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