crystal-9

Crystal-9 accepted artifacts v1

Crystal-9 is a clean-room, local 3×3 tic-tac-toe move-policy experiment. It is a small sparse Mixture-of-Experts policy model: shared token and position embeddings, causal multi-head attention, LayerNorm, a router, nine two-layer experts, and top-2 routing.

This package contains four accepted Crystal-9 artifacts: the immutable F32 reference, two independently validated packed-INT4 deployments, and a complete mixed-layout packed-INT3 deployment. It is not a Transformers checkpoint, GGUF, llama.cpp, or Ollama model; use the included custom Python runtime.

Need a GGUF or standard llama.cpp/Ollama compatibility? Try Palace-9, the earlier compatibility-focused predecessor to Crystal-9. Its published GGUF artifacts are the appropriate choice for those runtimes.

Accepted artifacts

Every listed artifact passed the exhaustive gate: 0 policy misses across 294,778 nonterminal legal histories. For each history, the selected move must match the minimax move selected under the validator's fixed tie order.

F32 reference

artifacts/artifacts-fp32.pt — immutable F32 source and evaluation baseline. 116,365 bytes · SHA-256: e5e3aa5eee…3537c34312b9399c

INT4 with FP32 scales

artifacts/crystal-9-int4-group2-packed-v1.pt — original accepted deployment: packed signed INT4 codes with FP32 dequantization scales. 46,547 bytes · SHA-256: 10fb96a66aaf…da12434a2c722b9f9

INT4 with FP16 scales

artifacts/crystal-9-int4-group2-packed-fp16-scales-v1.pt — accepted scale-compressed deployment: the same signed INT4-code layout with all 787 dequantization scales stored as FP16. 46,299 bytes · SHA-256: 63eee663a143…b2f5e329dacb1392eb

INT3 with mixed FP32 scales

artifacts/crystal-9-int3-packed-v1.pt — complete accepted deployment: packed signed INT3 codes with the recorded mixed FP32-scale layouts. 55,489 bytes · SHA-256: 2bc68216b05d…47747b2122174dc8574fc

This exact INT3 deployment is 9,190 bytes larger than the 46,299-byte INT4 artifact with FP16 scales because its mixed layout retains substantial FP32 scale overhead, including scalar-group tensors.

Full artifact digests, acceptance evidence, and source provenance are in release-manifest.json; SHA256SUMS verifies every shipped file.

The FP16-scale artifact is not a full-FP16 model. Its model codes remain INT4; only the explicit dequantization scales use FP16. It is 248 bytes (0.53%) smaller than the FP32-scale packed artifact.

A full-FP16 Crystal-9 model has not been created or accepted. The INT3 artifact is complete and accepted, but its mixed groups retain FP32 scales—especially scalar groups—so it is not claimed to be scale-storage-optimal. Its internal manifest is independently protected by SHA-256 5a27545c39fa2b327e25f8f62c4a16f4a820643cb3354ac36b4e97f2c115c58a.

INT2 exact-policy research artifact

artifacts/crystal-9-int2-packed-scalar-fp8-e4m3fn-scales.pt is included for reproducible review of a complete, behaviorally exact INT2 representation. Its signed INT2 codes are packed low-bit-first and its 24,726 scalar dequantization scales use float8_e4m3fn.

It passed 0 policy misses across 294,778 nonterminal legal histories in the independently packed runtime, and returns ! for the staged invalid/terminal examples. It is not an accepted compact deployment: at 64,525 bytes, it is larger than the accepted 46,299-byte INT4 artifact because it retains one scale per scalar. Use the INT4 FP16-scale artifact for the compact local deployment.

64,525 bytes · SHA-256: 0908e9953a43…e013bd7bb5105768235 · packed-manifest SHA-256: d438aca4987c0b2efd6b71e6776c42d919e4a8fd1caaa5a545490860aedd9d26

The shipped packed_int2.py runtime and validation/packed-int2-fp8-research-acceptance.json are specific to this research artifact. The release manifest keeps it separate from the four accepted deployment/reference artifacts.

Why Crystal-9 followed Palace-9

Palace-9 was the earlier compatibility-focused experiment: a Qwen2MoeForCausalLM model shaped for Transformers, llama.cpp, and Ollama chat tooling. That required a general-purpose byte-BPE vocabulary, a 16-token context, and architecture/configuration conventions intended for another model family. Those constraints were useful for proving compatibility, but they were not the most compact fit for a deterministic 3×3 move-history policy.

Crystal-9 uses the same deterministic tic-tac-toe training and evaluation data, but was redesigned around the task: a 32-wide hidden state, nine top-2 routed experts, an eight-move context, a 13-token game vocabulary, and exact packed-INT4 inference. It intentionally uses a custom local runtime rather than a llama.cpp/Ollama-compatible container.

The formats are not interchangeable. Palace-9's listed artifacts are Qwen2-MoE/Transformers or GGUF compatibility artifacts; Crystal-9's artifacts are a PyTorch F32 state dictionary and custom packed-INT4 containers. These comparisons document task-specific design tradeoffs, not loader compatibility.

The exact comparison inputs and byte counts are in validation/palace-9-comparison.json.

Tensor workflow

This is a decoded, non-reconstructable inspection of the full-parameter INT4 QAT checkpoint. It documents the tensor layout and QAT workflow; it is not a release label, model container, or substitute for either packed deployment artifact.

Netron inspection graph

inspection/crystal-9-f32-fixed8-inspection.onnx is a derived F32 ONNX graph for Netron. Keep its required crystal-9-f32-fixed8-inspection.onnx.data weight file beside it when transferring or opening it. The graph has one fixed int64 input, token_ids with shape [1, 8], and returns logits with shape [1, 13]. It exposes the attention, router/top-2 selection, all nine expert branches, routed merge, and output path that a packed artifact dictionary cannot show. It is inspection-only—not a Crystal-9 runtime or accepted deployment artifact. Its source binding and ONNX Runtime comparison are recorded in inspection/crystal-9-f32-fixed8-inspection-validation.json.

This clipped, indexed-color PNG preview is a derived rendering of that ONNX graph. The matching SVG retains zoomable vector detail. Both were generated from the ONNX file with Netron 9.2.9 by Lutz Roeder.

Input and output contract

Pass a raw history of board-square letters a through i in play order, with at most eight moves. The policy returns one square letter for a legal next move, or ! when the history is invalid or terminal.

The internal vocabulary is <pad>, <bos>, <eos>, !, and a–i. Only a–i are public input symbols.

Run locally

Use a current PyTorch installation. From this repository root:

python3 - <<'PY'
from crystal9 import GameTokenizer
from packed_int4 import PackedInt4Policy

runtime = PackedInt4Policy.load("artifacts/crystal-9-int4-group2-packed-fp16-scales-v1.pt").eval()
tokenizer = GameTokenizer.from_design_file("design.json")
print(runtime.predict("ae", tokenizer))
PY

To load the accepted INT3 artifact instead, change the two runtime lines to:

from packed_int3 import PackedInt3Policy
runtime = PackedInt3Policy.load("artifacts/crystal-9-int3-packed-v1.pt").eval()

To play the included terminal demo as X against Crystal-9 (O):

python3 -m pip install -r requirements.txt
python3 play_crystal9.py

The demo uses the accepted smaller INT4 artifact with FP16 dequantization scales. Enter one unoccupied a–i square per turn; the board prints as three rows containing ., x, and o, and the game stops at a win or draw. This is a local custom-runtime demo; it is not hosted inference.

To evaluate the four accepted staged artifacts and the separate INT2 research artifact on the exhaustive legal-history and invalid-input gates:

PYTHONDONTWRITEBYTECODE=1 python3 validation/verify_release.py

Integrity and provenance

release-manifest.json names every accepted artifact, its role, exact byte size, digest, and acceptance boundary. validation/release-acceptance.json is generated by the self-contained validation script against the staged copies.

Verify every distributable file (except SHA256SUMS itself):

sha256sum -c SHA256SUMS

SHA256SUMS detects changes after generation. It is not an authenticated signature; compare artifact digests in release-manifest.json with a trusted release reference.

Browser projection files are separate derivative representations and are not required by this Python runtime. The tensor workflow image is a decoded visualization, not a byte container.

Acknowledgments

CRYSTAL-9 was designed and directed by Lewis Moten. Its code and documentation were developed with assistance from GPT-5.6-terra Med, accessed through Hermes and using Honcho for context and project-memory support. Lewis Moten remains the project designer, maintainer, and publisher.

License

This package is licensed under Apache License 2.0.