quantik-models 1.0.0__tar.gz

quantik_models-1.0.0/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+Instructions for humans and AI agents working in this repository.
+
+## Read these first, in this order
+
+| | |
+|---|---|
+| [`README.md`](README.md) | what the package is and how it is used |
+| [`DEVELOPMENT.md`](DEVELOPMENT.md) | **environment, tests, CI, the release process, and the non-negotiable invariants.** Everything about working on this repository is there. |
+| [`docs/README.md`](docs/README.md) | the reading order for `docs/` |
+
+**Do not grep your way in.** This repository's hard-won conclusions are
+written down, and most of them are not derivable from the code — several are
+about measurements that turned out to be wrong. `DEVELOPMENT.md`'s
+"Invariants that are not negotiable" is the shortest path to not repeating
+one.
+
+## What is specific to working here as an agent
+
+**Verify before anything expensive.** Training runs and arenas cost hours,
+and this repository has paid more than once for skipping the smoke test.
+`DEVELOPMENT.md` has the rules; the shortest version is that a timing taken
+under load is an upper bound, often a wild one, and an average from a
+differently-shaped workload does not transfer.
+
+**Say what you actually ran.** `mypy` is a gate now, but claiming a check
+passed without running it has happened here. So has drawing a 16-epoch
+conclusion from one epoch of evidence, and publishing a plausible, detailed,
+statistically significant story that was entirely an artifact of a
+hyperparameter inherited from another architecture.
+
+**When you recommend something, write down what you rejected.** Both
+architecture decision records in `docs/decisions/` are structured that way,
+and the rejected options are the part that has aged best.
+
+**A measurement disagreeing with an earlier one is the interesting case.**
+Do not split the difference. Held-out accuracy has failed to predict play
+strength four separate times; when it disagrees with the arena, say so.
+
+## Where work is tracked
+
+`quantik-workspace` is the control plane and the source of truth for what
+work exists — initiatives under `tasks/active/QW-NNN/`, repository packets
+under `context/repositories/`, decisions under `docs/adr/`. It is a sibling
+checkout, not part of this repository.

quantik_models-1.0.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to `quantik-models` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+What counts as a breaking change here is written down in
+[`docs/decisions/0002-versioning-and-release.md`](docs/decisions/0002-versioning-and-release.md).
+
+## Unreleased
+
+## 1.0.0 - 2026-09-05
+
+First release on PyPI. The package has been usable from a checkout for
+months; what changes is that it is now installable, versioned and documented
+as a library rather than as this workspace's training directory.
+
+### Added
+
+- **`quantik_models.hub`** — load the four published networks from the
+  Hugging Face Hub in one call:
+
+  ```python
+  from quantik_models import hub
+  evaluator = hub.load_evaluator("cpool")               # torch
+  evaluator = hub.load_evaluator("cpool", runtime="onnx")  # no torch
+  ```
+
+  Short names resolve through a table of the published repo ids rather than
+  a Hub query, a full `owner/repo` passes through unresolved so a fork needs
+  no code change, and the downloaded artifact is checked against the digest
+  in `manifest.json` for the runtime that will load it — `weights_hash` for
+  safetensors, `onnx_hash` for the graph. The module is importable without
+  torch.
+
+  Every fetch failure is re-raised as `hub.HubError` carrying the remedy —
+  the cache path and the command to run when offline with a cold cache, the
+  terms link for a gated repo, the valid names for a typo, the commit list
+  for an unknown revision — with the Hub's own exception kept as `__cause__`.
+  A digest mismatch is re-fetched once before it is raised, because the usual
+  cause is a truncated cache entry that would otherwise fail identically
+  forever. `resolve()` reports the commit `main` resolved to, so a run made
+  without an explicit `revision` is still reproducible.
+- **`quantik-models-fetch` console script** (`hub.prefetch()` from Python) —
+  fills the Hugging Face cache without loading anything, so a container build
+  or an air-gapped host can be prepared before torch or onnxruntime exist.
+- **`hub` extra** (`pip install 'quantik-models[hub]'`) carrying
+  `huggingface-hub`. Kept out of the base install because nothing in
+  training, evaluation or the arena fetches anything.
+- **`quantik-models-play` console script**, so the play service starts the
+  same way from an installed package as from a checkout.
+- **`py.typed`**: the package now ships its type information.
+- **`arena.registry.weights_path`**, the resolver behind the loader fix
+  below.
+- **[`DEVELOPMENT.md`](DEVELOPMENT.md)**, [`CHANGELOG.md`](CHANGELOG.md), and
+  [`docs/models.md`](docs/models.md) — the published models, their numbers,
+  and how to load them.
+
+### Fixed
+
+- **`load_evaluator` could not read a downloaded Hub repository.** It
+  required `weights.safetensors`; `export.huggingface.stage` renames the
+  file to `model.safetensors` on the way to the Hub, and that is the name in
+  all four published repositories. The result was that the primary Python
+  snippet on every published model card raised `FileNotFoundError`. The
+  loader now resolves both names and, when it finds neither, says so naming
+  both candidates instead of pointing at a file that was never meant to
+  exist.
+- **The build declared `setuptools>=68` while using PEP 639 metadata that
+  needs 77.** A resolver that honoured the stated floor produced a wheel
+  with no licence, or failed outright.
+- **The generated model cards told readers `quantik-models` was not on PyPI**
+  and to install from a git ref. They now name the release.
+- **The card's Python snippet called a method that does not exist.**
+  `evaluator.evaluate(boards)` is wrong twice over — an evaluator is
+  callable, and the legality mask is a required argument with no default —
+  so a reader following the card got an `AttributeError` on the one line the
+  card exists to provide. Both live snippets were verified against a real
+  download from the Hub before this release, and
+  `tests/test_documented_snippets.py` now executes the documented call and
+  fails if `Evaluator.__call__` and the documents disagree.
+
+### Changed
+
+- Version **0.1.0 → 1.0.0**. The package's public surface — the `(B, 9, 4, 4)`
+  mover-relative input contract, the 64-logit policy and tanh value output,
+  the architecture registry and the checkpoint manifest — has been stable
+  across four trained architectures and four published model repositories.
+  `0.1.0` understated that, and semantic versioning only says anything once
+  the first stable release exists.
+- `quantik-core` dependency pinned to `>=1.2,<2` rather than `>=1.2`, so a
+  future major release of the core cannot silently satisfy this constraint.
+- `mypy` is now configured in `pyproject.toml` and **enforced in CI**. It was
+  previously declared in the `dev` extra and wired into nothing.
+- Packaging metadata filled in: authors, classifiers, keywords, project URLs
+  (including the Hub namespace), and a `MANIFEST.in` that ships the tests
+  with the fixtures they need and excludes `runs/`, `docs/` and `staging/`.
+
+### Documentation
+
+- `README.md` is now about using the library and the models. Everything
+  about checking out the workspace, the smoke pipeline, the corpora and the
+  release process moved to `DEVELOPMENT.md`.
+- The twenty-three documents in `docs/` were consolidated. Superseded
+  narrative and dated working journals were removed in favour of the
+  standing conclusions, which are what a reader can act on. See
+  `docs/README.md`.

quantik_models-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mauro Berlanda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

quantik_models-1.0.0/MANIFEST.in

@@ -0,0 +1,26 @@
+# What ships in the sdist beyond the package itself.
+#
+# The rule: an sdist must be enough to build the wheel *and* verify it. That
+# means the tests and the 80 KB smoke checkpoint they load — shipping
+# `tests/` without `tests/fixtures/` gives a source distribution whose test
+# suite cannot run, which is worse than shipping neither.
+include LICENSE
+include CHANGELOG.md
+include AGENTS.md
+recursive-include tests *.py *.json *.safetensors
+
+# Everything below is deliberately excluded.
+#
+# `runs/` is gitignored and holds every corpus and checkpoint — tens of GB,
+# none of it publishable, and the reason this list is explicit rather than
+# implicit. `docs/` is 664 KB of Markdown and figures that are one link away
+# on GitHub. `docker/staging/` is materialized weights.
+prune runs
+prune docs
+prune docker
+prune experiments
+prune examples
+prune scripts
+prune staging
+global-exclude *.pyc *.npz *.parquet *.jsonl
+global-exclude .DS_Store

quantik_models-1.0.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: quantik-models
+Version: 1.0.0
+Summary: Policy/value networks, training and evaluation for the Quantik board game
+Author-email: Mauro Berlanda <mauro.berlanda@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mberlanda/quantik-models-py
+Project-URL: Repository, https://github.com/mberlanda/quantik-models-py
+Project-URL: Documentation, https://github.com/mberlanda/quantik-models-py#readme
+Project-URL: Changelog, https://github.com/mberlanda/quantik-models-py/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/mberlanda/quantik-models-py/issues
+Project-URL: Model Weights, https://huggingface.co/brpoplpush
+Keywords: quantik,board-games,game-ai,policy-value-network,reinforcement-learning,mcts,alphazero,onnx,pytorch
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=2.0
+Requires-Dist: quantik-core<2,>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: mypy<3,>=1.8; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Requires-Dist: twine<7,>=6; extra == "dev"
+Provides-Extra: arrow
+Requires-Dist: pyarrow<22,>=16; extra == "arrow"
+Provides-Extra: torch
+Requires-Dist: torch>=2.4; extra == "torch"
+Requires-Dist: safetensors>=0.4; extra == "torch"
+Provides-Extra: onnx
+Requires-Dist: onnx>=1.16; extra == "onnx"
+Requires-Dist: onnxscript>=0.1; extra == "onnx"
+Requires-Dist: onnxruntime>=1.18; extra == "onnx"
+Provides-Extra: serve
+Requires-Dist: onnxruntime>=1.18; extra == "serve"
+Provides-Extra: hub
+Requires-Dist: huggingface-hub>=0.34; extra == "hub"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == "viz"
+Provides-Extra: all
+Requires-Dist: quantik-models[arrow,dev,hub,onnx,serve,torch,viz]; extra == "all"
+Dynamic: license-file
+
+# quantik-models
+
+[![PyPI](https://img.shields.io/pypi/v/quantik-models.svg)](https://pypi.org/project/quantik-models/)
+[![Python](https://img.shields.io/pypi/pyversions/quantik-models.svg)](https://pypi.org/project/quantik-models/)
+[![License](https://img.shields.io/pypi/l/quantik-models.svg)](LICENSE)
+
+Policy/value networks for **Quantik**, and the training, evaluation and play
+tooling behind them. Four architectures, parameter-matched, trained on
+positions labelled by an exact solver — and four sets of weights published on
+the Hugging Face Hub.
+
+Quantik is a 4×4 board game with a group-wise placement rule: you may not
+place a shape in a row, column or 2×2 zone where your *opponent* already has
+that shape, and you win by completing a line of four different shapes in
+either colour. It is small enough to solve exactly, which is what makes it a
+useful place to ask whether an architectural prior is worth having — the
+ground truth is available to check the answer against.
+
+```bash
+pip install 'quantik-models[torch,hub]'
+```
+
+```python
+from quantik_models import hub
+from quantik_models.env import fastboard as fb
+
+evaluator = hub.load_evaluator("cpool")     # downloads and verifies the weights
+
+boards = fb.empty_boards(1)              # (1, 8) uint16
+legal = fb.legal_masks(boards)           # (1, 64) bool
+policy, value = evaluator(boards, legal) # masked priors, value in [-1, 1]
+```
+
+Working *on* this package rather than with it: **[DEVELOPMENT.md](DEVELOPMENT.md)**.
+
+## Install
+
+| you want | install |
+|---|---|
+| the published models, on torch | `pip install 'quantik-models[torch,hub]'` |
+| the published models, no torch | `pip install 'quantik-models[serve,hub]'` |
+| to train your own | `pip install 'quantik-models[torch,onnx]'` |
+| the library only | `pip install quantik-models` |
+
+The base install is `numpy` and `quantik-core` and nothing else. torch is a
+529 MB dependency and onnxruntime is 80 MB; neither is imposed on someone who
+does not need it. The full table is in
+[DEVELOPMENT.md](DEVELOPMENT.md#environment).
+
+Python 3.12+.
+
+## Getting the weights
+
+The weights are not in the wheel. They are ~7 MB each, they carry a different
+licence from the code, and they version independently of it — so
+`load_evaluator` fetches them from the Hub on first use and reads them from
+the Hugging Face cache (`$HF_HOME`, default `~/.cache/huggingface`) every time
+after. **One network call, once per model, and never again.**
+
+To fill that cache ahead of time — a container build, a machine that is about
+to go offline, an air-gapped copy — use the fetch command. It needs neither
+torch nor onnxruntime, so it runs before either is installed:
+
+```bash
+quantik-models-fetch --all          # or: quantik-models-fetch cpool attn
+```
+
+Once a model is cached, everything works with no network at all.
+
+Nothing else needs special attention. Every way this can fail raises
+`hub.HubError` with the remedy in the message rather than a traceback through
+`huggingface_hub`:
+
+| what went wrong | what you get |
+|---|---|
+| offline, model already cached | it just works — the cache is used |
+| offline, nothing cached | the cache path, and the `quantik-models-fetch` line to run while online |
+| truncated download | re-fetched once automatically; a second failure names the cache to clear |
+| typo in the model name | the four names that do exist |
+| bad `revision` | a link to the repo's commit list |
+| rate limited | that it clears on its own, and that logging in raises the limit |
+
+`hub.resolve()` returns the commit the download actually resolved to, which is
+what to record when you report a number — `revision="main"` is not a pin.
+
+## The models
+
+Four networks answering the same question in different ways, all
+interchangeable because they agree on one contract:
+
+    input   (B, 9, 4, 4) float32      tensor-board.v1, mover-relative
+    output  (B, 64) policy logits     action_index = shape * 16 + position
+            (B,)    value in [-1, 1]  +1 = good for the side to move
+
+**Legality masking is applied outside every model**, using the same code path
+in training and at inference — so no engine here can return an illegal move.
+
+| model | Hub repository | IID top-1 | vs `minimax-d2` |
+|---|---|---|---|
+| **`cpool`** | [`quantik-cpool-c191-b6`](https://huggingface.co/brpoplpush/quantik-cpool-c191-b6) | **0.9893** | **49.4%** |
+| `attn` | [`quantik-attn-d192-b6`](https://huggingface.co/brpoplpush/quantik-attn-d192-b6) | 0.9879 | 43.1% |
+| `resnet` | [`quantik-resnet-c128-b6`](https://huggingface.co/brpoplpush/quantik-resnet-c128-b6) | 0.9701 | 36.5% |
+| `mlp` | [`quantik-mlp-h455-b4`](https://huggingface.co/brpoplpush/quantik-mlp-h455-b4) | 0.9516 | 31.9% |
+
+`minimax-d2` is a fixed two-ply alpha-beta search — the only opponent whose
+strength does not move with the field, and so the only column that answers
+"is any of this good" rather than "which of these is better". `cpool` playing
+raw policy, one forward pass per move, is even with it. **Full numbers, the
+four measurements that disagree, and what not to conclude from them:
+[`docs/models.md`](docs/models.md).**
+
+> **The weights are CC BY-NC 4.0; this package is MIT.** A commercial
+> application may use the pipeline, the rules engine and the evaluation
+> harness freely, and may not ship these weights. Train your own and they
+> are yours.
+
+### `cpool` — the constraint model
+
+Quantik's rule is group-wise, not spatial: twelve overlapping groups (4 rows,
+4 columns, 4 zones), every cell in exactly three. Each block pools the sixteen
+cell tokens into those groups, transforms them there, and scatters back.
+
+```mermaid
+flowchart LR
+  IN["board<br/>(B,9,4,4)"] --> TOK["16 cell tokens<br/>Linear 9→C"]
+  TOK --> BLK
+  subgraph BLK["constraint block × B"]
+    direction LR
+    N["LayerNorm"] --> POOL["pool to 12 groups<br/>4 rows · 4 cols · 4 zones"]
+    POOL --> KIND["+ kind embedding<br/>line | zone"]
+    KIND --> GM["group MLP"]
+    GM --> SC["scatter to member cells"]
+    SC --> MG["merge with cell features<br/>+ FFN, residual"]
+  end
+  BLK --> PH["policy head<br/>Linear C→4 per cell<br/>transpose → 64"]
+  BLK --> VH["value head<br/>mean over cells · MLP · tanh"]
+  PH --> POL["policy logits (B,64)"]
+  VH --> VAL["value (B,)"]
+```
+
+[`docs/architecture-constraint-pool.md`](docs/architecture-constraint-pool.md)
+
+### `attn` — the same bet without the prior
+
+Transformer encoder over the sixteen cells, told *nothing* about rows,
+columns or zones. It is the test of whether `cpool`'s explicit wiring was
+necessary: on policy accuracy it ties, on the value head it does not.
+
+[`docs/architectures.md`](docs/architectures.md) ·
+[`docs/attention-negative-result.md`](docs/attention-negative-result.md)
+
+### `resnet` — the incumbent
+
+Convolutional residual trunk, and the architecture every hyperparameter here
+was originally chosen for. 99.2% of its parameters are the trunk.
+
+[`docs/architecture-resnet.md`](docs/architecture-resnet.md)
+
+### `mlp` — the control
+
+Throws spatial structure away entirely: 144 flat features through dense
+residual blocks. It exists to make "convolution is worth having on a 4×4
+board" falsifiable rather than assumed. It loses, so the spatial prior is
+real.
+
+[`docs/architecture-mlp.md`](docs/architecture-mlp.md)
+
+![Validation top-1 per epoch](docs/figures/training-curves.svg)
+
+The dashed lines are two architectures trained at `2e-3`, the rate the ResNet
+was tuned for and everything added later inherited by silence. `attn` did not
+learn at all at that rate; `cpool` converged perfectly well, to a lower place.
+A single-rate comparison cannot tell either of those apart from "this
+architecture is worse" — which is how three published conclusions here turned
+out to be hyperparameter artifacts.
+[`docs/learning-rate-sweep.md`](docs/learning-rate-sweep.md).
+
+## Playing against them
+
+The play service serves the board and the models on one port, and records
+finished games:
+
+```bash
+pip install 'quantik-models[serve,hub]'
+quantik-models-play --models staging
+```
+
+It prints a LAN address to open on a phone. `--no-store` opens no database,
+which is the configuration the public container runs.
+[`docs/play-service.md`](docs/play-service.md).
+
+## Training your own
+
+```bash
+pip install 'quantik-models[torch,onnx]'
+```
+
+```bash
+# check the assumptions before a long run (~1 min/arch)
+python -m quantik_models.train.preflight --preset medium --epochs 16
+
+# train to convergence: --epochs is the cap, --patience the rule
+python -m quantik_models.train.supervised --arch cpool --preset medium \
+  --corpus runs/oracle/corpus/exact-sampled.npz --name my-run \
+  --epochs 60 --patience 5
+
+# regenerate every published number for it
+scripts/evaluate_lineup.sh runs/eval/today cpool=runs/train/my-run/best
+
+# stage it as a Hugging Face model repository (writes files; uploads nothing)
+quantik-models-hf-stage runs/train/my-run/best staging/my-model
+```
+
+Training writes `weights.safetensors`, `model.onnx`, a
+`model-checkpoint.v1` `manifest.json` and a training report. Corpora, the
+label strategy and the retrain/fine-tune path — including freezing part of a
+network — are in [`docs/`](docs/README.md).
+
+## Documentation
+
+[`docs/README.md`](docs/README.md) is the reading order. The four to start
+with:
+
+| | |
+|---|---|
+| [`docs/models.md`](docs/models.md) | the published models: how to load one, what the numbers mean, what not to conclude |
+| [`docs/decisions/0001-architecture-lineup.md`](docs/decisions/0001-architecture-lineup.md) | which architectures were trained, which six were declined, and the methodology |
+| [`docs/benchmarks.md`](docs/benchmarks.md) | the figures, and what each does and does not establish |
+| [`docs/oracle-benchmark.md`](docs/oracle-benchmark.md) | the field against a fixed classical engine |
+
+## Related
+
+- [`quantik-core`](https://pypi.org/project/quantik-core/) — the rules
+  engine, QFEN, bitboards and the exact solver. Also on
+  [crates.io](https://crates.io/crates/quantik-core).
+- [The models on the Hub](https://huggingface.co/brpoplpush) — weights,
+  ONNX graphs and model cards.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The published **weights** are CC BY-NC 4.0 and
+are not distributed with this package.