Metadata-Version: 2.4
Name: szl-khipu
Version: 0.1.0
Summary: Governed-AI khipu: Λ-gate, YARQA canals, TinyKhipu silhouette, hash-chained receipts. Knot the run. Hash the proof. Fail closed.
Author: Stephen P. Lutar Jr. / SZL Holdings
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/szl-holdings/szl-khipu
Project-URL: Repository, https://github.com/szl-holdings/szl-khipu
Project-URL: Hugging Face, https://huggingface.co/SZLHOLDINGS/szl-khipu
Project-URL: ORCID, https://orcid.org/0009-0001-0110-4173
Project-URL: Issues, https://github.com/szl-holdings/szl-khipu/issues
Project-URL: Changelog, https://github.com/szl-holdings/szl-khipu/releases
Keywords: governed-ai,khipu,lambda-gate,yarqa,receipts
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.26
Provides-Extra: gradio
Requires-Dist: gradio<7,>=6.27.0; extra == "gradio"
Provides-Extra: torch
Requires-Dist: torch>=2.5; extra == "torch"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: PyYAML<7,>=6.0; extra == "test"
Provides-Extra: hub
Requires-Dist: huggingface_hub>=0.24; extra == "hub"
Dynamic: license-file

---
license: apache-2.0
library_name: numpy
tags: [governed-ai, khipu, szl-holdings, receipts, lambda-gate]
---

<!-- SZL-CARD-PRESENTATION:v1 -->
<!-- Native identity: szl-brand@4309f6fce89179331b0b3ed8c99494e76c5be256; Orbit v2 icon sha256 6e2b7d72a3af3d9602b79de41df0194ede6496a9661f057108ec224c0efc92e6. -->
<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>

Orbit artwork: SZL Holdings / Stephen Lutar · [CC BY 4.0](https://github.com/szl-holdings/szl-brand/blob/4309f6fce89179331b0b3ed8c99494e76c5be256/kit/LICENSE) · [Trademark notice](https://github.com/szl-holdings/szl-brand/blob/4309f6fce89179331b0b3ed8c99494e76c5be256/NOTICE). Software and artifact rights remain declared in the original metadata and documentation.

# SZL Khipu

Inspect advisory NumPy kernels, small reference fixtures, and hash-chained run receipts.

**Artifact:** Python / NumPy software package · **Stage:** Software / reference

[Explore in Command Lab](https://huggingface.co/spaces/SZLHOLDINGS/szl-command-lab) · [Build](https://github.com/szl-holdings/szl-khipu) · [Evidence](https://github.com/szl-holdings/szl-khipu/blob/8d06c9333b636a86a27d88feb49097906833af30/README.md)

## Before you use it

- Λ is advisory: Conjecture 1 OPEN and proven_trust=false.
- CUDA and energy measurement are UNAVAILABLE; software source binding does not establish a production deployment.
- The package and Nano fixtures do not qualify a 1.5B checkpoint. Verify each artifact and its separate inference contract.

<details>
<summary>Technical details and evidence</summary>

<!-- SZL-CARD-TECHNICAL:v1:START -->

# szl-khipu
<!-- szl:header v1 -->
<!-- badges: add this repo's CI / release / status badges here -->
[![org: szl-holdings](https://img.shields.io/badge/org-szl--holdings-black)](https://github.com/szl-holdings)
[![doctrine](https://img.shields.io/badge/doctrine-control%20before%20action%20%C2%B7%20evidence%20after-blue)](https://a-11-oy.com)

**Control before action. Evidence after.**

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

**Knot the run. Hash the proof. Fail closed.**

Governed-AI khipu: an advisory Λ-gate, original YARQA canal attention, a TinyKhipu NAVIGATE/ABSTAIN silhouette, and hash-chained receipts. CPU numpy is LIVE. CUDA is UNAVAILABLE. energy UNAVAILABLE. `proven_trust` is always false.

Canonical GitHub source: [szl-holdings/szl-khipu](https://github.com/szl-holdings/szl-khipu)  
Hub card: [SZLHOLDINGS/szl-khipu](https://huggingface.co/SZLHOLDINGS/szl-khipu)  
Kernels: [SZLHOLDINGS/szl-khipu-kernels](https://huggingface.co/SZLHOLDINGS/szl-khipu-kernels)

The canonical `publish-hf` workflow mirrors `szl_khipu/`, `README.md`, `LICENSE`,
and `pyproject.toml` from immutable Git blobs in one Hub model commit. Its
`MODEL_SOURCE_BINDING.json` records the Git commit, tree, and each file digest;
publication succeeds only after immutable provider readback matches every byte.
Historical Hub files outside this software scope are preserved and are not
attested by this binding. Software parity makes no trained-checkpoint claim.

## What it is

- A Python package (`szl_khipu`) that knots a run, hashes a receipt, and fail-closes on a zero axis or a broken chain.
- Λ: weighted geometric mean over 13 Yuyay axes, advisory, never proven trust.
- YARQA: contiguous canals; attend only inside the compartment; leak is the bound.
- TinyKhipu-Nano: NAVIGATE / ABSTAIN silhouette. A few thousand floats. Hard ID filter.
- ReceiptAgent-Nano: the reviewed `szl_khipu/train/receipt_agent.py` defines
  `0=ALLOW`, `1=WARN`, `2=BLOCKED`, `3=ESCALATE`. The deterministic
  `rule_check` decision remains authoritative; learned predictions do not
  override it. This software binding does not attest the sibling archive, its
  card, or its historical training/class-index contract.
- Receipts: sha256 of weights, seed, steps, loss. Honesty **REPORTED**. Joules **null**.
- Organ integrity: five-organ fail-closed kernel of [szl-holdings/anatomy](https://github.com/szl-holdings/anatomy). HEART/YUYAY, YAWAR, YACHAY, OTel, Khipu skeleton. Not a Three.js rehost. The 3D atlas is SLSA L1 static viz.

## What it is NOT

- **Not Qwen.** Not a Qwen fine-tune, not a Qwen rehost, not a Qwen eval.
- **Not 1.5B.** Nothing in this tree trains or publishes SZL-Khipu-1.5B, KHIPU-R2, or ReceiptAgent 1.5B. Those Hub cards stay RESEARCH and are not produced here.
- **Not a FlashAttention rehost.** Not Dao `.cu`, not hopper/, not cute/, not Sage `csrc`, not vLLM paged `.cu`, not `flex_attention.py`.
- **Λ uniqueness is OPEN.** Conjecture 1 is not a theorem. Unconditional uniqueness under kernel A1–A5 is machine-checked FALSE.
- **Energy UNAVAILABLE.** Never a fabricated joule. MEASURED-NVML or honest null.
- Not trained weights at 1–2B. Not GGUF. Not a CUDA speedup. Not proven trust.

## Install

```bash
pip install -e .
pip install -e ".[gradio]"   # optional — Gradio 6 demo; gradio>=6.27.0,<7
pip install -e ".[torch]"    # optional — torch path; CUDA still UNAVAILABLE here
```

Requires Python ≥ 3.11. Runtime dep: `numpy>=1.26`. Apache-2.0.

## Verify

```bash
pip install -e ".[test]"
python -m pytest -q tests                  # package suite (CI also runs it as `python -m unittest discover -s tests`)
szl-khipu verify artifacts/TRAINING_RECEIPT.json   # recompute the committed archives' sha256 (exit 1 on any mismatch)
(cd hardware/khipu-x1 && pip install -e ".[dev]" && python -m pytest -q)   # KHIPU-X1 software reference
```

The Gradio demo has its own pinned install and real-SDK smoke test; see [spaces/README.md](spaces/README.md).

## Python frontend + backend

Stdlib HTTP. Same process serves the holographic UI and runs the kernels. No Gradio required.

```bash
szl-khipu serve --host 0.0.0.0 --port 7860
# GET          /  /healthz  /version  /api/version  /.well-known/szl-source.json
# GET or POST  /api/lambda  /api/anatomy  /api/greenlight  /api/yarqa  /api/tiledigest
#              /api/prefix  /api/route  /api/bench  /api/infer
```

A malformed request is an explicit 4xx with its reason, never a default-filled 200.
`/api/infer` reports which weights answered: the committed `artifacts/*.npz`
(with its sha256) in a checkout or the Space, or a small on-request build when a
wheel install has no `artifacts/`.

Gold = OPEN. Proof teal = LIVE. Never green-as-proven. Energy UNAVAILABLE. Conjecture 1 stays OPEN.

Static JS silhouette (not the NumPy kernel): [docs/index.html](docs/index.html) · live at [holdings.a-11-oy.com/khipu/](https://holdings.a-11-oy.com/khipu/) (served by [szl-holdings/szl-holdings.github.io](https://github.com/szl-holdings/szl-holdings.github.io/blob/main/khipu/index.html)). The former `khipu-pages` repository is archived.

## Quickstart

### Lambda (advisory)

```python
from szl_khipu import evaluate_lambda, YUYAY_FLOORS

ev = evaluate_lambda(list(YUYAY_FLOORS))
print(ev.value, ev.blocked, ev.reason)
# advisory pass — uniqueness remains Conjecture 1 OPEN

zeroed = list(YUYAY_FLOORS)
zeroed[0] = 0.0
print(evaluate_lambda(zeroed).blocked)  # True — fail closed
```

CLI:

```bash
szl-khipu demo-lambda
szl-khipu demo-lambda --zero 0
```

### YARQA (canal leak)

```python
import numpy as np
from szl_khipu import yarqa_attn

q = k = v = np.random.default_rng(7).standard_normal((12, 4))
out = yarqa_attn(q, k, v, n_canals=3)
print(out.leaked)  # bound: leaked ≤ 1e-9
```

```bash
szl-khipu demo-yarqa --n-canals 3
```

For numerical output without dense probability diagnostics, use
`yarqa_attn_output(q, k, v, n_canals=3)`. This NumPy path computes query tiles
inside each canal and avoids full sequence-square score/probability matrices.
The [API contract and reproducible CPU comparison](https://github.com/szl-holdings/szl-khipu/blob/e53e3d24b22e356eb986c373aee27b3b3e7947ec/docs/YARQA_OUTPUT_ONLY.md)
document validation, memory limits, attribution, and measurement boundaries
at the reviewed source commit. This document is outside the model software
mirror scope and is not included in that Hub model snapshot.

### Organ integrity (five organs)

Fail-closed substrate. Any DOWN organ or a WILLAY veto blocks the body. Λ stays Conjecture 1 OPEN. Energy UNAVAILABLE. Locked-proven stays 8. Not a Three.js rehost.

```python
from szl_khipu import evaluate_anatomy

ev = evaluate_anatomy(seed=11)
print(ev.live_count, ev.blocked, ev.energy)  # 5 False UNAVAILABLE

print(evaluate_anatomy(zero_heart=True).blocked)        # True
print(evaluate_anatomy(fabricate_joule=True).energy_j)  # None — never a fabricated joule
```

```bash
szl-khipu demo-anatomy
szl-khipu demo-anatomy --tamper-chain
szl-khipu demo-anatomy --fabricate-joule
```

Canonical anatomy repo: [szl-holdings/anatomy](https://github.com/szl-holdings/anatomy) · 3D atlas: [SZLHOLDINGS/anatomy](https://huggingface.co/spaces/SZLHOLDINGS/anatomy)

### Train TinyKhipu

```bash
szl-khipu train --seed 20260721 --steps 280 --out runs/tinykhipu
# writes runs/tinykhipu/tiny_khipu.npz + runs/tinykhipu/training_receipt.json
szl-khipu verify runs/tinykhipu/training_receipt.json
# exit 1 if a declared file is missing or its sha256 differs
```

`--out` defaults to `runs/tinykhipu` under the working directory. Keep runs out
of `artifacts/`, which holds the committed, Hub-published export.

```python
from szl_khipu import train_tiny_khipu

result = train_tiny_khipu(seed=20260721, steps=280)
print(result.plan_valid, result.abstain, result.hallucinated)
```

Export all three silhouettes (TinyKhipu, ReceiptAgent, moons), the MiniEmbed table and a combined receipt:

```bash
python scripts/train_and_export.py --out runs/export
# runs/export/*.npz + runs/export/TRAINING_RECEIPT.json
# honesty REPORTED · energy_j null · proven_trust false · whatNot listed
szl-khipu verify runs/export/TRAINING_RECEIPT.json
```

Without `--out` the script rewrites the committed `artifacts/` in place. Those
four archives are the historical 2026-08-29 export; the four Nano Hub repos and
the Space carry the same bytes (their LFS SHA-256 values equal
`artifacts/TRAINING_RECEIPT.json`). Current source does not reproduce those file
digests: TinyKhipu's arrays changed with the curriculum fix in #103, and
ReceiptAgent, moons and MiniEmbed regenerate identical arrays inside a
differently versioned zip container, so their file SHA-256 differs too.

ReceiptAgent keeps the historical 600 training / 200 development examples and
selects weights and stops using **development** agreement. Its `agree` and
`n_held` return values are compatibility aliases for `development_agree` and
`n_development`; they are not independent test results. After selection, the
trainer measures `test_agree` once on 400 additional synthetic examples from a
separate deterministic random stream. Duplicate feature rows within or across
all three splits are rejected before training, independently of labels.
New export receipts include both scores, split counts, and explicit metric roles.
Historical receipts and weights are not rewritten by this source change.

This test measures the same synthetic generator, not unseen source families or
production model quality. Repeated runs on the same seed reuse the same test
examples, so that test must not become a hyperparameter-selection target. The
deterministic `rule_check` remains authoritative, including when the surrogate
disagrees; this evaluation grants no GPU-training or production admission.

## Kernels vs field leaders (honest deltas)

| SZL cut | Field leader | Honest delta |
|---|---|---|
| TileReceipt (`szl-receipt-attn`) | FlashAttention (Dao et al., NeurIPS 2022) | Numeric silhouette of tiled fused attention. SHA receipt of the tiles. **No speedup claim.** Not a rehost of Dao `.cu` / hopper / cute. |
| BlockWitness (`szl-block-kv`) | PagedAttention / vLLM (Kwon et al., SOSP 2023) | Paged-KV gather with a digest of the block table. **No tokens/s.** Not a vLLM rehost. |
| ScoreMod Fiber (`szl-maskmod`) | FlexAttention (PyTorch, arXiv:2412.05496) | Original score_mod + block-mask path that receipts the mask digest. **No CUDA benches.** A swapped mask cannot stay silent. |
| YARQA-ATTN | SageAttention (Zhang et al., ICLR 2025) | **Not quantized attention.** Contiguous canals (Quechua *yarqa*), attend inside the compartment, receipt the partition. GPU cubins **UNAVAILABLE**. CPU numpy path **LIVE**. |
| Governed RMSNorm | RMSNorm (Zhang & Sennrich, 2019) / LayerNorm | Matches a reference and optionally chains a digest of the rounded output. **No speedup.** Digest is integrity, not authorship. |
| Λ-gate | UN HDI 2010 WGM / OECD composite indicators | WGM over [0,1] axes, fail-closed on any zero or non-finite axis, A1–A4 runtime checks. Uniqueness is **Conjecture 1 — OPEN**. Advisory, never proven trust. |
| govsign + provctl | in-toto / SLSA / Sigstore / DSSE | Governance predicate (Λ, energy, decision) as an envelope. `proven_trust` locked **false**. UNSIGNED is a first-class fallback, never a fake signature. SLSA L1 honest, L2 roadmap. |

This repo silhouettes Λ, YARQA, TinyKhipu, ReceiptAgent, and receipts in **numpy**. It does not replace those field leaders and does not inherit their benches.

## Locked-8

Lean locked-proven formulas = **exactly 8**. Lab numerics CHECKED ≠ Lean PROVEN. The F-number mapping onto any larger registry is UNKNOWN — never fabricated.

| ID | Name | Caveat |
|---|---|---|
| F1 | Replay-Hash Determinism | |
| F4 | Khipu DAG acyclicity | edges dst < src |
| F7 | Chaski FIFO | drain(enqueueAll([], msgs)) = msgs |
| F11 | Ayni Reciprocity Conservation | Σ in = Σ out |
| F12 | Kuramoto boundedness | additive fragment ONLY — not full nonlinear sync |
| F18 | RS(10,6) recovery | recoverable iff ≥ 6 of 10 shards |
| F19 | Bekenstein additive scaffolding | monotone fragment ONLY — not S ≤ 2πkRE/ℏc |
| F22 | Khipu emit monotonicity | sequence numbers strictly increase |

## Conjecture 1

> Any two aggregators satisfying A1–A4 agree on every input. **OPEN (sorry).** Unconditional uniqueness under kernel A1–A5 is machine-checked FALSE.

Λ is advisory. Trust ceiling 0.97. `proven_trust` is false in this artifact and every receipt it emits.

Axioms carried at runtime (checks, not a uniqueness proof):

| ID | Name |
|---|---|
| A1 | IsMonotone |
| A2 | IsHomogeneous  Λ(c·x)=c·Λ(x) |
| A3 | IsEgyptianExact  Λ(c,…,c)=c |
| A4 | IsBounded  Λ(x)≤max(x) |
| A5 | IsPermutationInvariant |

## Honesty

| Claim | Label |
|---|---|
| CPU numpy path | LIVE |
| CUDA / GPU cubins | UNAVAILABLE |
| Energy / joules | UNAVAILABLE (never fabricated) |
| Λ uniqueness | Conjecture 1 OPEN |
| proven_trust | false |
| TinyKhipu / ReceiptAgent / moons trained here | REPORTED silhouette, not 1.5B |
| SZL-Khipu-1.5B / ReceiptAgent 1.5B | RESEARCH, **not trained in this tree** |
| Weights at Hub 1–2B | not applicable |

Doctrine **v11 LOCKED** · 749 declarations · 14 axioms · 163 tracked sorries · locked-proven **8**.

## Hub siblings

| Artifact | What |
|---|---|
| [hf/TinyKhipu-Nano](hf/TinyKhipu-Nano/README.md) | NAVIGATE/ABSTAIN silhouette |
| [hf/ReceiptAgent-Nano](hf/ReceiptAgent-Nano/README.md) | 4-way gate; kernel is truth |
| [hf/Moons-Nano](hf/Moons-Nano/README.md) | 2→8→2 two-moons fixture |
| [hf/MiniEmbed-Nano](hf/MiniEmbed-Nano/README.md) | 64 × 12 hash-token table, not a neural embedding |
| [hf/szl-khipu-kernels](hf/szl-khipu-kernels/README.md) | Kernel Hub card; `get_kernel` |
| [space/](space/README.md) | Hub docker hologram — stdlib HTTP, no Gradio |
| [spaces/](spaces/README.md) | Gradio 6 demo (GitHub only; separate Docker publisher uses `space/`) |

## License

Apache-2.0. Copyright 2026 SZL Holdings.

Stephen P. Lutar Jr. / SZL Holdings · ORCID [0009-0001-0110-4173](https://orcid.org/0009-0001-0110-4173)

---

## Work with SZL Holdings

szl-khipu participates in the SZL governed-AI estate. The flagship control plane targets governed agent change management, but production/runtime qualification is tracked separately through the GitHub → Hugging Face → product → proof evidence chain. This repository does not itself prove or authorize a production deployment.

- **Design partners (6-month, paid):** governed-action receipts in your environment → [stephenlutar2@gmail.com](mailto:stephenlutar2@gmail.com)
- **Verify our claims offline:** [github.com/szl-holdings/szl-gov](https://github.com/szl-holdings/szl-gov) — signed estate receipt + public verifier
- **Pricing + SKUs:** not maintained in this repository.

<!-- SZL-CARD-TECHNICAL:v1:END -->

</details>
