diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c856c631d..398302ec6 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -60,6 +60,7 @@ jobs: python3 tests/mtp_draft_vocab_test.py python3 tests/check_pins_test.py python3 tests/hrx_long_prompt_test.py + python3 tools/template_bom.py --self-test # the chat-template BOM component - name: Configure run: cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=gcc-16 -DCMAKE_CXX_COMPILER=g++-16 - name: Build diff --git a/docs/template-publishing.md b/docs/template-publishing.md index 90c48210d..48ecd83ca 100644 --- a/docs/template-publishing.md +++ b/docs/template-publishing.md @@ -137,3 +137,21 @@ instead of only checking a pin. No upstream filing, no vendor contact: this is a proposal for our own BOM output (`tools/` and the release packages) and for the cards we publish. + +**`tools/template_bom.py` emits exactly that component** for a `.gguf` or a model directory — the digest +in `hashes`, the file it came from in `properties`, `--bom` for a whole CycloneDX 1.6 document, and a +component with **no** hash and a description for a model that carries no template (so "no template" is a +verifiable claim in the BOM too): + +```console +$ tools/template_bom.py --bom ~/models/zaya1-8b-Q4_K_M.gguf +{"bomFormat": "CycloneDX", "specVersion": "1.6", "version": 1, "components": [ + {"type": "data", "bom-ref": "pkg:generic/zaya1-8b-Q4_K_M.gguf?chat-template", + "name": "tokenizer.chat_template", + "hashes": [{"alg": "SHA-256", "content": "b55ecfbbbcbb238a011465bfa139366db18790103f9205060cf2855a3f51b30f"}], …}]} +``` + +That digest is the same one `1bit serve` prints at load, so the BOM, the log and the card row agree by +construction rather than by bookkeeping. Both branches hash the bytes as stored — a container whose +`chat_template.jinja` is CRLF gets its `sha256sum`, not a newline-normalised variant — because that is +what the serve path hashes too. diff --git a/tools/template_bom.py b/tools/template_bom.py new file mode 100755 index 000000000..f68a662fd --- /dev/null +++ b/tools/template_bom.py @@ -0,0 +1,227 @@ +#!/usr/bin/env python3 +# Copyright 2026 bong-water-water-bong +# SPDX-License-Identifier: Apache-2.0 +# +# 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. +"""The chat template as a CycloneDX component, so a BOM can sign and diff it. + +A `tokenizer.chat_template` is a Jinja program the llama.cpp-family backends run on every request, and +it has no name, no digest and no place in a dependency graph — which is why it escapes review. Give it +the shape of a component and the tools that already read a BOM start covering it: the digest goes in +`hashes`, where it came from goes in `properties`, and "the weights are the same file and the template +is not" becomes a component difference instead of an invisible substitution +(docs/template-publishing.md, "Proposal: the chat template as a signed part"). + +usage: tools/template_bom.py [--bom | --sums] [--self-test] PATH... + + PATH a .gguf file, or a model directory (Q4NX/NPU container) — the template is read from the GGUF's + metadata header, or from the directory's tokenizer_config.json `chat_template`, else + `chat_template.jinja` beside it. Only the header is read; the tensors never are. + --bom emit one CycloneDX 1.6 document with a component per PATH; without it, one component per line + (JSON Lines), so it composes with the other tools. + --sums emit the `SHA256SUMS` lines instead — ` #tokenizer.chat_template` for a `.gguf`, + `/#chat_template` for a container — the row a published file needs + (docs/template-publishing.md). 'none' models print nothing, so the file stays clean. + --self-test build three tiny fixtures (a GGUF with a template, a container directory whose template is + LF and CRLF, and a model that carries none) and check the components this tool derives from them. + +Exit codes: 0 all paths read, 1 a path could not be read, 3 --self-test failed. +""" +from __future__ import annotations + +import hashlib +import json +import os +import sys +import tempfile + +SPEC_VERSION = "1.6" + + +def read_template(path: str) -> tuple[bytes | None, str | None]: + """(the template bytes as stored, where they came from) — `(None, None)` when the model carries none. + + Bytes, never decoded text: the served side (`container_chat_template_sha()`, `app/template_pin.h`) + hashes the raw file and so does `sha256sum`, so a text read's newline translation would name a + digest the file does not have — on a CRLF container that is a different sha256 for one template. + """ + if os.path.isdir(path): + cfg = os.path.join(path, "tokenizer_config.json") + if os.path.exists(cfg): + try: + with open(cfg, encoding="utf-8") as f: + t = json.load(f).get("chat_template") + if isinstance(t, str) and t: + # a JSON string value carries no raw newline, so this equals the C++ json read + return t.encode(), "tokenizer_config.json" + except Exception: + pass + jinja = os.path.join(path, "chat_template.jinja") + if os.path.exists(jinja): + with open(jinja, "rb") as f: + return f.read(), "chat_template.jinja" + return None, None + import gguf # only for a .gguf: keeps --self-test's directory case dependency-free + + reader = gguf.GGUFReader(path) + field = reader.fields.get("tokenizer.chat_template") + if field is None: + return None, None + return bytes(field.parts[-1]), "GGUF metadata (tokenizer.chat_template)" + + +def component(path: str) -> dict: + tpl, source = read_template(path) + ref = "pkg:generic/" + os.path.basename(os.path.abspath(path.rstrip("/"))) + "?chat-template" + props = [ + {"name": "onebit:template:path", "value": os.path.abspath(path)}, + {"name": "onebit:template:source-file", "value": source or "none"}, + ] + if tpl is None: + return { + "type": "data", + "bom-ref": ref, + "name": "tokenizer.chat_template", + "description": "no chat template in this model (a base model, an mmproj, or a container without one)", + "properties": props, + } + props.insert(1, {"name": "onebit:template:bytes", "value": str(len(tpl))}) + return { + "type": "data", + "bom-ref": ref, + "name": "tokenizer.chat_template", + "hashes": [{"alg": "SHA-256", "content": hashlib.sha256(tpl).hexdigest()}], + "properties": props, + } + + +def sums_line(path: str) -> str | None: + """The `SHA256SUMS` line for PATH, or None when the model carries no template.""" + tpl, source = read_template(path) + if tpl is None: + return None + sha = hashlib.sha256(tpl).hexdigest() + if os.path.isdir(path): + return f"{sha} {os.path.join(path, os.path.basename(source)) if source else path}#chat_template" + return f"{sha} {os.path.basename(path)}#tokenizer.chat_template" + + +def self_test() -> int: + import struct + + failures = 0 + + def expect(what: str, got, want) -> None: + ok = got == want + print(f"{'ok ' if ok else 'FAIL'} {what}: {got!r}") + nonlocal failures + failures += 0 if ok else 1 + + tpl = "{% for m in messages %}{{ '' ~ m['role'] }}{% endfor %}assistant\\n" + with tempfile.TemporaryDirectory() as d: + # a header-only GGUF carrying the template, written the way a real one stores it + def s(x: str) -> bytes: + b = x.encode() + return struct.pack(" int: + if "--self-test" in argv: + return self_test() + as_bom = "--bom" in argv + as_sums = "--sums" in argv + paths = [a for a in argv if not a.startswith("-")] + if not paths: + print(__doc__.strip().splitlines()[0], file=sys.stderr) + print("usage: tools/template_bom.py [--bom | --sums] [--self-test] PATH...", file=sys.stderr) + return 2 + comps, failed = [], False + for p in paths: + try: + comps.append(component(p)) + except Exception as e: + print(f"template_bom: {p}: {e}", file=sys.stderr) + failed = True + if as_sums: + for p in paths: + try: + line = sums_line(p) + except Exception: + line = None + if line: + print(line) + elif as_bom: + print(json.dumps({"bomFormat": "CycloneDX", "specVersion": SPEC_VERSION, "version": 1, + "components": comps}, indent=1)) + else: + for c in comps: + print(json.dumps(c, sort_keys=True)) + return 1 if failed else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:]))