← all skills

iching-api-reading

/home/avalon/.hermes/skills/software-development/iching-api-reading/SKILL.md · raw

I Ching API Reading

When to use

Use this when Alex asks Hermes to do an I Ching reading using the app/server, especially when he wants an API-like operation rather than an in-chat randomization.

App location

Core method

API endpoints

Throw one line

curl -sS -X POST http://127.0.0.1:4017/api/divination/throw-line

Returns one line object:

{
  "line": {
    "coins": ["heads", "tails", "heads"],
    "total": 8,
    "line": 0,
    "changing": false,
    "lineKind": "young_yin"
  },
  "note": "One three-coin cast..."
}

Resolve a six-line reading

curl -sS -X POST http://127.0.0.1:4017/api/divination/reading \
  -H 'Content-Type: application/json' \
  --data '{"lines":[LINE1,LINE2,LINE3,LINE4,LINE5,LINE6]}'

Returns: - lines: cast lines, bottom-up - primaryHexagram: source/oracle hexagram - relatingHexagram: changed/resulting hexagram - changingLineNumbers: bottom-up line numbers whose totals were 6 or 9 - relatingLines: line stack after flips - guidance: method note

Time context (required)

Before casting, capture the querent's local wall-clock time so the reading can be anchored honestly (e.g. "morning", "tonight", planetary hour, Moon degree). Do NOT infer time from words in the user's message (the voice transcriber renders "I Ching" as "night-ching" — that is not a time signal).

Use the user's profile timezone (Alex = America/Los_Angeles):

TZ=America/Los_Angeles date '+%Y-%m-%d %H:%M %Z (%A)'

Record that timestamp and only use day/night framing if the hour actually supports it. If no profile TZ is known, ask or fall back to UTC and say so.

Required operating workflow

Run the reading from a tool, not mentally. Two modes:

Pick the mode based on the user's wording. When in doubt for a real divination question, use ritual mode.

Ritual mode (default)

from hermes_tools import terminal
import json, random, time, shlex

base = 'http://127.0.0.1:4017'
lines = []
for i in range(6):
    r = terminal(f'curl -sS -X POST {base}/api/divination/throw-line', timeout=30)
    obj = json.loads(r['output'])
    lines.append(obj['line'])
    if i < 5:
        time.sleep(random.uniform(2.0, 8.0))  # ritual gap

payload = json.dumps({'lines': lines})
r = terminal(
    "curl -sS -X POST -H 'Content-Type: application/json' --data "
    + shlex.quote(payload)
    + f' {base}/api/divination/reading',
    timeout=30,
)
reading = json.loads(r['output'])
print(json.dumps(reading, indent=2, ensure_ascii=False))

Fast mode

No sleeps. Six quick throws + one resolve call:

from hermes_tools import terminal
import json, shlex

base = 'http://127.0.0.1:4017'
lines = []
for i in range(6):
    r = terminal(f'curl -sS -X POST {base}/api/divination/throw-line', timeout=30)
    lines.append(json.loads(r['output'])['line'])

payload = json.dumps({'lines': lines})
r = terminal(
    "curl -sS -X POST -H 'Content-Type: application/json' --data "
    + shlex.quote(payload)
    + f' {base}/api/divination/reading',
    timeout=30,
)
reading = json.loads(r['output'])
print(json.dumps(reading, indent=2, ensure_ascii=False))

Interpretation formatting

Structure (top to bottom):

  1. Time stamp line. A single italic line with the actual wall-clock cast time (see Time context). No day/night framing unless the hour supports it.

  2. The casts — at the very top, stacked visually like the hexagram. Display line 6 at the TOP and line 1 at the BOTTOM (matches how a hexagram is read). Each line: Line N: total kind ⚊/⚋ and mark changing lines with — changing. Example layout: Line 6 (top): 6 old yin ⚋ — changing Line 5: 8 young yin ⚋ Line 4: 8 young yin ⚋ Line 3: 7 young yang ⚊ Line 2: 8 young yin ⚋ Line 1 (bot): 7 young yang ⚊

  3. Hexagram header block — directly under the casts. Show the primary hexagram (and the relating hexagram if there are changing lines) as a compact header: character glyph, number, English name, Chinese + pinyin. No changing-line annotation here — it's already visible in the cast stack. Example: ䷣ 36 — Darkening of the Light · 明夷 (míng yí) → ䷕ 22 — Grace · 賁 (bì)

  4. 🪙 The Reading (composite story — CONDENSED). One tight paragraph (roughly half the length of a long-form synthesis — aim for ~4–7 sentences total, not three full paragraphs). Fuse: primary situation + what the moving line(s) inflect + trajectory into the relating hexagram. Skip the relating trajectory if there are no changing lines.

  5. Primary hexagram — expanded. Trigrams above/below, Judgment, Image, and a richer interpretive paragraph drawing on the Wilhelm text and the explanation.overview. Go deeper here than in the top story.

  6. Moving line(s) — expanded. For each changing line: quote the Wilhelm text in full, then give an expanded reading of what that specific line means inside the primary hexagram's situation (positional meaning, symbolism, the inflection it introduces). If no moving lines, say "No moving lines — the primary stands as the whole answer."

  7. Relating hexagram — expanded (only if changing lines exist). Trigrams, Judgment, and a richer paragraph on it as the direction/outcome/transformed field. Still do NOT quote its individual line texts unless explicitly asked.

  8. One-breath summary. A single bold one-to-three-sentence summation at the very bottom.

Stay grounded in the API response — never invent hexagram numbers, line texts, casts, or time framing the data doesn't support.

Verification