Open-source Riichi Mahjong AI. The goal is to build an AI that rivals LuckyJ (Tencent, 10.68 stable dan on Tenhou) with open weights.
This research used the Delta advanced computing and data resource, which is supported by the National Science Foundation (award OAC 2005572) and the State of Illinois. Delta is a joint effort of the University of Illinois Urbana-Champaign and its National Center for Supercomputing Applications.
Train a mahjong AI that:
- Surpasses Mortal (~7-dan) and approaches LuckyJ-level play (10+ dan) in head-to-head evaluation
- Releases weights under a permissive license
- Adds opponent modeling and inference-time search — the two capabilities that separate LuckyJ from all other mahjong AIs
Hydra uses a layered authority flow built from the archive handoff canon upward:
research/agent_handoffs/ARCHIVE_CANONICAL_CLAIMS.jsonl— epistemic root / canonical archive SSOT for upstream research conclusionsresearch/agent_handoffs/ARCHIVE_CANONICAL_CLAIMS_ROADMAP.mdandresearch/agent_handoffs/ARCHIVE_CANONICAL_CLAIMS_RENDERED.md— derived archive views over that canonical source ledgerresearch/design/HYDRA_FINAL.md— promoted architecture doctrine built from archive canon plus repo validationresearch/design/HYDRA_RECONCILIATION.md— promoted operational doctrine and roadmap to Hydra v1 built from archive canon plus repo validationdocs/CURRENT_STATUS.md— promoted current-status snapshot for already-built repo surfacesdocs/GAME_ENGINE.mdanddocs/COMPATIBILITY_SURFACE.md— runtime semantics and compatibility surfaces; current code wins when docs drift
Hydra's documentation split is simple:
HYDRA_FINAL.mddescribes the max-ceiling destinationHYDRA_RECONCILIATION.mdis the roadmap to Hydra v1docs/CURRENT_STATUS.mdsays what is already shipped or still staged today
Raw answer_*_combined.md files in research/agent_handoffs/combined_all_variants/ remain raw archive corpus, not promoted doctrine.
If you are entering Hydra with zero prior memory, use this order and stop when you have enough truth for the task:
README.mdfor repo routingresearch/agent_handoffs/ARCHIVE_CANONICAL_CLAIMS.jsonlfor canonical archive intakeresearch/agent_handoffs/ARCHIVE_CANONICAL_CLAIMS_ROADMAP.mdfor derived archive triageresearch/design/HYDRA_RECONCILIATION.mdfor the roadmap to Hydra v1research/design/HYDRA_FINAL.mdfor the long-term ceilingdocs/CURRENT_STATUS.mdfor shipped/staged truthdocs/GAME_ENGINE.mdanddocs/COMPATIBILITY_SURFACE.mdfor runtime truth
combined_all_variants/ remains raw archive corpus for provenance only.
For implementation work, choose the next lane from
research/design/HYDRA_RECONCILIATION.md, confirm whether it already exists in
docs/CURRENT_STATUS.md, and confirm exact runtime contracts in
docs/GAME_ENGINE.md plus current code.
| Term | Meaning |
|---|---|
active path |
what Hydra should optimize/build now |
shipped baseline |
implemented and part of the current live baseline |
implemented but not default-on |
implemented in code, intentionally not the default path |
implemented but staged |
implemented enough to exist, but activation/promotion is intentionally deferred |
reserve shelf |
preserved later-work direction, not current mainline |
blocked |
not ready because a real dependency or semantic gap remains |
rejected |
not part of the current plan |
historical |
preserved context only; not governing truth |
| Crate | Owns | Does not own |
|---|---|---|
crates/hydra-engine |
vendored rules engine behavior | Hydra-specific runtime/training orchestration |
crates/hydra-core |
runtime bridge, encoder, simulator, seeding, search/runtime feature plumbing | Burn training logic or vendored rules ownership |
crates/hydra-train |
model, targets, losses, BC/RL/self-play orchestration, train binary | low-level rules engine behavior |
If you are deciding what to build next, follow the Fresh-agent routing order above.
research/design/HYDRA_SPEC.md remains historical context only.
| File | What's In It |
|---|---|
| ARCHIVE_CANONICAL_CLAIMS.jsonl | Epistemic root / canonical archive SSOT for upstream research intake |
| ARCHIVE_CANONICAL_CLAIMS_ROADMAP.md | Derived archive prioritization view over canonical archive claims |
| ARCHIVE_CANONICAL_CLAIMS_RENDERED.md | Generated human-readable mirror of the canonical archive ledger |
| HYDRA_FINAL.md | Promoted architecture doctrine summary |
| HYDRA_RECONCILIATION.md | Promoted operational doctrine summary and roadmap to Hydra v1 |
| HYDRA_ARCHIVE.md | Reserve-only design/archive planning surfaces |
| HYDRA_SPEC.md | Historical architecture spec only |
| MORTAL_ANALYSIS.md | Mortal's architecture, training details, confirmed weaknesses |
| OPPONENT_MODELING.md | Opponent-modeling rationale; includes both active ideas and reserve/future extensions |
| INFRASTRUCTURE.md | Rust stack, data pipeline, training infra, hardware, deployment |
| SEEDING.md | RNG hierarchy, reproducibility, evaluation seed bank |
| CHECKPOINTING.md | Checkpoint format, save protocol, retention policy |
| ECOSYSTEM.md | Useful repos, tooling, and framework references |
| REWARD_DESIGN.md | Reward design and RVR notes |
| COMMUNITY_INSIGHTS.md | Community observations and external signals |
| REFERENCES.md | Citation index |
| TESTING.md | Testing strategy, correctness verification, property-based tests |
| RUST_STACK.md | 100% Rust decision and framework notes |
Hydra is in active implementation. For the current shipped/staged repo snapshot, read docs/CURRENT_STATUS.md. For runtime semantics and compatibility-sensitive invariants, read docs/GAME_ENGINE.md and docs/COMPATIBILITY_SURFACE.md.
If you need to run or debug the training stack rather than read the architecture docs first, start here:
docs/TRAINING_WORKFLOWS.md— training entry modes, YAML contract, BC/RL shape, and sidecar-enabled trainingdocs/PREFLIGHT_AND_RUNTIME_SELECTION.md— preflight cache, selected-runtime authority, probe flows, and runtime reuse rulesdocs/REPLAY_SIDECARS.md— ExIt/DeltaQ sidecar generation and replay-time hydration contractsdocs/MJAI_AUDIT_AND_FAILURE_TRIAGE.md— replay corpus validation, failure inventories, and triage toolingdocs/BC_SHARDS.md— BC shard production, manifest interpretation, and training consumptiondocs/DELTAQ_PROMOTION.md— DeltaQ promotion gates, arena confirmation, and artifact interpretationdocker/train/README.md— container execution contract
Hydra uses cargo nextest run --release as the default workspace test path and cargo-llvm-cov for workspace-wide coverage reporting. For local coverage generation details, read docs/COVERAGE.md.
- hydra-core (encoder, training pipeline): BSL 1.1 -- free for non-commercial use, converts to Apache-2.0 on 2031-03-02
- hydra-engine (game rules): Apache-2.0 (vendored from riichienv-core)