Metadata-Version: 2.4
Name: szl-nemo
Version: 0.5.0
Summary: Deterministic doctrine and proof-carrying inference-envelope witness. Not Nemotron, not an LLM, not a CUDA kernel.
License: Apache-2.0
Project-URL: Homepage, https://github.com/szl-holdings/szl-nemo
Project-URL: Source, https://github.com/szl-holdings/szl-nemo
Project-URL: Issues, https://github.com/szl-holdings/szl-nemo/issues
Project-URL: Changelog, https://github.com/szl-holdings/szl-nemo/releases
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

[![PyPI](https://img.shields.io/pypi/v/szl-nemo)](https://pypi.org/project/szl-nemo/) [![Python](https://img.shields.io/pypi/pyversions/szl-nemo)](https://pypi.org/project/szl-nemo/) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/szl-holdings/szl-nemo/badge)](https://scorecard.dev/viewer/?uri=github.com/szl-holdings/szl-nemo) [![CI](https://github.com/szl-holdings/szl-nemo/actions/workflows/cpu-contract.yml/badge.svg)](https://github.com/szl-holdings/szl-nemo/actions/workflows/cpu-contract.yml) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

# szl-nemo — deterministic witness, not Nemotron

Canonical GitHub source: [`szl-holdings/szl-nemo`](https://github.com/szl-holdings/szl-nemo).

`SZL Nemo` is **software**: a deterministic doctrine checker and structured
inference-envelope witness. It is **not** NVIDIA Nemotron, an LLM, a generative
model, an Ollama model, or a Triton/CUDA kernel. SZL has not fine-tuned Nemotron
and does not republish NVIDIA weights.

<!-- 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 -->

## Quickstart

```bash
pip install szl-nemo
szl-nemo --help   # deterministic doctrine checker (R1-R5) + proof-carrying witness
```

Approved package paths:

- `szl_nemo.rule_check` / `szl_nemo.evaluate`: prompt-and-answer doctrine checks
  R1–R5.
- `szl_nemo.envelope_check` / `szl_nemo.evaluate_envelope`: proof-carrying
  inference-envelope checks E1–E10.

`model.joblib` and its historical scorer generator remain quarantined. They are
not an approved runtime or publication path.

## Canonical role inside SZL Forge

Forge owns model lifecycle, evaluation, qualification, and publication. Nemo is
an independent witness around a replaceable inference engine:

```text
Second Brain handles
  -> controller-side tenant authorization + content-digest verification
  -> Nemo PRE_GENERATION witness
  -> proposal-only model
  -> Nemo POST_GENERATION witness
  -> A11oy PRE_TOOL admission + human approval + signed receipt
  -> execution outside the model
  -> Nemo POST_TOOL/postcondition witness
  -> sanitized Living Anatomy observation
```

Nemo may return `ALLOW`, `BLOCK`, or `REVIEW`. `ALLOW` means only that the
checks for the inspected stage passed. It never grants tool authority by itself.
Living Anatomy is an observer, not a decision authority.

## R1–R5 prompt/answer contract

The original deterministic API remains stable:

```json
{
  "schema_version": "szl.nemo.decision.v1",
  "decision": "ALLOW | BLOCK | REVIEW",
  "violated_rules": ["R1_no_fabrication_label"],
  "reasons": ["human-readable reason per violated rule"],
  "rule_version": "doctrine-v11/R1-R5",
  "input_hash": "sha256:<canonical {prompt, answer} JSON>",
  "receipt_status": "UNSIGNED_HONEST"
}
```

For this API, `REVIEW` is the empty-input case: no doctrine signal exists, so the
kernel refuses to silently allow it. Every non-empty pair receives a binary
R1–R5 result.

## E1–E10 proof-carrying envelope

Version `0.4.0` adds a structured, stdlib-only witness over inference metadata and
digests. It does not store raw prompts, hydrated content, private graph state, or
private chain-of-thought.

| Rule | Enforced boundary |
|---|---|
| E1 | Envelope schema and Nemo identity: `SOFTWARE_KERNEL`, non-generative, not Nemotron |
| E2 | Pinned model, adapter, tokenizer, template, runtime, and hardware identity |
| E3 | Principal/tenant authorization plus Second Brain handle/source/content-digest binding |
| E4 | Exact locked-eight formula set, pinned formal/kernel sources, applicability evidence, no invented F-ID-to-callable mapping, Lambda advisory only |
| E5 | Model remains `PROPOSAL_ONLY`; A11oy is the only execution authority |
| E6 | Raw content, private graph data, and private reasoning are forbidden |
| E7 | Tool intent requires A11oy admission, human approval, and a verified signed receipt |
| E8 | PRE/POST generation and PRE/POST tool witness stages are ordered exactly |
| E9 | Executed tool results and postconditions are digest-bound |
| E10 | Persisted claims use only `MEASURED`, `REPORTED`, `MODELED`, `CONJECTURE`, `UNKNOWN`, or `UNAVAILABLE` and carry statement digests |

The formal locked-proven formula set is exactly:

```text
F1, F4, F7, F11, F12, F18, F19, F22
```

The separate `szl-formulas` software kernel exposes 21 callable functions. Nemo
does **not** fabricate a mapping between those callable names and the formal
F-number corpus; the mapping remains `UNKNOWN_NOT_ASSERTED` until a proved
binding artifact exists. F23/Lambda remains `CONJECTURE_1_ADVISORY` and cannot be
an authorization basis.

A valid `PRE_TOOL` envelope with pending human approval returns `REVIEW`. A valid
`POST_TOOL` envelope with a failed bound postcondition also returns `REVIEW`.
Structural, provenance, privacy, or authority drift returns `BLOCK`.

## Receipts

`szl_nemo.receipt` binds decisions into a deterministic hash-chained ledger
(`szl.nemo.receipt.v1`). Every receipt carries `sequence`,
`prev_receipt_sha256`, and its own `receipt_sha256`; genesis is 64 zeroes.
`verify_receipt()` and `verify_chain()` recompute integrity without raising.

These receipts prove content integrity and ordering, not signer identity. This
repository holds no signing key, so receipt status remains honestly unsigned.
A11oy/Evidence Plane signing must occur before a consequential action.

## Usage

```bash
pip install -e .

szl-nemo check \
  --prompt "What's your MMLU?" \
  --answer "UNKNOWN - no benchmarks have been run."
# ALLOW, exit 0

szl-nemo check --prompt "What's your MMLU?" --answer "My MMLU is 73."
# BLOCK, exit 1

szl-nemo envelope-check inference-envelope.json
# ALLOW=0, BLOCK=1, malformed input=2, REVIEW=3

szl-nemo selftest
szl-nemo receipt-verify chain.json
szl-nemo version
```

Library use:

```python
from szl_nemo import evaluate, evaluate_envelope

text_decision = evaluate(prompt, answer)
envelope_decision = evaluate_envelope(envelope)
assert text_decision.input_hash.startswith("sha256:")
assert envelope_decision.input_hash.startswith("sha256:")
```

## Triad binder

`szl_nemo.evaluate_triad` binds four facts the other SZL surfaces already
state separately. It does not merge them into a new theorem.

1. The caller is authorized and the request is a SHA-256 digest. The raw
   request is not stored.
2. An NVIDIA Nemotron reply, or any other model reply, stays
   `PROPOSAL_ONLY`. This package does not load or republish those weights.
3. Energy is a finite non-negative NVML joule value labeled `MEASURED`, or
   `null` labeled `UNAVAILABLE`. A missing meter is not a fabricated number.
4. Λ is the weighted geometric mean of scores in `[0, 1]`. One zero axis
   forces 0. The score is `MODELED`. Unconditional uniqueness under A1–A5
   is Conjecture 1 and is machine-checked false as stated
   (`maxAgg_ne_Lambda` in `szl-holdings/lutar-lean`). Theorem U is
   conditional. The score cannot authorize.
5. The record's DSSE field is `null` and `receipt_status` is
   `UNSIGNED_HONEST`. This repository holds no signing key.

`ALLOW` means the document has that shape. It is not tool authority, not a
proof of computation, and not a DARPA award. Public program names ANSR,
ARCOS, and CLARA are references only.

```bash
szl-nemo triad-check triad.json
```

## Status

| Surface | Label | Evidence and limitations |
|---|---|---|
| R1–R5 doctrine checker, typed decisions, CLI, and receipts | **MEASURED — operational** | CI, labelled vectors, deterministic decision tests, installed-wheel self-test, and receipt-chain verification. Regex ground truth is deliberately conservative and may false-block negated phrasing. |
| Triad binder `szl.nemo.triad.v1` | **MEASURED — local contract tests only** | 19 unit tests on this tree, including malformed-metadata redaction through the API and CLI. No live NVML call, no signature, and no deployment. |
| E1–E10 structured inference-envelope witness | **MEASURED — operational contract** | Adversarial tests cover formula-set drift, invented formula mappings, formula applicability, tenant denial, evidence tampering, mutable revisions, Nemo/Nemotron confusion, private-state leakage, model self-execution, unsigned tool calls, stage order, postconditions, and truth-label drift. This validates envelopes; it does not prove a model is high quality or that a live deployment executed. |
| Historical TF-IDF/logistic-regression triage scorer | **QUARANTINED / not an approved path** | `TRAINING_RECEIPT.json` reports N=5,620 checker-labelled rows and a 12-example paraphrase set. `model.joblib` is absent from the approved package path, so the historical scorer is not loadable or replayable from published bytes. |
| Nemotron or generative-model evaluation | **UNAVAILABLE** | No Nemotron weights or qualified Nemotron benchmark are published here. |
| NVIDIA weights | **NOT REPUBLISHED** | Upstream weights, when independently fetched, remain governed by their upstream license. |

Apache-2.0 applies to SZL-authored files in this repository. Unconditional
Lambda uniqueness under bare A1–A5 remains Conjecture 1 and is
machine-checked false as stated (`maxAgg_ne_Lambda`). Theorem U is
conditional. Never describe Lambda as proven, and never use it as
authorization.

Estate on Hugging Face: models, datasets and Spaces are published under the [SZLHOLDINGS](https://huggingface.co/SZLHOLDINGS) org.
