How robbyshao-8ag/yice works
1. Repository shape
- This is a Python-first decision-analysis system with two user-facing runtimes: a CLI app at main.py and a web app under web/.
- The core product logic lives in core/ and agents/; the rest is supporting data, tests, and generation scripts.
2. Primary domain flow
- The central workflow is: user question → clarification → scene classification → six-line analysis → report synthesis.
- The README describes this as a multi-agent “六爻” pipeline, and the code structure matches that: QiguaAgent, SceneRouter, YaoAgents, and Reporter.
3. Agent orchestration layer
- agents/ contains the conversational and reasoning roles:
- qigua_agent.py handles question elicitation / divination-style intake.
- question_analyzer.py and sufficiency_checker.py support whether the question is clear enough to proceed.
- scene_router.py chooses a scenario/hexagram category.
- yao_agents.py and option_generator.py drive the six parallel line-level analyses.
- reporter.py assembles the final decision report.
- This layer is the business logic boundary where LLM calls are coordinated.
4. Core calculation and rule engine
- core/ holds the deterministic domain logic around hexagrams and lines:
- bian_gua.py for changing-hexagram logic,
- hu_gua.py for inter-hexagram derivation,
- yao_math.py for line/position calculations,
- liu_shou.py, hexagram_relations.py, and related modules for traditional relationship rules.
- This layer is the non-LLM “engine” that turns symbolic inputs into structured context for agents.
5. Data model and loading
- Static knowledge is stored in data/*.json, including hexagrams, lines, scene mappings, yao attributes, and reference relations.
- core/data_loader.py loads this data, while core/models.py defines the structured objects used across the pipeline.
- core/config_validator.py validates runtime configuration, especially model/provider settings.
6. LLM and external service boundary
- core/llm_client.py is the main integration point to external model providers.
- The README shows provider/model configuration in models.json, which means the system is designed to swap LLM backends per agent rather than hard-coding a single model.
- This is the key external dependency boundary: the reasoning pipeline is local, but generation steps depend on remote LLM APIs.
7. CLI runtime
- main.py is the simplest entrypoint for local execution.
- The README emphasizes a zero-dependency CLI path, so the CLI likely exercises the same core pipeline without the web frontend.
- For architecture diagrams, treat this as a thin shell around core.pipeline and the agent layer.
8. Web runtime
- web/main.py launches a separate web stack with a Python backend and a Vue/TypeScript frontend.
- web/backend/ exposes route handlers for config, history, and websocket dialogue; services/agent_bridge.py likely adapts backend requests into the core agent pipeline.
- web/frontend/ is a SPA built with Vue, Vite, TypeScript, stores, router, and a websocket client.
9. Real-time interaction model
- The web app appears to use WebSocket-based dialogue for interactive questioning and staged analysis, not just one-shot requests.
- web/backend/routes/websocket.py plus web/frontend/src/services/websocket.ts indicate streaming or stepwise updates during the divination/reporting process.
- This matters because the user experience is conversational and incremental, not a single synchronous response.
10. Persistence and history
- There is no obvious database in the tree; persistence is mostly file-based and transient.
- Web-specific history support exists via web/backend/routes/history.py, suggesting session or conversation history is managed at the application layer, likely in memory or simple storage rather than a full DB.
11. Testing and quality control
- The tests/ directory is broad and highly specific: agent collaboration, pipeline, websocket dialogue, CLI, data integrity, hexagram rules, and LLM client behavior.
- This indicates the architecture is heavily verified at both the deterministic-rule level and the orchestration level.
- The tests/fixtures/reference/ JSON files serve as canonical truth data for symbolic calculations.
12. Build, maintenance, and CI
- .github/workflows/ci.yml provides continuous integration, and the scripts/ folder contains data-generation and repair utilities.
- Those scripts suggest part of the system’s “source of truth” is generated or normalized data, not just hand-written code.
- For an architecture diagram, treat scripts/ as the offline data-preparation layer feeding the runtime JSON knowledge base.
13. Key boundaries to draw
- One boundary is between symbolic/domain logic (core/ + data/) and LLM-driven reasoning (agents/ + llm_client.py).
- Another boundary is between core engine and delivery channels: CLI vs web backend/frontend.
- The final boundary is local code vs external model APIs, since the system’s intelligence depends on remote providers but its structure and rules are local and deterministic.
Main entry points: pipeline.py Pipeline · yao_agents.py Yao Agents · llm_client.py LLM Client · main.py Web Backend
Components 28
Delivery
CLI and web entrypoints exposed to users
- CLI · Command-line entrypoint for local runs
main.py
Orchestration
Question intake, routing, and report assembly
- Pipeline · Coordinates the end-to-end divination workflow
core/pipeline.py - Qigua · Collects and clarifies the user question
agents/qigua_agent.py - Analyzer · Checks whether the question is sufficiently clear
agents/question_analyzer.py - Scene Router · Maps the question to a scene or hexagram category
agents/scene_router.py - Yao Agents · Runs the six parallel line-level analyses
agents/yao_agents.py - Options · Generates candidate choices for analysis or response
agents/option_generator.py - Reporter · Assembles the final decision report
agents/reporter.py - LLM Client · Single integration point for external model providers
core/llm_client.py
Domain Engine
Deterministic hexagram and line calculations
- Relations · Traditional relationship rules for hexagrams and lines
core/hexagram_relations.py - Changing Gua · Computes the changing hexagram
core/bian_gua.py - Inter Gua · Derives the inter-hexagram structure
core/hu_gua.py - Yao Math · Calculates line and position values
core/yao_math.py - Liu Shou · Applies six-spirit relationship logic
core/liu_shou.py
Knowledge
Static reference data and loaders
- Models · Shared structured objects passed through the pipeline
core/models.py - Data Loader · Loads static hexagram and relation knowledge
core/data_loader.py - Config Validator · Checks runtime model and provider configuration
core/config_validator.py - Data JSON · Static hexagram, scene, and relation reference data
data/hexagrams.json
Web Stack
Backend API and Vue frontend
- Web Backend · Python backend for routes and dialogue orchestration
web/backend/main.py - Agent Bridge · Adapts web requests into the core pipeline
web/backend/services/agent_bridge.py - WebSocket · Handles staged conversational updates
web/backend/routes/websocket.py - History · Serves dialogue and session history
web/backend/routes/history.py - Config · Exposes configuration endpoints for the web app
web/backend/routes/config.py - Vue SPA · Single-page web client for interactive divination
web/frontend/src/App.vue - WS Client · Client-side websocket transport for dialogue
web/frontend/src/services/websocket.ts
Ops
Offline generation and verification
Other components
- Model APIs · Remote LLM providers used by the agents
Connections 33
- CLI → Pipeline: runs · CLI invokes the shared workflow
- Web Backend → Agent Bridge: delegates · Web backend hands requests to the core pipeline adapter
- Agent Bridge → Pipeline: invokes · Bridges web requests into the shared orchestration flow
- WebSocket → Agent Bridge: streams · WebSocket route drives incremental dialogue execution
- WS Client → WebSocket: connects · Frontend dialogue client talks to the backend websocket endpoint
- Pipeline → Qigua: asks · Pipeline starts by eliciting and clarifying the question
- Pipeline → Analyzer: checks · Ensures the question is clear enough to proceed
- Pipeline → Scene Router: routes · Selects the scenario or hexagram category
- Pipeline → Yao Agents: analyzes · Launches the six line-level analyses
- Pipeline → Reporter: synthesizes · Produces the final decision report
- Qigua → LLM Client: calls · Uses model calls for conversational intake
- Scene Router → Data Loader: reads · Uses reference mappings to classify the scene
- Scene Router → Relations: uses · Applies symbolic relation rules during routing
- Yao Agents → Yao Math: computes · Derives line-level positions and values
- Yao Agents → Changing Gua: derives · Builds changing-hexagram context
- Yao Agents → Inter Gua: derives · Builds inter-hexagram context
- Yao Agents → Liu Shou: applies · Adds six-spirit relationship context
- Yao Agents → LLM Client: calls · Combines deterministic context with model reasoning
- Reporter → Models: formats · Assembles structured output from shared models
- Reporter → LLM Client: calls · May use models for final synthesis and phrasing
- Pipeline → Models: passes · Pipeline moves typed objects between stages
- Data Loader → Data JSON: loads · Reads the static knowledge base
- Config Validator → Models: validates · Checks provider and model configuration against schema
- LLM Client → Model APIs: requests · External dependency boundary to remote model providers
- Web Backend → History: exposes · Serves conversation history endpoints
- Web Backend → Config: exposes · Serves configuration endpoints
- Web Backend → WebSocket: exposes · Serves interactive websocket dialogue
- Vue SPA → WS Client: uses · Frontend UI relies on websocket transport
- Scripts → Data JSON: generates · Offline scripts create and repair reference data
- Tests → Pipeline: verifies · Tests the main workflow end to end
- Tests → WebSocket: verifies · Tests interactive websocket dialogue behavior
- Tests → LLM Client: mocks · Validates provider integration behavior
- Tests → Data Loader: checks · Covers data loading and integrity rules