avrik 1.0.0__tar.gz

avrik-1.0.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

avrik-1.0.0/NOTICE

@@ -0,0 +1,10 @@
+avrik
+Copyright 2026 Avrik AI (https://www.avrik.ai)
+
+Licensed under the Apache License, Version 2.0 (see LICENSE). Distributed on an "AS IS"
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+Avrik models are built on Gemma 4 by Google, licensed under the Apache License,
+Version 2.0. Acceptable use policy: https://huggingface.co/avrik-ai/Avrik-Pro-12B/blob/main/USE_POLICY.md
+
+Contact: avriktech.ai@gmail.com

avrik-1.0.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: avrik
+Version: 1.0.0
+Summary: Avrik: run the Avrik decision models locally (pull, ask, serve).
+Author: Avrik AI
+Author-email: Avrik AI <avriktech.ai@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: avrik-server[api,readout]>=1.0.0,<2
+Requires-Dist: huggingface-hub>=0.30
+Requires-Dist: avrik-server[cpu]>=1.0.0,<2 ; extra == 'cpu'
+Maintainer: Avrik AI
+Maintainer-email: Avrik AI <avriktech.ai@gmail.com>
+Requires-Python: >=3.12
+Project-URL: Homepage, https://www.avrik.ai
+Project-URL: Models, https://huggingface.co/avrik-ai
+Provides-Extra: cpu
+Description-Content-Type: text/markdown
+
+# avrik
+
+Run [Avrik](https://huggingface.co/avrik-ai) decision models on your own machine:
+`avrik pull`, `avrik ask`, `avrik serve`, `avrik info`.
+
+An Avrik model reads a state and typed questions (yes/no, choice, score, multi-label) and
+returns a calibrated probability distribution over each question's options, in one
+forward pass with no generated text. Every answer carries the hashes that identify the
+exact model, calibration and prompt behind it.
+
+## Install
+
+On a CPU:
+
+```bash
+pip install llama-cpp-python==0.3.35 --no-deps --only-binary=:all: \
+  --index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+pip install "avrik[cpu]"
+```
+
+The first line installs llama.cpp's prebuilt CPU wheel from its own index; without it, pip
+compiles llama.cpp, which needs a C++ compiler. On a GPU, `pip install avrik` and run vLLM
+on loopback (each model card gives the command), then pass `--vllm-url`.
+
+## Use
+
+```bash
+avrik pull Avrik-Lite-4B             # downloads avrik-ai/Avrik-Lite-4B-GGUF and verifies it
+avrik ask Avrik-Lite-4B --state "Customer bought headphones 12 days ago, unopened, \
+receipt attached. Policy: unopened items within 30 days get a full refund." \
+  --noul "Should the refund be approved?" \
+  --choice "Which action?=approve,deny,escalate" [--json]
+avrik serve Avrik-Lite-4B --port 8080   # /v1/systemone on 127.0.0.1 only
+avrik info Avrik-Lite-4B                # provenance: hashes, recipe, calibration
+```
+
+| Model | Default build | Hardware |
+| --- | --- | --- |
+| `Avrik-Lite-4B` | GGUF Q4_K_M (`--format bf16` for GPU) | CPU |
+| `Avrik-Pro-12B` | GGUF Q8_0 (`--format bf16` for GPU) | CPU or 16 GB card; bf16 on one GPU |
+| `Avrik-Max-31B` | FP8 via vLLM (weights downloaded from Google's repo, verified by hash) | one 80 GB GPU |
+
+Names match in any case. `--dir` uses a local release directory instead of the cache
+(`$AVRIK_HOME`, default `~/.cache/avrik`).
+
+## Integrity and privacy
+
+- `pull` downloads a release at a commit pinned inside this package and refuses it unless
+  its `MANIFEST.sha256` has the pinned digest; then every file is checked.
+- `ask`, `serve` and `info` re-check every file before anything loads. Code files,
+  `auto_map`, symlinks and unlisted files are refused (exit 3).
+- Only `pull` uses the network. Inference sends no telemetry and stores nothing.
+
+Call the API from Python with [`avrik-sdk`](https://pypi.org/project/avrik-sdk/).
+
+Built on Gemma 4 by Google (Apache-2.0). Licence: Apache-2.0. Security reports:
+avriktech.ai@gmail.com.
+
+Website: [www.avrik.ai](https://www.avrik.ai) · Models: [huggingface.co/avrik-ai](https://huggingface.co/avrik-ai) ·
+[Acceptable use policy](https://huggingface.co/avrik-ai/Avrik-Pro-12B/blob/main/USE_POLICY.md)

avrik-1.0.0/PYPI.md

@@ -0,0 +1,60 @@
+# avrik
+
+Run [Avrik](https://huggingface.co/avrik-ai) decision models on your own machine:
+`avrik pull`, `avrik ask`, `avrik serve`, `avrik info`.
+
+An Avrik model reads a state and typed questions (yes/no, choice, score, multi-label) and
+returns a calibrated probability distribution over each question's options, in one
+forward pass with no generated text. Every answer carries the hashes that identify the
+exact model, calibration and prompt behind it.
+
+## Install
+
+On a CPU:
+
+```bash
+pip install llama-cpp-python==0.3.35 --no-deps --only-binary=:all: \
+  --index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
+pip install "avrik[cpu]"
+```
+
+The first line installs llama.cpp's prebuilt CPU wheel from its own index; without it, pip
+compiles llama.cpp, which needs a C++ compiler. On a GPU, `pip install avrik` and run vLLM
+on loopback (each model card gives the command), then pass `--vllm-url`.
+
+## Use
+
+```bash
+avrik pull Avrik-Lite-4B             # downloads avrik-ai/Avrik-Lite-4B-GGUF and verifies it
+avrik ask Avrik-Lite-4B --state "Customer bought headphones 12 days ago, unopened, \
+receipt attached. Policy: unopened items within 30 days get a full refund." \
+  --noul "Should the refund be approved?" \
+  --choice "Which action?=approve,deny,escalate" [--json]
+avrik serve Avrik-Lite-4B --port 8080   # /v1/systemone on 127.0.0.1 only
+avrik info Avrik-Lite-4B                # provenance: hashes, recipe, calibration
+```
+
+| Model | Default build | Hardware |
+| --- | --- | --- |
+| `Avrik-Lite-4B` | GGUF Q4_K_M (`--format bf16` for GPU) | CPU |
+| `Avrik-Pro-12B` | GGUF Q8_0 (`--format bf16` for GPU) | CPU or 16 GB card; bf16 on one GPU |
+| `Avrik-Max-31B` | FP8 via vLLM (weights downloaded from Google's repo, verified by hash) | one 80 GB GPU |
+
+Names match in any case. `--dir` uses a local release directory instead of the cache
+(`$AVRIK_HOME`, default `~/.cache/avrik`).
+
+## Integrity and privacy
+
+- `pull` downloads a release at a commit pinned inside this package and refuses it unless
+  its `MANIFEST.sha256` has the pinned digest; then every file is checked.
+- `ask`, `serve` and `info` re-check every file before anything loads. Code files,
+  `auto_map`, symlinks and unlisted files are refused (exit 3).
+- Only `pull` uses the network. Inference sends no telemetry and stores nothing.
+
+Call the API from Python with [`avrik-sdk`](https://pypi.org/project/avrik-sdk/).
+
+Built on Gemma 4 by Google (Apache-2.0). Licence: Apache-2.0. Security reports:
+avriktech.ai@gmail.com.
+
+Website: [www.avrik.ai](https://www.avrik.ai) · Models: [huggingface.co/avrik-ai](https://huggingface.co/avrik-ai) ·
+[Acceptable use policy](https://huggingface.co/avrik-ai/Avrik-Pro-12B/blob/main/USE_POLICY.md)

avrik-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "avrik"
+version = "1.0.0"
+description = "Avrik: run the Avrik decision models locally (pull, ask, serve)."
+readme = "PYPI.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = [
+    "LICENSE",
+    "NOTICE",
+]
+dependencies = [
+    "avrik-server[api,readout]>=1.0.0,<2",
+    "huggingface_hub>=0.30",
+]
+
+[[project.authors]]
+name = "Avrik AI"
+email = "avriktech.ai@gmail.com"
+
+[[project.maintainers]]
+name = "Avrik AI"
+email = "avriktech.ai@gmail.com"
+
+[project.urls]
+Homepage = "https://www.avrik.ai"
+Models = "https://huggingface.co/avrik-ai"
+
+[project.optional-dependencies]
+cpu = ["avrik-server[cpu]>=1.0.0,<2"]
+
+[project.scripts]
+avrik = "avrik_cli.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "avrik_cli"

avrik-1.0.0/pyproject.toml.orig

@@ -0,0 +1,30 @@
+[project]
+name = "avrik"
+authors = [{ name = "Avrik AI", email = "avriktech.ai@gmail.com" }]
+version = "1.0.0"
+description = "Avrik: run the Avrik decision models locally (pull, ask, serve)."
+readme = "PYPI.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+license-files = ["LICENSE", "NOTICE"]
+maintainers = [{ name = "Avrik AI", email = "avriktech.ai@gmail.com" }]
+# Published on PyPI with avrik-server (spec 004, research R14). Must not depend on
+# avrik-eval, avrik-data or avrik-train.
+dependencies = ["avrik-server[api,readout]>=1.0.0,<2", "huggingface_hub>=0.30"]
+
+[project.urls]
+Homepage = "https://www.avrik.ai"
+Models = "https://huggingface.co/avrik-ai"
+
+[project.optional-dependencies]
+cpu = ["avrik-server[cpu]>=1.0.0,<2"]
+
+[project.scripts]
+avrik = "avrik_cli.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "avrik_cli"

avrik-1.0.0/src/avrik_cli/__init__.py

@@ -0,0 +1 @@
+"""avrik: run the avrik-s1 decision models locally (spec 004, contracts/avrik-cli.md)."""

avrik-1.0.0/src/avrik_cli/__main__.py

@@ -0,0 +1,297 @@
+"""``avrik``: pull, ask, serve, info (spec 004 contracts/avrik-cli.md).
+
+- ``avrik pull MODEL [--format gguf|bf16|fp8]``: downloads ``avrik-ai/MODEL`` (``-GGUF``
+  for the GGUF build) and verifies ``MANIFEST.sha256``. For a weights-free build (Max,
+  ``fp8`` by default) it then downloads the pinned upstream revision into ``upstream/``
+  and checks every file against the shipped lock. This is the only command that uses the
+  network.
+- ``avrik ask MODEL --state … --noul Q --choice "Q=a,b,c" --score "Q=low,high"``:
+  answers in-process with the server's engine. It loads only verified files, offline.
+- ``avrik serve MODEL``: the ``/v1/systemone`` app on loopback.
+- ``avrik info MODEL``: recipe, hashes and calibration from ``provenance.json``.
+
+A release directory holds:
+- the weights (``*.gguf``, or bf16 safetensors), or for Max ``upstream.lock.json`` and,
+  once pulled, the verified upstream files in ``upstream/``;
+- the tokenizer and chat template;
+- ``.avrik-pin.json``;
+- ``readout.json``;
+- ``calibration/*.json``;
+- ``provenance.json``;
+- ``MANIFEST.sha256``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from avrik_cli.verify import UPSTREAM_DIR, ManifestError, verify_release
+
+ORG = "avrik-ai"
+FORMATS = ("gguf", "bf16", "fp8")
+DEFAULT_FORMAT = {"Avrik-Max-31B": "fp8"}  # weights-free: served by vLLM in FP8
+MODELS = ("Avrik-Lite-4B", "Avrik-Pro-12B", "Avrik-Max-31B")
+
+
+def canonical(model: str) -> str:
+    """A published model's name as the registry spells it, matched in any case."""
+    return next((m for m in MODELS if m.lower() == model.lower()), model)
+
+
+def cache_dir() -> Path:
+    """Where pulled releases live (``$AVRIK_HOME`` or ``~/.cache/avrik``)."""
+    return Path(os.environ.get("AVRIK_HOME", Path.home() / ".cache" / "avrik"))
+
+
+def release_dir(model: str, fmt: str) -> Path:
+    """A model's local release directory for a format."""
+    return cache_dir() / f"{model}-{fmt}"
+
+
+def pull(
+    model: str,
+    fmt: str,
+    revision: str | None,
+    dest: Path | None = None,
+    manifest_sha256: str | None = None,
+) -> Path:
+    """Download a release at a trusted commit, verify it, and move it into place.
+
+    The commit and manifest digest come from :mod:`avrik_cli.releases`, or from
+    ``revision`` with ``manifest_sha256`` for a newer release. The download goes into a
+    fresh temporary directory, is verified there, and is renamed into ``dest``, which
+    must not exist yet or be empty (security review T066, S1 and S2).
+
+    Raises:
+        ManifestError: When the release is unknown, the digest differs, a check fails, or
+            ``dest`` is not empty.
+    """
+    import shutil
+    import tempfile
+
+    from huggingface_hub import snapshot_download
+
+    from avrik_cli.releases import RELEASES
+    from avrik_cli.verify import MANIFEST, read_manifest, sha256
+
+    if bool(revision) != bool(manifest_sha256):
+        raise ManifestError("--revision and --manifest-sha256 go together")
+    known = RELEASES.get((model, fmt))
+    repo = f"{ORG}/{model}" + ("-GGUF" if fmt == "gguf" else "")
+    if revision and manifest_sha256:
+        commit, digest = revision, manifest_sha256
+    elif known is not None:
+        repo, commit, digest = known.repo, known.commit, known.manifest_sha256
+    else:
+        raise ManifestError(
+            f"{model} ({fmt}) is not a release this avrik knows; pass --revision and "
+            "--manifest-sha256 from the model card"
+        )
+    dest = dest or release_dir(model, fmt)
+    if dest.exists() and not dest.is_dir():
+        raise ManifestError(f"{dest} is not a directory")
+    if dest.exists() and any(dest.iterdir()):
+        raise ManifestError(f"{dest} is not empty; remove it or pick another --dir")
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    work = Path(tempfile.mkdtemp(prefix=".avrik-pull-", dir=dest.parent))
+    try:
+        token = os.environ.get("HF_TOKEN") or False  # environment only, never a stored token
+        # The manifest first, checked against the trusted digest; then exactly the files it
+        # lists. The Hub adds files of its own (``.gitattributes``) that a release never lists.
+        snapshot_download(repo_id=repo, revision=commit, local_dir=work, token=token,
+                          allow_patterns=[MANIFEST])  # fmt: skip
+        if sha256(work / MANIFEST) != digest:
+            raise ManifestError(f"{repo}@{commit}: MANIFEST.sha256 is not the published one")
+        snapshot_download(repo_id=repo, revision=commit, local_dir=work, token=token,
+                          allow_patterns=sorted(read_manifest(work)))  # fmt: skip
+        n = verify_release(work)
+        _check_provenance(work)
+        upstream = _upstream_block(work)
+        if upstream is not None:
+            if (work / UPSTREAM_DIR).exists():
+                raise ManifestError(f"{repo}@{commit} ships upstream/; only pull may write it")
+            snapshot_download(repo_id=upstream["repo"], revision=upstream["revision"],
+                              local_dir=work / UPSTREAM_DIR, token=token)  # fmt: skip
+            n = verify_release(work, upstream_required=True)
+        if dest.exists():
+            dest.rmdir()
+        work.rename(dest)
+    except BaseException:
+        shutil.rmtree(work, ignore_errors=True)
+        raise
+    print(f"pulled {repo}@{commit} -> {dest} ({n} files verified)")
+    return dest
+
+
+def _upstream_block(root: Path) -> dict[str, str] | None:
+    """A verified weights-free release's upstream repo and revision, or None.
+
+    :func:`verify_release` has already checked the block against the lock and the pin
+    (an ``org/name`` repo at a full 40-hex commit).
+    """
+    from avrik_cli.verify import readout
+
+    block = readout(root).get("upstream")
+    if not isinstance(block, dict):
+        return None
+    return {"repo": str(block["repo"]), "revision": str(block["revision"])}
+
+
+def _check_provenance(root: Path) -> None:
+    pin = json.loads((root / ".avrik-pin.json").read_text(encoding="utf-8"))
+    prov = json.loads((root / "provenance.json").read_text(encoding="utf-8"))
+    if prov.get("model_hash") != f"{pin.get('repo')}@{pin.get('revision')}":
+        raise ManifestError("provenance.json model_hash does not match .avrik-pin.json")
+
+
+PRECISIONS = ("bf16", "q8_0", "q4_k_m", "fp8")
+MAX_CONTEXT = 131072
+
+
+def _config(root: Path, *, vllm_url: str | None, port: int) -> dict[str, Any]:
+    """The server config for a verified release, from the names in ``readout.json``.
+
+    Values from the repo are checked, never expanded (security review T066, B1 and S3).
+    """
+    from avrik_cli.verify import readout
+
+    info = readout(root)
+    precision = str(info.get("precision", "bf16"))
+    if precision not in PRECISIONS:
+        raise ManifestError(f"readout.json precision {precision!r} is not one of {PRECISIONS}")
+    context = info.get("max_model_len", 8192)
+    if not isinstance(context, int) or not 512 <= context <= MAX_CONTEXT:
+        raise ManifestError(f"readout.json max_model_len must be 512–{MAX_CONTEXT}")
+    weights = [str(w) for w in info["weights"]]
+    if vllm_url:
+        backend: dict[str, Any] = {"kind": "vllm-gpu", "url": vllm_url, "served_model": "avrik"}
+    else:
+        ggufs = [w for w in weights if w.endswith(".gguf")]
+        if len(ggufs) != 1:
+            raise ManifestError("readout.json names no single GGUF; use --vllm-url for bf16")
+        backend = {"kind": "llamacpp-cpu", "gguf": str(root / ggufs[0])}
+    backend |= {"precision": precision, "max_model_len": context}
+    name = str(info.get("model", ""))
+    if not name or any(c in name for c in "$/\\ \n"):
+        raise ManifestError("readout.json model name is missing or has unsafe characters")
+    return {
+        "model": {"name": name, "dir": str(root)},
+        "backend": backend,
+        "profile": "avrik",
+        "calibration": str(root / str(info["calibration"])),
+        "serving": {"host": "127.0.0.1", "port": port, "max_in_flight": 1, "max_queued": 16},
+    }
+
+
+def _engine(root: Path, vllm_url: str | None, port: int = 8080) -> Any:
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    os.environ["TRANSFORMERS_OFFLINE"] = "1"
+    from avrik_server.api.__main__ import build_backend
+    from avrik_server.calibration.file import load
+    from avrik_server.config import parse_config
+    from avrik_server.engine.decide import Engine
+    from avrik_server.readout.smoke import _hf_tokenizer
+
+    config = parse_config(_config(root, vllm_url=vllm_url, port=port))
+    return Engine(config, _hf_tokenizer(root), build_backend(config), load(config.calibration))
+
+
+def _questions(args: argparse.Namespace) -> dict[str, Any]:
+    qs: dict[str, Any] = {}
+    for text in args.noul or []:
+        qs[f"q{len(qs) + 1}"] = {"type": "noul", "instructions": text}
+    for spec in args.choice or []:
+        question, _, opts = spec.rpartition("=")
+        criteria = {o.strip(): o.strip() for o in opts.split(",")}
+        qs[f"q{len(qs) + 1}"] = {"type": "choice", "instructions": question, "criteria": criteria}
+    for spec in args.score or []:
+        question, _, levels = spec.rpartition("=")
+        qs[f"q{len(qs) + 1}"] = {"type": "score", "instructions": question,
+                                 "criteria": [lv.strip() for lv in levels.split(",")]}  # fmt: skip
+    if not qs:
+        raise SystemExit("ask needs at least one --noul, --choice or --score")
+    return qs
+
+
+def _print_answers(questions: dict[str, Any], out: dict[str, Any]) -> None:
+    for name, q in questions.items():
+        a = out["answers"][name]
+        if a["type"] == "noul":
+            line = f"P(yes) = {a['noul']:.3f}"
+        elif a["type"] == "choice":
+            probs = ", ".join(f"{k} {v:.3f}" for k, v in a["probabilities"].items())
+            line = f"{a['choice']}  ({probs})"
+        else:
+            line = f"score {a['score']:.2f} of 0..{len(a['legend']) - 1}"
+        print(f"{q['instructions']}\n  -> {line}{'  [abstain]' if a.get('abstain') else ''}")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Entry point: 0 ok, 3 verification failure."""
+    parser = argparse.ArgumentParser(prog="avrik")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    for name in ("pull", "ask", "serve", "info"):
+        p = sub.add_parser(name)
+        p.add_argument("model")
+        p.add_argument("--format", choices=FORMATS,
+                       help="build (default: fp8 for Avrik-Max-31B, else gguf)")  # fmt: skip
+        p.add_argument("--dir", type=Path, help="a release directory (default: the pull cache)")
+        if name == "pull":
+            p.add_argument("--revision", help="a commit, with --manifest-sha256")
+            p.add_argument("--manifest-sha256", help="the card's MANIFEST.sha256 digest")
+        if name in ("ask", "serve"):
+            p.add_argument("--vllm-url", help="a vLLM server on loopback (bf16 and fp8 builds)")
+        if name == "ask":
+            p.add_argument("--state", required=True, help="text, or @file")
+            p.add_argument("--noul", action="append")
+            p.add_argument("--choice", action="append", help='"question=a,b,c"')
+            p.add_argument("--score", action="append", help='"question=low,mid,high"')
+            p.add_argument("--json", action="store_true")
+        if name == "serve":
+            p.add_argument("--port", type=int, default=8080)
+    args = parser.parse_args(argv)
+    args.model = canonical(args.model)
+    args.format = args.format or DEFAULT_FORMAT.get(args.model, "gguf")
+    try:
+        if args.cmd == "pull":
+            pull(args.model, args.format, args.revision, args.dir, args.manifest_sha256)
+            return 0
+        root = args.dir or release_dir(args.model, args.format)
+        # ask and serve need a weights-free build's upstream/ present and verified (M1).
+        verify_release(root, upstream_required=args.cmd in ("ask", "serve"))
+        if args.cmd == "info":
+            print(json.dumps(json.loads((root / "provenance.json").read_text()), indent=1))
+            return 0
+        if args.cmd == "ask":
+            state = args.state
+            if state.startswith("@"):
+                state = Path(state[1:]).read_text(encoding="utf-8")
+            questions = _questions(args)
+            engine = _engine(root, args.vllm_url)
+            out = asyncio.run(engine.decide({"state": state, "questions": questions}))
+            if args.json:
+                print(json.dumps(out, indent=1))
+            else:
+                _print_answers(questions, out)
+            return 0
+        import uvicorn
+
+        from avrik_server.api.app import create_app
+
+        engine = _engine(root, args.vllm_url, args.port)
+        uvicorn.run(create_app(engine), host="127.0.0.1", port=args.port, access_log=False)
+        return 0
+    except ManifestError as error:
+        print(f"refused: {error}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())

avrik-1.0.0/src/avrik_cli/release.py

@@ -0,0 +1,310 @@
+"""Release bundles for Hugging Face (spec 004 contracts/release-bundle.md; FR-017).
+
+``stage`` assembles one build's release directory:
+
+| Contents | Source |
+| --- | --- |
+| Weights | GGUF or bf16 safetensors |
+| Tokenizer and chat template | Copied from the base |
+| ``.avrik-pin.json`` | The build's identity (below) |
+| ``readout.json`` | Written here |
+| ``calibration/`` | The fitted calibration file |
+| ``provenance.json`` | Written here |
+| ``README.md`` | The card |
+| ``LICENSE``, ``NOTICE``, ``USE_POLICY.md`` | ``--extra``: licence and terms files |
+| ``results/`` | Copied in |
+| ``MANIFEST.sha256`` | Every file above, hashed |
+
+**Build identity.** The pin is ``avrik-ai/<repo>@<first 16 hex of the weights' sha256>``.
+The calibration must be fitted against this exact ``model_hash``, and the server refuses
+a mismatch.
+
+**Weights-free builds** (``Avrik-Max-31B``; research R17). ``--upstream-lock`` replaces
+``--weights``: the bundle ships the lock as ``upstream.lock.json`` and no weights, and the
+pin is the upstream ``repo@revision`` the lock names. ``avrik pull`` fetches that revision
+and checks it against the lock.
+
+``render_card`` fills ``docs/model-cards/TEMPLATE.md`` from a JSON of values and refuses
+any placeholder left unfilled.
+
+``upload`` creates the repo **private** and uploads the folder. ``--public`` is a
+separate, approved step (Day 7).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import sys
+from collections.abc import Sequence
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from avrik_cli.verify import MANIFEST, UPSTREAM_LOCK, ManifestError, sha256
+
+ORG = "avrik-ai"
+TOKENIZER_FILES = ("tokenizer.json", "tokenizer_config.json", "chat_template.jinja",
+                   "special_tokens_map.json", "generation_config.json", "config.json",
+                   "processor_config.json", "preprocessor_config.json")  # fmt: skip
+
+
+def repo_name(model: str, fmt: str) -> str:
+    """HF repo for a build: the bf16 repo has no suffix, the GGUF repo ``-GGUF``."""
+    return f"{model}-GGUF" if fmt.startswith("gguf") else model
+
+
+def weights_digest(files: Sequence[Path]) -> str:
+    """One sha256 over the weight files' own sha256s, in name order."""
+    h = hashlib.sha256()
+    for path in sorted(files, key=lambda p: p.name):
+        h.update(f"{path.name}:{sha256(path)}\n".encode())
+    return h.hexdigest()
+
+
+def pin(model: str, fmt: str, weights: Sequence[Path]) -> dict[str, str]:
+    """The build identity written as ``.avrik-pin.json``."""
+    return {"repo": f"{ORG}/{repo_name(model, fmt)}", "revision": weights_digest(weights)[:16]}
+
+
+def read_lock(path: Path) -> dict[str, Any]:
+    """An upstream lock (``infra/weights/model_lock.py``): repo, revision, files.
+
+    Raises:
+        ValueError: When a field is missing or no file is listed.
+    """
+    lock: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    if not lock.get("repo") or not lock.get("revision") or not lock.get("files"):
+        raise ValueError(f"{path} is not a lock with repo, revision and files")
+    return lock
+
+
+def upstream_pin(lock: dict[str, Any]) -> dict[str, str]:
+    """A weights-free build's identity: the upstream repo at its full revision."""
+    return {"repo": str(lock["repo"]), "revision": str(lock["revision"])}
+
+
+def stage(
+    *,
+    model: str,
+    fmt: str,
+    weights: Sequence[Path],
+    base_dir: Path,
+    calibration: Path | None,
+    out: Path,
+    provenance: dict[str, Any],
+    card: Path | None = None,
+    results: Sequence[Path] = (),
+    readout: dict[str, Any] | None = None,
+    upstream_lock: Path | None = None,
+    extra: Sequence[Path] = (),
+) -> Path:
+    """Assemble a release directory and its manifest; return ``out``.
+
+    ``out`` must not exist or must be empty, so nothing left over gets listed and shipped
+    (security review T066, S6). Weights are hardlinked when ``out`` is on the same
+    filesystem, and copied otherwise. ``readout.json`` names the weights and the
+    calibration; ``avrik`` loads exactly those. ``extra`` files (licence and terms) are
+    copied to the root by name. With ``upstream_lock`` the bundle has no
+    weights: it ships the lock and names it in ``readout.json``'s ``upstream`` block.
+
+    Raises:
+        ValueError: When ``out`` is not empty, no calibration is given, or the bundle has
+            both or neither of weights and an upstream lock.
+    """
+    if out.exists() and any(out.iterdir()):
+        raise ValueError(f"{out} is not empty; stage into a fresh directory")
+    if calibration is None:
+        raise ValueError("a release needs its own calibration file")
+    if bool(weights) == (upstream_lock is not None):
+        raise ValueError("a release ships weights or an upstream lock, not both or neither")
+    lock = read_lock(upstream_lock) if upstream_lock is not None else None
+    out.mkdir(parents=True, exist_ok=True)
+    for path in weights:
+        try:
+            os.link(path, out / path.name)
+        except OSError:
+            shutil.copy2(path, out / path.name)
+    for name in TOKENIZER_FILES:
+        if (base_dir / name).exists():
+            shutil.copy2(base_dir / name, out / name)
+    identity = upstream_pin(lock) if lock is not None else pin(model, fmt, weights)
+    upstream: dict[str, Any] = {}
+    if lock is not None and upstream_lock is not None:
+        shutil.copy2(upstream_lock, out / UPSTREAM_LOCK)
+        upstream = {"upstream": {**identity, "lock": UPSTREAM_LOCK}}
+    adapter = provenance.get("adapter_hash")
+    record = {**identity, **({"adapter": adapter} if adapter and adapter != "none" else {})}
+    (out / ".avrik-pin.json").write_text(json.dumps(record, indent=1) + "\n")
+    (out / "calibration").mkdir(exist_ok=True)
+    shutil.copy2(calibration, out / "calibration" / calibration.name)
+    (out / "readout.json").write_text(json.dumps({
+        "model": model, "format": fmt, "profile": "avrik", "mass_bound": 0.98,
+        "weights": [p.name for p in weights], "calibration": f"calibration/{calibration.name}",
+        "allowed_set": "every tokenizer form of each option code; codes past 26 use two "
+                       "letters, skipping codes the tokenizer splits; abstain last",
+        **(readout or {}), **upstream,  # the upstream block cannot be overridden
+    }, indent=1) + "\n")  # fmt: skip
+    (out / "provenance.json").write_text(json.dumps({
+        "model": model, "format": fmt, "model_hash": f"{identity['repo']}@{identity['revision']}",
+        "created_at": datetime.now(UTC).isoformat(timespec="seconds"), **provenance,
+    }, indent=1) + "\n")  # fmt: skip
+    if card is not None:
+        shutil.copy2(card, out / "README.md")
+    for path in extra:
+        shutil.copy2(path, out / path.name)
+    if results:
+        (out / "results").mkdir(exist_ok=True)
+        for path in results:
+            shutil.copy2(path, out / "results" / path.name)
+    files = sorted(p for p in out.rglob("*") if p.is_file() and p.name != MANIFEST
+                   and ".cache" not in p.parts)  # fmt: skip
+    (out / MANIFEST).write_text("".join(f"{sha256(p)}  {p.relative_to(out).as_posix()}\n"
+                                        for p in files))  # fmt: skip
+    return out
+
+
+PLACEHOLDER = re.compile(r"\{\{([a-z0-9_]+)\}\}")
+
+
+class CardError(ValueError):
+    """A card template has placeholders with no value."""
+
+
+def render_card(template: Path, values: dict[str, str], out: Path) -> Path:
+    """Fill ``{{key}}`` placeholders in ``template``; refuse any left unfilled.
+
+    Raises:
+        CardError: Naming the missing keys.
+    """
+    text = template.read_text(encoding="utf-8")
+    missing = sorted({k for k in PLACEHOLDER.findall(text) if k not in values})
+    if missing:
+        raise CardError(f"card values missing: {', '.join(missing)}")
+    rendered = PLACEHOLDER.sub(lambda m: str(values[m.group(1)]), text)
+    out.write_text(rendered, encoding="utf-8")
+    return out
+
+
+def upload(folder: Path, repo: str, *, public: bool = False) -> str:
+    """Verify ``folder``, then upload its manifest's files to ``avrik-ai/<repo>``.
+
+    The repo's visibility must match the request: an existing public repo is refused
+    unless ``public``, and ``public`` on an existing private repo is refused too. Switching
+    visibility is a separate, approved step (security review T066, S5). The token comes
+    from ``HF_TOKEN`` only.
+
+    Raises:
+        ValueError: On a visibility mismatch or a failed verification.
+    """
+    from huggingface_hub import HfApi
+
+    from avrik_cli.verify import read_manifest, verify_release
+
+    verify_release(folder)
+    api = HfApi(token=os.environ.get("HF_TOKEN") or False)
+    repo_id = f"{ORG}/{repo}"
+    api.create_repo(repo_id, repo_type="model", private=not public, exist_ok=True)
+    private = bool(api.model_info(repo_id).private)
+    if private == public:
+        state = "private" if private else "public"
+        raise ValueError(f"{repo_id} is {state}; upload refused (asked public={public})")
+    files = [*read_manifest(folder), MANIFEST]
+    api.upload_folder(folder_path=str(folder), repo_id=repo_id, repo_type="model",
+                      allow_patterns=files)  # fmt: skip
+    return repo_id
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """``python -m avrik_cli.release pin|stage|card|upload ...``; 3 on a refusal."""
+    parser = argparse.ArgumentParser(prog="python -m avrik_cli.release")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    up = sub.add_parser("upload")
+    up.add_argument("--dir", type=Path, required=True)
+    up.add_argument("--repo", required=True)
+    up.add_argument("--public", action="store_true")
+    pn = sub.add_parser("pin", help="print a build's identity (fit its calibration to this)")
+    pn.add_argument("--model", required=True)
+    pn.add_argument("--format", required=True)
+    pn.add_argument("--weights", type=Path, nargs="+", required=True)
+    pn.add_argument("--base-dir", type=Path, help="also print the template sha256")
+    st = sub.add_parser("stage")
+    st.add_argument("--model", required=True)
+    st.add_argument("--format", required=True)
+    st.add_argument("--weights", type=Path, nargs="*", default=[])
+    st.add_argument("--upstream-lock", type=Path, help="a weights-free build's upstream lock")
+    st.add_argument("--base-dir", type=Path, required=True)
+    st.add_argument("--calibration", type=Path, required=True)
+    st.add_argument("--provenance", type=Path, required=True, help="JSON merged into provenance")
+    st.add_argument("--readout", type=Path, help="JSON merged into readout.json")
+    st.add_argument("--card", type=Path)
+    st.add_argument("--results", type=Path, nargs="*", default=[])
+    st.add_argument("--extra", type=Path, nargs="*", default=[], help="licence and terms files")
+    st.add_argument("--out", type=Path, required=True)
+    card = sub.add_parser("card")
+    card.add_argument("--template", type=Path, default=Path("docs/model-cards/TEMPLATE.md"))
+    card.add_argument("--values", type=Path, required=True, help="JSON {key: text}")
+    card.add_argument("--out", type=Path, required=True)
+    args = parser.parse_args(argv)
+    if args.cmd == "pin":
+        identity = pin(args.model, args.format, args.weights)
+        record: dict[str, str] = {
+            **identity,
+            "model_hash": f"{identity['repo']}@{identity['revision']}",
+        }
+        if args.base_dir:
+            from avrik_server.readout.prompt import template_sha256
+            from avrik_server.readout.smoke import _hf_tokenizer
+
+            record["template_sha256"] = template_sha256(
+                _hf_tokenizer(args.base_dir), "avrik", identity["revision"]
+            )
+        print(json.dumps(record, indent=1))
+        return 0
+    if args.cmd == "stage":
+        cal = json.loads(args.calibration.read_text(encoding="utf-8"))
+        try:
+            identity = (upstream_pin(read_lock(args.upstream_lock)) if args.upstream_lock
+                        else pin(args.model, args.format, args.weights))  # fmt: skip
+        except ValueError as error:
+            print(f"refused: {error}", file=sys.stderr)
+            return 3
+        build = f"{identity['repo']}@{identity['revision']}"
+        if cal.get("model_hash") != build:
+            bound = cal.get("model_hash")
+            print(f"refused: {args.calibration} is bound to {bound}, not {build}", file=sys.stderr)
+            return 3
+        readout = json.loads(args.readout.read_text()) if args.readout else None
+        try:
+            out = stage(model=args.model, fmt=args.format, weights=args.weights,
+                        base_dir=args.base_dir, calibration=args.calibration, out=args.out,
+                        provenance=json.loads(args.provenance.read_text()), card=args.card,
+                        results=args.results, readout=readout,
+                        upstream_lock=args.upstream_lock, extra=args.extra)  # fmt: skip
+        except ValueError as error:
+            print(f"refused: {error}", file=sys.stderr)
+            return 3
+        print(out)
+        return 0
+    if args.cmd == "card":
+        values = json.loads(args.values.read_text(encoding="utf-8"))
+        try:
+            print(render_card(args.template, values, args.out))
+        except CardError as error:
+            print(f"refused: {error}", file=sys.stderr)
+            return 3
+        return 0
+    try:
+        print(upload(args.dir, args.repo, public=args.public))
+    except (ValueError, ManifestError) as error:
+        print(f"refused: {error}", file=sys.stderr)
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

avrik-1.0.0/src/avrik_cli/releases.py

@@ -0,0 +1,50 @@
+"""Published releases this ``avrik`` version trusts (security review T066, S1).
+
+``avrik pull`` downloads a release at the commit listed here and refuses it unless its
+``MANIFEST.sha256`` has the listed sha256. A downloaded manifest can't vouch for itself,
+so the trusted digest ships inside the package. Day 7 (T061/T062) fills this in when the
+repos are uploaded. ``pull --revision`` with ``--manifest-sha256`` covers releases newer
+than this package.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class Release(NamedTuple):
+    """One published Hugging Face repo at one commit."""
+
+    repo: str
+    commit: str
+    manifest_sha256: str
+
+
+# key: (model, format), e.g. ("Avrik-Lite-4B", "gguf")
+RELEASES: dict[tuple[str, str], Release] = {
+    ("Avrik-Lite-4B", "gguf"): Release(
+        "avrik-ai/Avrik-Lite-4B-GGUF",
+        "b52cdce83c998c49a66dd44b9c1cd05f7fc18d59",
+        "d008a6ccee3a4c1d1bd64369cec10f53179d35203e4c917b423032864adbab76",
+    ),
+    ("Avrik-Lite-4B", "bf16"): Release(
+        "avrik-ai/Avrik-Lite-4B",
+        "05ca5ed2faa1b853c3a80201bbebb30ad9d25714",
+        "f87feb81b75670d7550e8ad501e79560619d7bb97ffdde9e7d5a710e0bf5dc3f",
+    ),
+    ("Avrik-Pro-12B", "gguf"): Release(
+        "avrik-ai/Avrik-Pro-12B-GGUF",
+        "3361b4db25bf0e30b2db10404df748f059ee3ac7",
+        "afe2735afb68472bc0b2f630db827e20c8a449487922526143b91e48f7770721",
+    ),
+    ("Avrik-Pro-12B", "bf16"): Release(
+        "avrik-ai/Avrik-Pro-12B",
+        "1c52c6e0cd210cff279e4389f8d8c2d9de2b970e",
+        "04c221547f84cdd1401f5d61d2e6c6e76a90de19a4ab8c5fade31dfd9d7d95f4",
+    ),
+    ("Avrik-Max-31B", "fp8"): Release(
+        "avrik-ai/Avrik-Max-31B",
+        "ee7cb20d17e5512d61eb4f4ca1d5485d1bd3b082",
+        "f9e34c712fbdd18769589a989c1964a29e10ec2af419693e33c49e91e4134993",
+    ),
+}

avrik-1.0.0/src/avrik_cli/verify.py

@@ -0,0 +1,241 @@
+"""Release checks before any file is loaded (spec 004 FR-018, SC-008; security review T066).
+
+A release directory carries ``MANIFEST.sha256``, with lines ``<sha256>  <relative path>``
+in sha256sum format. :func:`verify_release` refuses the release unless all of these hold:
+
+- **Hashes:** every listed file exists inside the directory and matches its sha256.
+- **Nothing unlisted:** every file in the directory is listed. The only exception is
+  ``.cache/huggingface/``, the Hub's download bookkeeping, which is never loaded.
+- **No symlinks:** none anywhere, files or directories, because a link could point
+  outside the release.
+- **No code (B2):** no ``*.py``, ``*.pyc``, ``*.so``, ``*.dylib`` or ``*.dll`` file, and no
+  ``auto_map`` key in any JSON file, so Transformers never offers to run shipped code.
+- **Required files:** ``readout.json``, ``provenance.json``, ``.avrik-pin.json`` and
+  ``tokenizer.json``, plus the weights and the calibration that ``readout.json`` names
+  (``weights``, ``calibration``). Loaders use those names and never pick a file by
+  pattern.
+- **Weights-free builds** (``Avrik-Max-31B``; spec 004 research R17): ``readout.json``
+  names no weights and carries ``upstream: {repo, revision, lock}``. The lock
+  (``upstream.lock.json``, listed in the manifest) holds the sha256 of every file of the
+  pinned upstream revision, and the files themselves live in ``upstream/``. Every file
+  there must be exactly the lock's, under the same checks; ``upstream_required`` refuses
+  a release whose ``upstream/`` is missing (after ``avrik pull``).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+MANIFEST = "MANIFEST.sha256"
+IGNORED = (".cache", "huggingface")  # huggingface_hub's bookkeeping; never loaded
+CODE_SUFFIXES = (".py", ".pyc", ".so", ".dylib", ".dll")
+REQUIRED = ("readout.json", "provenance.json", ".avrik-pin.json", "tokenizer.json")
+UPSTREAM_LOCK = "upstream.lock.json"
+UPSTREAM_DIR = "upstream"
+
+
+class ManifestError(RuntimeError):
+    """A release fails a check; nothing in it may be loaded."""
+
+
+def sha256(path: Path) -> str:
+    """Hex sha256 of a file, streamed."""
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def read_manifest(root: Path) -> dict[str, str]:
+    """``{relative path: sha256}`` from ``root/MANIFEST.sha256``.
+
+    Raises:
+        ManifestError: When the manifest is missing or malformed.
+    """
+    path = root / MANIFEST
+    if path.is_symlink() or not path.is_file():
+        raise ManifestError(f"{root} has no {MANIFEST}")
+    out: dict[str, str] = {}
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if not line.strip():
+            continue
+        digest, sep, rel = line.partition("  ")
+        if not sep or len(digest) != 64:
+            raise ManifestError(f"malformed manifest line: {line[:80]!r}")
+        out[rel.strip()] = digest
+    return out
+
+
+def _ignored(rel: Path) -> bool:
+    """Under ``.cache/huggingface/``; anything else under ``.cache`` is checked."""
+    return rel.parts[: len(IGNORED)] == IGNORED
+
+
+def files_in(root: Path) -> list[Path]:
+    """Every file under ``root``, relative, outside the ignored path.
+
+    Raises:
+        ManifestError: On any symlink.
+    """
+    found: list[Path] = []
+    for directory, dirnames, filenames in os.walk(root, followlinks=False):
+        here = Path(directory)
+        for name in [*dirnames, *filenames]:
+            rel = (here / name).relative_to(root)
+            if not _ignored(rel) and (here / name).is_symlink():
+                raise ManifestError(f"{rel.as_posix()} is a symlink; a release may not hold links")
+        dirnames[:] = [d for d in dirnames if not _ignored((here / d).relative_to(root))]
+        found += [(here / f).relative_to(root) for f in filenames]
+    return sorted(f for f in found if not _ignored(f))
+
+
+def readout(root: Path) -> dict[str, Any]:
+    """The release's ``readout.json``; call :func:`verify_release` first."""
+    data: dict[str, Any] = json.loads((root / "readout.json").read_text(encoding="utf-8"))
+    return data
+
+
+def verify_release(root: Path, *, upstream_required: bool = False) -> int:
+    """Run every check in the module docstring; return how many files were hashed.
+
+    Raises:
+        ManifestError: Naming the first problem found.
+    """
+    root = root.resolve()
+    entries = read_manifest(root)
+    present = files_in(root)  # symlinks refused before anything is opened
+    for rel, digest in entries.items():
+        path = (root / rel).resolve()
+        if not path.is_relative_to(root):
+            raise ManifestError(f"manifest path escapes the release: {rel}")
+        if not path.is_file():
+            raise ManifestError(f"file {rel} is missing from the release")
+        if sha256(path) != digest:
+            raise ManifestError(f"file {rel} does not match the release manifest")
+    for name in REQUIRED:
+        if name not in entries:
+            raise ManifestError(f"the release has no {name}")
+    info = readout(root)
+    upstream = _upstream(root, info, entries)
+    listed = set(entries) | {MANIFEST}
+    pulled: list[Path] = []
+    for found in present:
+        if upstream is not None and found.parts[0] == UPSTREAM_DIR:
+            pulled.append(found)
+            continue
+        name = found.as_posix()
+        if name not in listed:
+            raise ManifestError(f"file {name} is not in the release manifest")
+        _no_code(root, found)
+    weights, calibration = info.get("weights"), info.get("calibration")
+    if not isinstance(weights, list) or not isinstance(calibration, str):
+        raise ManifestError("readout.json must name its weights and its calibration")
+    if bool(weights) == (upstream is not None):
+        raise ManifestError("readout.json must name weights, or an upstream lock, not both")
+    for name in [*weights, calibration]:
+        if name not in entries:
+            raise ManifestError(f"readout.json names {name}, which is not in the manifest")
+    hashed = len(entries)
+    if upstream is not None and (pulled or upstream_required):
+        hashed += _verify_upstream(root, upstream, pulled)
+    return hashed
+
+
+def _no_code(root: Path, found: Path) -> None:
+    name = found.as_posix()
+    if found.suffix in CODE_SUFFIXES:
+        raise ManifestError(f"file {name} is code; a release may not ship code")
+    if found.suffix == ".json" and _has_auto_map(root / found):
+        raise ManifestError(f"file {name} declares auto_map (remote code)")
+
+
+REPO = re.compile(r"[A-Za-z0-9._-]+/[A-Za-z0-9._-]+")
+COMMIT = re.compile(r"[0-9a-f]{40}")
+HEX64 = re.compile(r"[0-9a-f]{64}")
+# Root files the readout loads that also come from upstream; README.md is our card.
+FROM_UPSTREAM = ("tokenizer.json", "tokenizer_config.json", "chat_template.jinja",
+                 "special_tokens_map.json", "generation_config.json", "config.json",
+                 "processor_config.json", "preprocessor_config.json")  # fmt: skip
+
+
+def _upstream(root: Path, info: dict[str, Any], entries: dict[str, str]) -> dict[str, str] | None:
+    """The verified lock's files for a weights-free build, or None for one with weights.
+
+    The block, the lock and ``.avrik-pin.json`` must name the same ``org/name`` repo and
+    full 40-hex commit, and every tokenizer, template or config file at the root must
+    have the lock's sha256, so the readout and vLLM read the same files.
+    """
+    block = info.get("upstream")
+    if block is None:
+        return None
+    if not isinstance(block, dict) or block.get("lock") != UPSTREAM_LOCK:
+        raise ManifestError(f"readout.json upstream must name its lock, {UPSTREAM_LOCK}")
+    if UPSTREAM_LOCK not in entries:
+        raise ManifestError(f"{UPSTREAM_LOCK} is not in the release manifest")
+    repo, revision = block.get("repo"), block.get("revision")
+    if not isinstance(repo, str) or not REPO.fullmatch(repo):
+        raise ManifestError(f"readout.json upstream repo {repo!r} is not org/name")
+    if not isinstance(revision, str) or not COMMIT.fullmatch(revision):
+        raise ManifestError(f"upstream {repo}@{revision} is not pinned to a full commit")
+    try:
+        lock = json.loads((root / UPSTREAM_LOCK).read_text(encoding="utf-8"))
+        pin = json.loads((root / ".avrik-pin.json").read_text(encoding="utf-8"))
+    except (ValueError, UnicodeDecodeError) as error:
+        raise ManifestError(f"{UPSTREAM_LOCK} or .avrik-pin.json is not valid JSON") from error
+    if not isinstance(lock, dict) or not isinstance(pin, dict):
+        raise ManifestError(f"{UPSTREAM_LOCK} and .avrik-pin.json must be JSON objects")
+    if (lock.get("repo"), lock.get("revision")) != (repo, revision):
+        raise ManifestError("readout.json upstream does not match its lock")
+    if (pin.get("repo"), pin.get("revision")) != (repo, revision):
+        raise ManifestError(".avrik-pin.json does not name the upstream lock's revision")
+    files = lock.get("files")
+    if not isinstance(files, dict) or not files:
+        raise ManifestError(f"{UPSTREAM_LOCK} lists no files")
+    for name, digest in files.items():
+        if not isinstance(name, str) or not isinstance(digest, str) or not HEX64.fullmatch(digest):
+            raise ManifestError(f"{UPSTREAM_LOCK} has a malformed entry for {name!r}")
+        if name in FROM_UPSTREAM and name in entries and entries[name] != digest:
+            raise ManifestError(f"file {name} differs from the upstream lock's {name}")
+    return dict(files)
+
+
+def _verify_upstream(root: Path, lock: dict[str, str], pulled: list[Path]) -> int:
+    """``upstream/`` holds exactly the lock's files, each matching; return the count."""
+    here = root / UPSTREAM_DIR
+    found = {p.relative_to(UPSTREAM_DIR).as_posix(): p for p in pulled
+             if not _ignored(p.relative_to(UPSTREAM_DIR))}  # fmt: skip
+    for name in sorted(set(found) - set(lock)):
+        raise ManifestError(f"file {UPSTREAM_DIR}/{name} is not in the upstream lock")
+    for name, digest in sorted(lock.items()):
+        path = (here / name).resolve()
+        if not path.is_relative_to(here.resolve()):
+            raise ManifestError(f"upstream lock path escapes the release: {name}")
+        if name not in found or not path.is_file():
+            raise ManifestError(f"upstream file {name} is missing; run avrik pull")
+        if sha256(path) != digest:
+            raise ManifestError(f"upstream file {name} does not match the upstream lock")
+        _no_code(root, found[name])
+    return len(lock)
+
+
+def _has_auto_map(path: Path) -> bool:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, UnicodeDecodeError) as error:
+        raise ManifestError(f"{path.name} is not valid JSON") from error
+    stack: list[Any] = [data]
+    while stack:
+        item = stack.pop()
+        if isinstance(item, dict):
+            if "auto_map" in item:
+                return True
+            stack.extend(item.values())
+        elif isinstance(item, list):
+            stack.extend(item)
+    return False