LuckyJ

Analysis workspace for LuckyJ's Japanese mahjong games analyzed by NAGA.

Site: https://honvl.github.io/LuckyJ/ Japanese translation: https://honvl.github.io/LuckyJ/ja.html

Contents

• data/LuckyJ.csv - exported original game list.
• data/LuckyJ.xlsx - exported workbook copy.
• data/luckyj_analysis.json - generated aggregate and move-level summary from all linked NAGA reports.
• scripts/analyze_luckyj.py - fetches linked NAGA report JSONs, caches them locally, and generates the aggregate analysis.
• scripts/build_book_data.py - turns aggregate and move-level counters into site/book-data.json.
• scripts/extract_case_studies.py - replays closed-hand LuckyJ/NAGA discard disagreements with the mahjong shanten engine and writes site/case-studies.json.
• scripts/build_point_examples.py - mines ranked replay examples for each numbered principle and writes site/point-examples.json.
• scripts/build_mortal_analysis.py - locally replays the selected examples through Mortal/libriichi and writes site/mortal-analysis.json.
• scripts/mine_model_patterns.py - mines LuckyJ/NAGA mismatch families and optionally cross-checks a deterministic sample through Mortal.
• scripts/validate_points.py - maps every numbered point to statistical proxies and writes validation artifacts.
• analysis/model-patterns-2026-06-30.md - readable summary of the model-mined candidate points.
• analysis/point-evidence-2026-07-09.md - readable proxy-evidence audit for all numbered points.
• site/model-patterns.json - machine-readable output from the model-pattern mining run.
• site/point-validation.json - machine-readable validation data used by the English and Japanese static pages.
• site/strategy-guides.json - long-form strategic commentary for the numbered replay examples.
• site/strategy-guides.ja.json - Japanese commentary used by the translated static book.
• site/mortal-analysis.ja.json - Japanese Mortal panel copy used by the translated static book.
• site/mortal-analysis.json - compact Mortal cross-check output used by the static site.
• site/points.html - full English playbook; site/index.html is the shorter concept overview.
• site/ - static online book.

Raw analyzer caches, the Mortal repo checkout, model weights, Mjai logs, and local hand-review source files stay local. The analyzer cache is about 1.2 GB and can be regenerated by rerunning the analyzer.

Rebuild

From the repo root:

.venv/bin/python scripts/analyze_luckyj.py
.venv/bin/python scripts/build_book_data.py
.venv/bin/python scripts/extract_case_studies.py
.venv/bin/python scripts/build_point_examples.py
.venv/bin/python scripts/validate_points.py

Example selection prefers frames where at least one NAGA head (and, when known from site/mortal-analysis.json, Mortal) backs LuckyJ's line, with per-point diversity caps on (stage, score band) and games. Because Mortal verdicts feed selection, a fresh selection pass converges in two rounds: rebuild examples, run the Mortal replay, rebuild examples again. After the final Mortal replay, refresh the evidence badges without changing the selected frames:

.venv/bin/python scripts/build_point_examples.py --refresh-evidence-only

Per-example commentary is generated by scripts/generate_llm_guides.py (prompt version pro-voice-v3, professional-commentator voice, Mortal verdict fed into the prompt) against a local OpenAI-compatible proxy on localhost:8317:

CLIPROXY_API_KEY=... .venv/bin/python scripts/generate_llm_guides.py --workers 6

The "Prescriptions" section (numeric thresholds in site/points.html / site/ja.html) is backed by miners over the raw NAGA cache; each writes a JSON summary with per-cell n counts used to hand-write the section. The current prescription tables use the rx3 child-only outputs, where LuckyJ is not start-of-kyoku oya/dealer:

.venv/bin/python scripts/mine_rx3_honors.py   # child-only lone-yakuhai/guest-wind timing
.venv/bin/python scripts/mine_rx3_defense.py  # child-only >5%-danger discard proxies by threat class
.venv/bin/python scripts/mine_rx3_riichi.py   # child-only declare thresholds and late danger proxies
.venv/bin/python scripts/mine_rx3_calls.py    # child-only yakuhai pon and chi reluctance

The mined summaries behind the published numbers are archived under analysis/rx3-*-2026-07-05.json. The older analysis/rx-*-2026-07-03.json files are kept as first-pass all-seat references, not as the current prescription source.

The Mortal cross-check is optional because it depends on local-only assets under ~/Downloads:

uv pip install --python .venv/bin/python numpy torch maturin
# Install Equim-chan Mortal/libriichi locally, then run:
.venv/bin/python scripts/build_mortal_analysis.py

The broader model-pattern mining pass is optional. The default published artifact uses NAGA-side statistics only; Mortal replay can be enabled manually for smaller cross-check samples.

.venv/bin/python scripts/mine_model_patterns.py --no-mortal --output site/model-patterns.json

Create the local environment with:

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

The book needs a local server because it fetches JSON files:

.venv/bin/python -m http.server 8000 -d site

Then open http://127.0.0.1:8000/.

Sources

• Original game list: https://docs.google.com/spreadsheets/d/1jV-fi6E-z8BFdbS_LPfvpktSw8qc68PSZj9iEgdUC9U/edit?usp=drivesdk
• LuckyJ training description: https://www.tencent.com/en-us/articles/2201746.html (self-play; Tokujou was the public live test environment)
• Format reference: https://natsuai.com/mahjong/digital/