yaomancy/liuyao-engine

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.