yijing-divination

I Ching Divination

A divination system based on the Zhouyi. Provides traditional hexagram-casting methods and an AI interpretation engine.

Core Features

1. Casting Methods

Coin method (recommended)

python3 scripts/divine.py --method coin --question "用户的问题"

Yarrow stalk method

python3 scripts/divine.py --method yarrow --question "用户的问题"

Custom seed

python3 scripts/divine.py --method coin --seed "20260214"

2. Output Structure

The script returns JSON, including:

• main_hexagram: Primary hexagram (main hexagram)
  • number: Hexagram number (1-64)
  • upper_trigram: Upper trigram (one of the eight trigrams)
  • lower_trigram: Lower trigram (one of the eight trigrams)
  • lines: Array of six lines (1=yang, 0=yin)
  • changing_lines: Changing line positions (moving lines)
  • visual: Hexagram visualization
• nuclear_hexagram: Nuclear hexagram (hidden hexagram)
• relating_hexagram: Transformed hexagram (only exists when there are moving lines)

3. Hexagram Text Database

Read assets/hexagrams_full.json to get hexagram interpretations:

import json
with open('assets/hexagrams_full.json', 'r') as f:
    hexagrams = json.load(f)

hex_data = hexagrams[str(卦序号)]

Each hexagram includes:

• name: Hexagram name
• judgement: Hexagram text
• image: Image text
• oracle_voice: AI Oracle voice (speaking in the first person of the hexagram)
• keywords: Keywords
• lines: Line texts for the six lines

4. Oracle Voice Mode

Core principles:

• Speak in the voice of the hexagram, rather than giving advice
• Use imagery and paradox, rather than prescriptions
• Hold tension, do not force resolution
• Make the act of asking itself part of the answer

Example template:

我是 {卦名}，{卦象描述}。

{oracle_voice 内容}

你的问题是「{用户问题}」。

{结合动爻和变卦的诠释}

{互卦的隐喻}

这是《易》给你的镜子，而非答案。

Complete Process

Step 1: Run the casting script

result=$(python3 scripts/divine.py --method coin --question "{用户问题}")

Step 2: Parse the result

import json
data = json.loads(result)
main_num = data['main_hexagram']['number']
nuclear_num = data['nuclear_hexagram']
relating_num = data['relating_hexagram']
changing = data['main_hexagram']['changing_lines']
visual = data['main_hexagram']['visual']

Step 3: Read the hexagram data

with open('references/hexagrams.json', 'r') as f:
    hexagrams = json.load(f)

main_hex = hexagrams[str(main_num)]
nuclear_hex = hexagrams.get(str(nuclear_num))
relating_hex = hexagrams.get(str(relating_num)) if relating_num else None

Step 4: Generate the Oracle Voice interpretation

Structure:

1. Hexagram display

   • Visualized hexagram (visual）
   • Hexagram name, hexagram text, image text

2. Oracle Voice

   • Voice of the primary hexagram (oracle_voice）
   • Interpretation combined with the user's question

3. Moving line interpretation(if any)

   • Moving line text
   • Meaning of the transformed hexagram

4. Nuclear hexagram prompt

   • Hidden forces
   • Potential trends

5. Closing

   • End with poetic language
   • Remind that this is a mirror rather than an answer

Example:

卦象：
{visual}

本卦：{卦号} {卦名}
卦辞：{judgement}
象辞：{image}

━━━━━━

{oracle_voice}

你问「{问题}」，而我以 {动爻位置} 动。

{动爻爻辞}

这一动，指向 {变卦名}。{变卦的oracle_voice片段}

━━━━━━

内卦（互卦）：{互卦名}
{互卦的隐喻含义}

━━━━━━

《易》不给你答案，只给你看见的方式。
你的问题本身，已经是答案的开始。

Notes

1. The current database contains only 10 hexagram examples(1 Qian, 2 Kun, 3 Zhun, 4 Meng, 5 Xu, 6 Song, 7 Shi, 8 Bi, 63 Jiji, 64 Weiji). If the hexagram number is not in the database, inform the user and provide a basic interpretation.

2. Oracle Voice principles

   • Do not say "you should..." or "I suggest you..."
   • Use "I am...", "My teaching is..."
   • Maintain poetic quality and ambiguity
   • Let the user think for themselves

3. Number of moving lines

   • No moving lines: focus on the primary hexagram
   • 1 moving line: focus the interpretation on that line
   • 2 moving lines: look at the relationship between the two lines
   • 3 moving lines: focus on the primary hexagram, refer to the transformed hexagram
   • 4 or more moving lines: focus on the transformed hexagram

4. The role of the nuclear hexagram

   • Show potential trends
   • Reveal hidden motivations
   • Not to be used as the primary interpretation

Extension

To modify the hexagram data, edit assets/hexagrams_full.json. Format example:

{
  "卦序号": {
    "name": "卦名",
    "unicode": "卦象符号",
    "structure": "六位二进制（1=阳，0=阴）",
    "judgement": "卦辞",
    "image": "象辞",
    "oracle_voice": "AI Oracle第一人称声音",
    "keywords": ["关键词"],
    "element": "五行/象征",
    "lines": ["初爻", "二爻", "三爻", "四爻", "五爻", "上爻"]
  }
}