Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,132 @@
+---
+license: mit
+tags:
+- pharmaceutical-supply-chain
+- traceability
+- anomaly-detection
+- tabular-classification
+- logistic-regression
+pipeline_tag: tabular-classification
+---
+
+# ZigoTrace Pharma — Diversion Anomaly Model
+
+A locked, validated logistic model that scores **grey-market diversion** on a
+pharmaceutical serialization graph — engine: [zigo-pharma](https://github.com/Davedave001/zigo-pharma).
+
+## Intended use — read this first
+
+- **Advisory only.** This model outputs a suspicion score that is fused as **one
+  reliability-capped evidence source** into a larger Dempster-Shafer authenticity
+  confidence, alongside deterministic rule-based gaps. **It never gates a
+  dispense/release decision by itself** — the deterministic layer (recall, expiry,
+  cold-chain, cloned-serial, aggregation, mass-balance) is the authoritative safety
+  path, always.
+- **Scope: diversion only.** Trained to catch route/ring diversion — units that are
+  *individually* unremarkable but statistically anomalous in their custody path or
+  their aggregation-case neighbourhood. It is **not** trained to catch expired,
+  recalled, or cold-chain-excursion stock; those are deterministic gaps, on purpose
+  (rules validate cleanly; this model is the layer for what rules cannot express).
+- **Abstains under uncertainty.** Low model certainty collapses its contribution toward
+  "unknown" rather than guessing — see `uncertainty` in the output.
+- **Not (yet) validated on real data.** Trained and evaluated on the synthetic dataset
+  `zigotrace/pharma-serialized-events`. See Limitations.
+
+## How to use
+
+Input is an **already-extracted 8-feature vector** — this model does not accept or
+parse a raw event graph. Feature extraction is intentionally single-sourced in the TS
+engine (`packages/intelligence/src/features.ts`) to avoid two implementations of graph
+traversal silently drifting apart; see `docs/huggingface-model-plan.md` §0.
+
+```python
+from huggingface_hub import hf_hub_download
+import json, sys
+sys.path.insert(0, ".")  # scorer.py ships alongside model.json in this repo
+from scorer import load_model, score_features
+
+model = load_model(hf_hub_download("zigotrace/pharma-authenticity-model", "model.json"))
+features = [0.83, 1, 1, 1, 1, 1, 4, 0.0]  # route_rarity, num_receives, num_dispenses,
+                                            # distinct_receive_locations, aggregation_consistent,
+                                            # attestation_ok, hop_count, case_dispense_anomaly
+out = score_features(model, features)
+print(out)  # AnomalyOutput(score=..., uncertainty=..., explanation="...")
+```
+
+Or via an Inference Endpoint running `handler.py`:
+
+```json
+POST /  {"inputs": {"features": [0.83, 1, 1, 1, 1, 1, 4, 0.0]}}
+```
+
+## Training
+
+- **Algorithm:** logistic regression, full-batch gradient descent, fixed
+  initialization and iteration count → **deterministic** (same events produce an
+  identical artifact — required for GxP change control; see
+  `packages/intelligence/src/train.ts`).
+- **Labels:** **weak supervision** — labeling functions over model-observable signals
+  (rare custody route, duplicate dispense, weak attestation, case-sibling funnelling),
+  not ground truth. Realistic for a domain where confirmed-counterfeit labels are
+  scarce.
+- **Data:** `zigotrace/pharma-serialized-events` (synthetic, seed 7, 420 train / 180
+  test rows).
+
+## Evaluation (this artifact, `test.jsonl`, standalone at a raw 0.5 threshold)
+
+| Metric | Value |
+|---|---|
+| Diversion detection (route + ring) | 7/7 — **100%** |
+| Brier score | **0.021** |
+| False-positive rate (standalone, 0.5 threshold) | 2.3% (4/173) |
+
+Reproduce: `python hf/local_dry_run.py` (after `node hf/generate_fixtures.mjs`).
+
+> **The false-positive rate above is a property of this model scored in isolation.**
+> In the shipped engine it is capped by a reliability weight inside the
+> Dempster-Shafer fusion and can only ever *add suspicion*, never override a
+> deterministic "authentic" verdict — so it does not translate into a real
+> false-quarantine rate. The shipped engine's actual false-quarantine rate (with this
+> model fused in, evaluated by `intel-validate`) is **0%**. See
+> `validation/model-card.md` in the source repo for the fused-system numbers.
+
+## Model internals (inspectable — this is why logistic-first)
+
+```
+featureNames: route_rarity, num_receives, num_dispenses, distinct_receive_locations,
+              aggregation_consistent, attestation_ok, hop_count, case_dispense_anomaly
+weights:      [1.596, 0.026, 0.567, 0.026, 2.117, -0.567, 0.2, 1.095]
+bias:         -2.329
+```
+
+Weights act on **standardized** features (`(x - mean) / std`, per-feature `mean`/`std`
+shipped in `model.json`). `case_dispense_anomaly` (the relational feature) and
+`route_rarity` carry meaningful weight, consistent with the model's diversion-specific
+training signal.
+
+## Limitations
+
+- Synthetic training/eval data only — real-world generalization is unverified pending
+  a lighthouse distributor dataset (planned, gated dataset repo).
+- Linear model — cannot capture more complex relational patterns (e.g. multi-hop
+  laundering rings); a GNN track exists (`ml/` in the source repo) for that, not yet
+  outperforming this baseline on available data.
+- `aggregation_consistent`'s weight sign should not be over-interpreted causally — it
+  has low variance in the synthetic generator (aggregation mismatches are a separate,
+  rare injected pattern), so its fitted coefficient is not strongly constrained by this
+  dataset.
+
+## Governance
+
+- **Change control:** training is deterministic; any retrain is a new artifact with a
+  new sha256, which is the locked version id (anchored on Hedera in the deployed
+  engine). No silent model updates.
+- **Human authority:** a pharmacist/QP/auditor retains override, with recorded
+  provenance, regardless of this model's output.
+- Full GxP validation pack: `validation/` in the
+  [source repo](https://github.com/Davedave001/zigo-pharma).
+
+## License
+
+MIT (this model + code). The synthetic dataset it's trained on is MIT-licensed
+generated data — see the dataset card for details.