# yaomancy/liuyao-engine architecture

> Architecture diagram of the GitHub repository yaomancy/liuyao-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaomancy/liuyao-engine
- Repository: https://github.com/yaomancy/liuyao-engine

## Overview

#### Purpose and Public Entry Points
`liuyao-engine` is a Python 3.11+ deterministic Liù Yáo chart-construction engine. It converts a coin cast and timestamp into structured divination facts, not interpretive or AI-generated advice. The package public surface is rooted in `liuyao/__init__.py`: `toss`, `compute_four_pillars`, `cast_chart`, and `build_reading`.

#### 1. Cast Acquisition
`liuyao/cast.py` represents six-line casts and generates coin tosses using CSPRNG-derived outcomes. Its result preserves primary-hexagram bits and moving-line state, which feed both primary and changed charts. The engine can also accept caller-provided bits/moving lines, keeping casting separate from chart assembly.

#### 2. Calendar and Four-Pillars Boundary
`liuyao/calendar.py` converts a local timestamp into the gan-zhi year, month, day, and hour pillars, including xúnkōng. This is the principal external-runtime boundary: it depends on `sxtwl` for Chinese calendrical calculations; tests validate timezone and day-boundary behavior. The resulting `FourPillars` data is passed into chart construction rather than having downstream modules query time.

#### 3. Hexagram Identity, Transformations, and Metadata
`liuyao/hexagram.py` maps line bits to one of 64 hexagrams and derives changed hexagrams from moving lines. `liuyao/guaxiang.py` supplies hexagram/palace-oriented facts, while `liuyao/gua_slug.py` and `liuyao/gua_page.py` support stable naming/page-oriented representations. These modules establish the canonical identity boundary before rule attribution.

#### 4. Najia Chart Assembly
`liuyao/analysis.py` and `liuyao/relations.py` assemble the rule-derived chart: nàjiǎ stem/branch attribution, five-element relationships, six relations, six spirits, shì/yìng positions, and fúshén. `liuyao/chizhi.py` provides Heavenly Stem/Earthly Branch and five-element domain primitives. `cast_chart` produces a structured `HexagramChart` from primary bits plus the day stem, making this stage deterministic and independent of question text.

#### 5. Strength and Use-God Analysis
`liuyao/analysis.py` derives the wàng-shuāi skeleton from chart facts and time context, then identifies yòngshén according to question category. This is a deliberate scope boundary: it encodes hard, inspectable rule outputs but excludes free-form divinatory interpretation and shénshà.

#### 6. Reading Composition and Output Contract
`liuyao/reading.py` is the orchestration layer behind `build_reading`. It combines question metadata, four pillars, palace and hexagram relations, primary/changed charts, yòngshén, and assessment into plain Python dictionaries. Its externally meaningful output shape is anchored by `cases/hexagram-json-contract.md`; callers can serialize it without framework, database, network, or I/O coupling.

#### 7. Rules, Reference Data, and Verification
Rules are implemented in package modules and audited against reference assets, especially `data/yigram-najia-tables.json`. `data/liuyao-glossary.json` preserves domain terminology; classical sources in `data/卜筮正宗_ctext公有领域全文.txt` and `data/增删卜易_ctext公有领域全文.txt` are reference material rather than runtime services. CI in `.github/workflows/ci.yml` runs regression and differential checks, including comparison against the independent `najia` implementation. The only material runtime dependency is `sxtwl`; the engine otherwise operates locally with no network access.

Main entry points: [`liuyao/analysis.py`](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/analysis.py) (Nàjiǎ chart assembly), [`liuyao/reading.py`](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/reading.py) (Reading composition), [`liuyao/calendar.py`](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/calendar.py) (Four Pillars), [`liuyao/__init__.py`](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/__init__.py) (Package exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_package_api["Package exports<br/>Python API<br/>[__init__.py]"]
end

subgraph group_engine["Deterministic Engine"]
  node_cast["Cast acquisition<br/>cast model<br/>[cast.py]"]
  node_csprng(("CSPRNG coin tosses<br/>random source"))
  node_calendar["Four Pillars<br/>calendar adapter<br/>[calendar.py]"]
  node_hexagram["Hexagram transforms<br/>identity rules<br/>[hexagram.py]"]
  node_guaxiang["Palace facts<br/>hexagram metadata<br/>[guaxiang.py]"]
  node_slug_page["Stable gua representations<br/>naming metadata<br/>[gua_slug.py]"]
  node_chart["Nàjiǎ chart assembly<br/>chart rules<br/>[analysis.py]"]
  node_relations["Relations &amp; positions<br/>rule attribution<br/>[relations.py]"]
  node_chizhi["Stem, branch &amp; elements<br/>domain primitives<br/>[chizhi.py]"]
  node_strength["Strength &amp; use-god<br/>assessment rules<br/>[analysis.py]"]
  node_reading["Reading composition<br/>orchestrator<br/>[reading.py]"]
end

subgraph group_references["Rules &amp; Verification"]
  node_najia_tables[("Nàjiǎ reference tables<br/>reference data")]
  node_output_contract["JSON output contract<br/>contract document"]
  node_ci["Regression &amp; differential CI<br/>verification pipeline<br/>[ci.yml]"]
end

node_sxtwl{{"sxtwl<br/>external dependency"}}

node_package_api -->|"toss"| node_cast
node_package_api -->|"compute_four_pillars"| node_calendar
node_package_api -->|"cast_chart"| node_chart
node_package_api -->|"build_reading"| node_reading
node_csprng -->|"coin outcomes"| node_cast
node_sxtwl -->|"calendar calculations"| node_calendar
node_cast -->|"bits and moving lines"| node_hexagram
node_hexagram -->|"canonical identity"| node_guaxiang
node_hexagram -->|"hexagram identity"| node_slug_page
node_chizhi -->|"stems, branches, elements"| node_relations
node_guaxiang -->|"palace facts"| node_chart
node_relations -->|"attributions"| node_chart
node_hexagram -->|"primary hexagram"| node_chart
node_calendar -->|"day stem"| node_chart
node_chart -->|"chart facts"| node_strength
node_calendar -->|"time context"| node_strength
node_chart -->|"primary and changed charts"| node_reading
node_calendar -->|"four pillars"| node_reading
node_strength -->|"assessment and yòngshén"| node_reading
node_guaxiang -->|"palace relations"| node_reading
node_najia_tables -.->|"audits rules"| node_chart
node_output_contract -.->|"output shape"| node_reading
node_ci -.->|"validates mappings"| node_najia_tables
node_ci -.->|"regression checks"| node_reading

click node_package_api "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/__init__.py"
click node_cast "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/cast.py"
click node_calendar "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/calendar.py"
click node_hexagram "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/hexagram.py"
click node_guaxiang "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/guaxiang.py"
click node_slug_page "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/gua_slug.py"
click node_chart "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/analysis.py"
click node_relations "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/relations.py"
click node_chizhi "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/chizhi.py"
click node_strength "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/analysis.py"
click node_reading "https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/reading.py"
click node_najia_tables "https://github.com/yaomancy/liuyao-engine/blob/main/data/yigram-najia-tables.json"
click node_output_contract "https://github.com/yaomancy/liuyao-engine/blob/main/cases/hexagram-json-contract.md"
click node_ci "https://github.com/yaomancy/liuyao-engine/blob/main/.github/workflows/ci.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package_api toneBlue
class node_cast,node_csprng,node_calendar,node_hexagram,node_guaxiang,node_slug_page,node_chart,node_relations,node_chizhi,node_strength,node_reading toneAmber
class node_najia_tables,node_output_contract,node_ci toneMint
class node_sxtwl toneNeutral
```

## Components

### Public API

- [Package exports](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/__init__.py): Python API · Exports toss, compute_four_pillars, cast_chart, and build_reading. · `liuyao/__init__.py`

### Deterministic Engine

- [Cast acquisition](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/cast.py): cast model · Represents six lines, primary bits, and moving-line state. · `liuyao/cast.py`
- **CSPRNG coin tosses**: random source
- [Four Pillars](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/calendar.py): calendar adapter · Converts local timestamps to pillars and xúnkōng. · `liuyao/calendar.py`
- [Hexagram transforms](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/hexagram.py): identity rules · Maps bits to canonical primary and changed hexagrams. · `liuyao/hexagram.py`
- [Palace facts](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/guaxiang.py): hexagram metadata · `liuyao/guaxiang.py`
- [Stable gua representations](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/gua_slug.py): naming metadata · `liuyao/gua_slug.py`
- [Nàjiǎ chart assembly](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/analysis.py): chart rules · Builds HexagramChart from primary bits and day stem. · `liuyao/analysis.py`
- [Relations & positions](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/relations.py): rule attribution · Derives relations, spirits, shì/yìng, and fúshén. · `liuyao/relations.py`
- [Stem, branch & elements](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/chizhi.py): domain primitives · `liuyao/chizhi.py`
- [Strength & use-god](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/analysis.py): assessment rules · Derives wàng-shuāi and question-category yòngshén. · `liuyao/analysis.py`
- [Reading composition](https://github.com/yaomancy/liuyao-engine/blob/main/liuyao/reading.py): orchestrator · Produces plain Python dictionaries without I/O coupling. · `liuyao/reading.py`

### Rules & Verification

- [Nàjiǎ reference tables](https://github.com/yaomancy/liuyao-engine/blob/main/data/yigram-najia-tables.json): reference data · Audits implemented rule mappings. · `data/yigram-najia-tables.json`
- [JSON output contract](https://github.com/yaomancy/liuyao-engine/blob/main/cases/hexagram-json-contract.md): contract document · Defines the externally meaningful reading shape. · `cases/hexagram-json-contract.md`
- [Regression & differential CI](https://github.com/yaomancy/liuyao-engine/blob/main/.github/workflows/ci.yml): verification pipeline · Checks regressions and an independent najia implementation. · `.github/workflows/ci.yml`

### Other components

- **sxtwl**: external dependency · Chinese calendrical calculation runtime.

## Connections

- Package exports → Cast acquisition: toss
- Package exports → Four Pillars: compute_four_pillars
- Package exports → Nàjiǎ chart assembly: cast_chart
- Package exports → Reading composition: build_reading
- CSPRNG coin tosses → Cast acquisition: coin outcomes
- sxtwl → Four Pillars: calendar calculations
- Cast acquisition → Hexagram transforms: bits and moving lines
- Hexagram transforms → Palace facts: canonical identity
- Hexagram transforms → Stable gua representations: hexagram identity
- Stem, branch & elements → Relations & positions: stems, branches, elements
- Palace facts → Nàjiǎ chart assembly: palace facts
- Relations & positions → Nàjiǎ chart assembly: attributions
- Hexagram transforms → Nàjiǎ chart assembly: primary hexagram
- Four Pillars → Nàjiǎ chart assembly: day stem
- Nàjiǎ chart assembly → Strength & use-god: chart facts
- Four Pillars → Strength & use-god: time context
- Nàjiǎ chart assembly → Reading composition: primary and changed charts
- Four Pillars → Reading composition: four pillars
- Strength & use-god → Reading composition: assessment and yòngshén
- Palace facts → Reading composition: palace relations
- Nàjiǎ reference tables → Nàjiǎ chart assembly: audits rules
- JSON output contract → Reading composition: output shape
- Regression & differential CI → Nàjiǎ reference tables: validates mappings
- Regression & differential CI → Reading composition: regression checks