Metadata-Version: 2.4
Name: szl-serve
Version: 0.1.0
Summary: Canonical SZL governed-inference serve recipe: pinned Khipu GGUF, schema validation outside the weights, honest energy receipts. Not a vendor engine.
Author: Stephen P. Lutar Jr., SZL Holdings
License: Apache-2.0
Project-URL: Homepage, https://a-11-oy.com
Project-URL: Repository, https://github.com/szl-holdings/szl-serve
Project-URL: Hugging Face GGUF, https://huggingface.co/SZLHOLDINGS/SZL-Khipu-1.5B-GGUF
Project-URL: MEASURED CPU lab (FORGE-owned), https://szlholdings-szl-model-inference-lab.hf.space
Project-URL: Space card, https://huggingface.co/spaces/SZLHOLDINGS/szl-model-inference-lab
Project-URL: Issues, https://github.com/szl-holdings/szl-serve/issues
Project-URL: Changelog, https://github.com/szl-holdings/szl-serve/releases
Keywords: governed-inference,llama.cpp,ollama,gguf,receipts,energy,szl-holdings
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.18
Provides-Extra: energy
Requires-Dist: szl-energy-attest>=0.3.0; extra == "energy"
Provides-Extra: gpu
Requires-Dist: pynvml>=11.0; extra == "gpu"
Provides-Extra: sign
Requires-Dist: szl-receipt-dsse>=0.3.1; extra == "sign"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: setuptools>=61; extra == "test"
Requires-Dist: wheel; extra == "test"
Dynamic: license-file

# szl-serve

**One OpenAI-shaped chat call. One pinned weight. One receipt.**

KERNEL-owned canonical governed-inference **recipe + validator + energy receipt** for SZL Holdings.

<!-- szl:header v1 -->
<!-- Native identity: szl-brand@4309f6fce89179331b0b3ed8c99494e76c5be256; Orbit v2 icon. -->
<p>
  <a href="https://github.com/szl-holdings">
    <img src="https://raw.githubusercontent.com/szl-holdings/szl-brand/4309f6fce89179331b0b3ed8c99494e76c5be256/kit/logos/orbit-v2/suite/szl-icon-32.svg" alt="SZL Holdings — Orbit v2" width="32" height="32" />
  </a>
</p>

**Control before action. Evidence after.**

[Product](https://a-11-oy.com) · [Proof](https://a11oy.net) · [GitHub organization](https://github.com/szl-holdings)
<!-- /szl:header -->

This is **not** a vendor engine. It is the silhouette of 2026 serving (vLLM / SGLang / TGI / TensorRT-LLM / llama.cpp / Dynamo) — without copying those engines, and without fabricating tokens/s or joules.

Homepage: [a-11-oy.com](https://a-11-oy.com) · Owner: Stephen P. Lutar Jr. / SZL Holdings · Doctrine v11 LOCKED **749/14/163** · Λ = **Conjecture 1** (advisory, never a theorem) · Apache-2.0

---

## What this is NOT

- **Not vLLM. Not TGI. Not TensorRT-LLM. Not SGLang. Not Dynamo.** Those names are the 2026 silhouette. This repo does not vendor-copy them. GPU path is **ROADMAP** until MEASURED on named hardware.
- **Not a tokens/s leaderboard.** A MEASURED sample is raw completion tokens + `elapsed_ms`. No derived tok/s rating.
- **Not proven trust.** A hash-chained receipt proves integrity of that record. It does not prove the model, the lab, or Λ.
- **Not a takeover of the Hugging Face Space.** FORGE owns [`szl-holdings/szl-forge`](https://github.com/szl-holdings/szl-forge) / [`SZLHOLDINGS/szl-model-inference-lab`](https://huggingface.co/spaces/SZLHOLDINGS/szl-model-inference-lab). This KERNEL repo **pins** that MEASURED lab as the live CPU path. It does not invent a second runtime.
- **Not [`szl-forge-lab`](https://huggingface.co/spaces/SZLHOLDINGS/szl-forge-lab).** That Space is **SNAPSHOT / READ-ONLY**, not a trainer, not a serve runtime. Do not point `szl-serve` at forge-lab.
- **Not Ask & Act as a live control plane.** The a11oy operator tab does not gate, launch, or control this recipe.
- **Not energy-attested-runs as MEASURED serve energy.** That corpus is **8/8 SIMULATED**, not an NVML joule delta and not a live serve path.

Honesty plate: [`CARD.md`](CARD.md).

---

## ATELIER lock

**Serve studio = `SZLHOLDINGS/szl-model-inference-lab` only.** GPU remains **ROADMAP**.

| Surface | Class |
|---|---|
| `SZLHOLDINGS/szl-model-inference-lab` | **LIVE / MEASURED** serve studio (this pin) |
| `SZLHOLDINGS/szl-forge-lab` | **SNAPSHOT**, not a trainer, **not a serve target** |
| GPU / vLLM / TGI / TensorRT-LLM / SGLang / Dynamo | **ROADMAP** |
| `SZLHOLDINGS/energy-attested-runs` | **8/8 SIMULATED** — not this recipe's CPU energy evidence |
| Ask & Act | **not a live control plane** |

---

## LIVE CPU (MEASURED) — pin this lab, do not invent a second runtime

ATELIER serve studio. **Not** `szl-forge-lab`.

| | |
|---|---|
| Surface | https://szlholdings-szl-model-inference-lab.hf.space |
| Space | https://huggingface.co/spaces/SZLHOLDINGS/szl-model-inference-lab |
| FORGE source | [`e28abe9d4be3ce5efbb09ea2a3a248494c654636`](https://github.com/szl-holdings/szl-forge/tree/e28abe9d4be3ce5efbb09ea2a3a248494c654636/spaces/szl-model-inference-lab) |
| API | OpenAI subset `POST /v1/chat/completions` |
| Model | `SZLHOLDINGS/SZL-Khipu-1.5B-GGUF@67d60ec577730747055491640cfb91fc4a4b5d25` |
| GGUF | `SZL-Khipu-1.5B-Q4_K_M.gguf` · SHA-256 `13c1a1993063e1dff92f7413ccf48eaca6d48efc8801ae9af35961ae3396623a` · 986047904 bytes |
| Sample 2026-11-04 | **24** completion tokens · **elapsed_ms 8237** · execution_record **UNSIGNED** · evidence [`measured-cpu-serve-20261104.json`](evidence/measured-cpu-serve-20261104.json) |
| Energy | `joules=null` · label **UNAVAILABLE** (CPU lab; MEASURED only from a real NVML delta) |
| GPU | **ROADMAP** until MEASURED on named hardware |
| SLA | Best-effort public demo. No provider SLA. Dummy bearer `not-a-secret` only — never a real token. |

```bash
curl https://szlholdings-szl-model-inference-lab.hf.space/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer not-a-secret" \
  -d '{"model":"SZLHOLDINGS/SZL-Khipu-1.5B-GGUF@67d60ec577730747055491640cfb91fc4a4b5d25","messages":[{"role":"user","content":"Explain one limit of cryptographic receipts."}],"max_tokens":24,"stream":false}'
```

Contract: `/.well-known/szl-inference-contract.json`. Identity: `/api/v1/identity`.

---

## Read-only runtime qualification

The pinned recipe can drift from the public Space. `qualify` reads four bounded
JSON surfaces and emits one receipt with per-field `OBSERVED`, `DIVERGENT`, or
`UNKNOWN` states:

```bash
szl-serve qualify --output qualification.json
```

The command checks `/api/build-info`, `/api/v1/identity`,
`/.well-known/szl-inference-contract.json`, and `/v1/models`. It requires the
exact Forge source repository and revision, model revision, GGUF file, byte
count, SHA-256, contract schema, and model-list identity. A timeout, partial
JSON, HTML response, oversized response, cross-origin redirect, missing field,
or stale value never becomes success. The current public contract may report
`UNKNOWN` for source repository until `/api/build-info` exposes that field;
the qualifier does not infer it from a URL or Space name.

Qualification is read-only. It sends no prompt, mints no signed release
receipt, changes no provider state, and says nothing about response quality,
safety, SLA, or production readiness.

---

## Airgap twin — same pin, local llama.cpp / Ollama

Local llama.cpp and Ollama run the **same** Q4_K_M bytes. They are the airgap twin of the Space, **not** a clone of vLLM.

```bash
llama-cli    -hf SZLHOLDINGS/SZL-Khipu-1.5B-GGUF:Q4_K_M
llama-server -hf SZLHOLDINGS/SZL-Khipu-1.5B-GGUF:Q4_K_M
ollama run hf.co/SZLHOLDINGS/SZL-Khipu-1.5B-GGUF:Q4_K_M
```

Print the recipe (no GGUF download):

```bash
python -m szl_serve recipe
```

Generated command strings target POSIX shells (`sh`/Bash). Prompts, the JSON
request body, and server host/port values are quoted as literal arguments;
shell substitutions inside them are not executed. PowerShell and `cmd.exe`
use different quoting rules and are not supported by these command generators.
The generators print recipes only; the selected engine validates host/port values.

---

## Controller — schema outside the weights

Model output is **proposal-only**. Copy of [`khipu.schema.json`](schemas/khipu.schema.json) is pinned from the GGUF repo (SHA-256 `b95f9927366dae7c5d36cfb7de6e229eb605524318ab642a6aa2292a212170d0`).

Built wheels include this exact 6,262-byte schema and its `PIN.json` under
`szl_serve/schemas/`. The validator prefers these package resources; source
checkouts use the canonical root `schemas/` copy. Git preserves LF bytes for
both JSON files on Windows as well as Linux. Schema bytes and the SHA-256 pin
remain strict: a drifted packaged schema is rejected, rather than normalized
or replaced with a fallback copy.

- Hallucinated `citedNodeIds` → **REJECT**. Never silently repaired into a green plan.
- `brainBinding.status` stays **NOT_RESOLVED**.
- Real model output provenance is **MODEL_PROPOSED**, not `SYNTHETIC`.
- Calls using `source="MODEL"` require controller-provided `offered_ids`;
  the model's own candidate list cannot establish grounding. An empty list
  explicitly means no handles were offered and still enforces rejection.
- Invalid JSON / cross-field contract failure → fail closed (`REJECT`).

The CLI examples below check schema and internal consistency (`source="UNKNOWN"`).
They do not establish that handles were independently offered to a real model.

```bash
python -m szl_serve validate tests/fixtures/plan_model_proposed.json
python -m szl_serve validate tests/fixtures/plan_hallucinated_cited.json   # exits 1
```

---

## Energy + receipt

Each wrap uses `szl-energy-attest` semantics (import if available, else a tiny honest local meter):

| Energy | When |
|---|---|
| **MEASURED** | Real NVML energy-counter delta. `joules` is that number. |
| **UNAVAILABLE** | No GPU / no fresh NVML delta (the CPU lab and this CI). `joules=null`. |

Never invent a joule. Hash-chain a serve receipt: request hash, output hash, model pin, energy label. Receipt is **UNSIGNED** unless a key is actually present. Do not fake DSSE.

---

## MEASURED vs ROADMAP vs UNAVAILABLE

| Surface | Label |
|---|---|
| FORGE Space CPU OpenAI subset + GGUF pin + 2026-11-04 sample | **MEASURED** |
| llama.cpp / Ollama commands for the same pin | **LIVE recipe** (airgap twin) |
| Energy on CPU | **UNAVAILABLE** |
| GPU / vLLM / TGI / TensorRT-LLM / SGLang / Dynamo | **ROADMAP** |
| GPU attention | **ROADMAP** — no fused/paged-attention LIVE claim; no tokens/s invented |
| Speculative decode (`szl-specdecode`) | **SPECDECODE=UNAVAILABLE** until soft-import LIVE — see below |
| `SZLHOLDINGS/szl-forge-lab` | **SNAPSHOT** — not a trainer; do not point this recipe at it |
| `SZLHOLDINGS/energy-attested-runs` | **8/8 SIMULATED** — not MEASURED NVML; not a live serve path |
| Ask & Act | **not a live control plane** |
| Chaski, ReceiptAgent weights | **ROADMAP** stubs on this config surface — not fake LIVE |

Λ is Conjecture 1. It does not become a theorem because a chat call returned 21 tokens.

---

## Speculative decode silhouette (optional)

Pointer to [`szl-holdings/szl-specdecode`](https://github.com/szl-holdings/szl-specdecode) (HF twin [`SZLHOLDINGS/szl-specdecode`](https://huggingface.co/SZLHOLDINGS/szl-specdecode)). Soft-imports `szl_specdecode.verify_draft` when that package is installed; otherwise labels **SPECDECODE=UNAVAILABLE**. GPU draft kernels stay **UNAVAILABLE**. Speedup claim stays **null** until a MEASURED draft/target pair receipt exists. Not a rehost of Medusa, EAGLE, TensorRT-LLM speculative decoding, or vLLM. Credit Stephen Lutar. MEASURED-or-null.

```python
from szl_serve.specdecode import probe_specdecode, get_verify_draft

probe_specdecode()           # {"label": "SPECDECODE=UNAVAILABLE", ...} or import-LIVE
get_verify_draft()           # callable or None — never fabricates tokens/s
```

---

## Tests

Unit tests use fixture plan JSON. **No network. Do not download the ~1 GB GGUF in CI.**
The packaging regression builds a wheel and an sdist-to-wheel round trip with
installed build tools and no package index, then installs the wheel into a
temporary target. An isolated Python subprocess outside the checkout checks
the exact schema and pin, validates a benign synthetic ABSTAIN proposal, and
confirms that tampered package data fails closed. Build tooling is a test extra.

```bash
python -m pip install --require-hashes -r requirements/test.lock
python -m pip install --no-deps -e .
pytest -q
```

`requirements/test.lock` is a universal hash-locked closure generated from the
published package metadata at the declared Python 3.10 floor, with an
`exclude-newer` cutoff of 2026-11-02 UTC.
Library compatibility ranges remain in `pyproject.toml`; the lock controls CI
and review reproduction without narrowing downstream consumers.

---

## Layout

```
LICENSE                 Apache-2.0, Copyright 2026 SZL Holdings
README.md               this Series A face
CARD.md                 honesty plate
schemas/khipu.schema.json
szl_serve/{__init__,schema,energy,recipe,cli}.py
tests/fixtures/*.json
```

---

<div align="center">

**Governed AI you can pin — not a leaderboard you can fake.**

[a-11-oy.com](https://a-11-oy.com) · [Khipu GGUF](https://huggingface.co/SZLHOLDINGS/SZL-Khipu-1.5B-GGUF) · [MEASURED lab (FORGE)](https://huggingface.co/spaces/SZLHOLDINGS/szl-model-inference-lab)

<sub>SLSA: L1 honest · L2 attested · L3 roadmap. Λ = Conjecture 1. Trust ceiling 0.97 — never 100%.</sub>

</div>
