DeterministicML: Examples

Version, license, simplest decide()

-- Act 1 - What you are doing --
  -> DeterministicML is the bit-identical decision layer that sits downstream of any ML model: calibrate logits, apply policy weights, threshold with hysteresis, and seal a SHA-256 receipt. Regulators audit this layer — not the GPU forward pass.

-- Act 2 - Version --
  -> Every support ticket starts with the package version.
  version: 0.1.0
  native: 0.1.0

-- Act 3 - License --
  -> The C engine is machine-locked (Ed25519).
  license_valid: True

-- Act 4 - Simplest call: decide() --
  -> Four-class moderation logits → action + receipt. Same inputs always produce the same receipt bytes on every platform.
  action: allow
  class_id: 0
  score: 0.373269
  receipt: 6c4eab78e5521c68076434c073a5e7a0…

-- Run complete --
  version: 0.1.0
  action: allow
  next_journey: 02_core_path.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/01_first_contact.py
 
# Production one-liner — same API call you ship:
python -c "import deterministicml as d; print(d.__version__, d.license_valid())"

Four-stage decision pipeline

-- Act 1 - Stages --
  -> 1) Temperature + Platt on the top class  2) Weighted sum with escalation + prior  3) Hysteresis thresholds  4) Canonical record + SHA-256.

-- Act 2 - First run --
  -> Capture action and Q40.24 score representation.
  action: allow
  class_id: 0
  score_repr: 6262419
  agg_repr: 5218167
  rule_trace: 0x1

-- Act 3 - Bit-identical re-run --
  -> Same inputs → same receipt, bit for bit.
  receipts_match: True
  scores_match: True
  receipt: 6c4eab78e5521c68076434c073a5e7a0ed4f4730f80761ae7072151717b2e577

-- Act 4 - Ranking path --
  -> Single-logit ranking uses class_id=-1.
  action: allow
  class_id: -1
  score: 0.180711

-- Run complete --
  action: allow
  next_journey: 03_configuration.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/02_core_path.py
 
# Production one-liner — same API call you ship:
python -c "from deterministicml import decide; d=decide([2.1,-0.4,0.7,-1.2], escalation=0.22, prior=0.18); print(d.action_name, d.receipt_hex)"

PipelineConfig + session

-- Act 1 - Defaults --
  -> PipelineConfig mirrors the validated POC constants (temperature, Platt, policy weights, tier thresholds, hysteresis ε).
  temperature: 1.3
  platt_A: -1.7
  threshold_remove: 0.8
  hysteresis_epsilon: 0.02

-- Act 2 - Stricter temperature --
  -> Lower temperature sharpens the softmax; actions can change near borders.
  soft_action: downrank
  soft_score: 0.770624
  sharp_action: downrank
  sharp_score: 0.649862

-- Act 3 - Session IDs --
  -> DeterministicSession auto-increments decision_id.
  decision_ids: [0, 1, 2]

-- Run complete --
  next_journey: 04_diagnostics.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/03_configuration.py
 
# Production one-liner — same API call you ship:
python -c "from deterministicml import DeterministicSession, PipelineConfig; s=DeterministicSession(PipelineConfig(temperature=1.0)); print(s.decide([1.0,0.0]).action_name)"

Receipt verification for auditors

-- Act 1 - Canonical record --
  -> Each decision packs a fixed 32-byte body (id, class, score_repr, agg_repr, rule_trace, action) then SHA-256 seals it.
  record_len: 64
  body_hex: 2a00000000000000328d5a0000000000…
  receipt: e2fe2a2bcabc5035e28123205add65568ba914ddce15da01546ab9c55bccce6a

-- Act 2 - verify_receipt() --
  -> Re-hash the body; must match the sealed receipt.
  verified: True

-- Act 3 - Tamper detection --
  -> Changing score_repr without resealing fails verification.
  tampered_verified: False

-- Run complete --
  verified: True
  next_journey: 05_moderation_stream.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/04_diagnostics.py
 
# Production one-liner — same API call you ship:
python -c "from deterministicml import decide, verify_receipt; d=decide([1.5,0.2,-0.8]); print(verify_receipt(d), d.receipt_hex)"

Batch decisions + auditor log hash

-- Act 1 - Scenario --
  -> A trust-and-safety service scores three posts. Each row is class logits from an upstream model (hate / spam / ok). Escalation and prior signals come from secondary classifiers. DeterministicML turns that into actions + a single log hash an auditor can re-derive.

-- Act 2 - Batch decide --
  -> decide_batch walks every row through the same Q40.24 pipeline and returns per-row Decision objects plus SHA-256 over the concatenated 64-byte records.
  post_0_action: allow
  post_0_class: 0
  post_0_score: 0.134989
  post_0_receipt: 331822eb02ab2a27…
  post_1_action: allow
  post_1_class: 1
  post_1_score: 0.318725
  post_1_receipt: 16f17567e5a137a4…
  post_2_action: downrank
  post_2_class: 1
  post_2_score: 0.822092
  post_2_receipt: aaecdf435f4b0684…

-- Act 3 - Log hash --
  -> One digest covers the whole decision log for the window.
  n: 3
  log_hash: caa36553c2a38008a048cad23d52034ba1560e04dbd6ebe4bafe60fb83836bf8

-- Act 4 - Parity check --
  -> Re-running the identical batch must reproduce the log hash bit-for-bit — the cross-platform claim auditors care about.
  log_hashes_match: True

-- Act 5 - Identical posts --
  -> Two copies of the same logits + signals share score_repr (decision_id differs, so receipts differ — the score path is what must match).
  score_repr_match: True
  action_match: True

-- Run complete --
  log_hash: caa36553c2a38008a048cad23d52034b…
  actions: ['allow', 'allow', 'downrank']
  next_journey: 06_limits.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/05_moderation_stream.py
 
# Production one-liner — same API call you ship:
python -c "from deterministicml import decide_batch; rows=[[2.5,-0.5,0.1],[0.2,1.8,-0.3],[0.1,0.2,0.15]]; ds,h=decide_batch(rows,[0.35,0.55,0.12],[0.2,0.25,0.1]); print([(d.action_name,d.class_id) for d in ds], h.hex()[:32])"

What DeterministicML will not do, and why that is a feature.

-- Act 1 - What this product is --
  -> A bit-identical ML decision layer: fixed-point aggregation of model outputs, hysteresis thresholds, and SHA-256 receipts. Same logits and config → same action and digest on every machine with the same library. • decide / decide_ranking / decide_batch • PipelineConfig with frozen Q40.24 arithmetic • verify_receipt against stored digests

-- Act 2 - What this product is not --
  -> DeterministicML does not make GPU/accelerator neural forward passes bit-identical. Training non-determinism is out of scope. The EU AI Act attaches to decisions and audit logs — that is the shipped surface.

-- Act 3 - Bad arguments --
  -> Empty logits raise ValueError / native ERR_BAD_ARG.
  empty_logits: refused -> ValueError: decide: bad argument

-- Act 4 - Sibling products --
  -> Need general bit-identical reductions? Use solvnum. Need precision reduction? Use mixed_precision. Need consensus fixed-point? Use blockchain_arithmetic.
  good_fit: policy/decision audit, ranking digests, batch parity logs
  wrong_tool: ONNX runtime parity, CUDA kernels, training seeds

-- Run complete --
  scope: decision_layer
  note: Reproducibility is bought with a narrower domain.
  next: (end of suite) - see examples/PROGRESSION.md

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/06_limits.py
 
# Production one-liner — same API call you ship:
python -c "from deterministicml import decide; decide([])"