Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,140 @@
+---
+license: apache-2.0
+library_name: interlock
+pipeline_tag: text-classification
+tags:
+- agent-safety
+- tool-use
+- guardrails
+- ai-safety
+language:
+- en
+---
+
+# Interlock
+
+Interlock judges a *proposed agent tool call* against *what the user actually
+asked for*. Content shields read the request and ask whether it is harmful.
+Interlock reads the request/action pair and asks a different question: is this
+call **more** than what was asked?
+
+It is deliberately blind to where a deviation came from. A widened `path`
+argument looks the same whether it originated in a prompt injection, a
+jailbreak, or an ordinary model mistake, and the defence is the same either
+way.
+
+## Output
+
+Three-valued, never binary:
+
+| decision  | meaning |
+|-----------|---------|
+| `allow`   | the call stays within what the request asked for |
+| `confirm` | the call should be put to the user before it runs |
+| `block`   | the call goes materially beyond the request |
+
+The three decisions are `allow`, `confirm`, `block`. Alongside the decision the model
+predicts a deviation type, one of `none`, `scope_expansion`, `unrequested_action`, `irreversible_unconfirmed`, `target_mismatch`, `out_of_scope`, `privilege_escalation`.
+
+`confirm` is a first-class outcome. Collapsing it into `block` would trade a
+question for a refusal on exactly the cases where the request is ambiguous.
+
+## Two tiers
+
+**Tier 1 -- linear (1080 parameters).** A two-headed multinomial
+logistic regression over 107 structured request/action alignment
+features. Pure NumPy at inference: no tokeniser, no torch. This is the tier
+that runs on every agent turn. Shipped as `interlock_linear.npz`, with the
+fitted operating point in `policy.json`.
+
+**Tier 2 -- encoder (optional).** ModernBERT-base with a decision head and a
+deviation head, reading a role-annotated text rendering of the same pair. More
+accurate where the wording rather than the structure carries the signal, and
+correspondingly slower. Shipped as `interlock.onnx` when it has been trained
+and exported; the export is verified against the torch model to within 1e-3 on
+the raw logits before it is published.
+
+A third file, `interlock-linear.gguf`, is a weight container for tier 1 with
+its feature names and operating point attached. It is not a runtime: llama.cpp
+has no architecture for this classification head and cannot serve it. The
+verified runtimes are NumPy for tier 1 and ONNX Runtime for tier 2.
+
+## Evaluation, and the split that makes it mean something
+
+The train/test split is taken at **tool family** granularity, not at row
+granularity. Training and validation draw on `fs, shell, mail, calendar, issues`.
+The held-out split draws on `browser, crm, storage, db` -- every tool schema
+in it is one the model has never seen. The split is verified against the files
+on disk, not just asserted in code.
+
+Measured for tier 1:
+
+| split | over-blocking | deviation detection |
+|-------|---------------|---------------------|
+| validation (seen families, unseen world) | 2.9% | 88.0% |
+| held-out families (unseen tool schemas)  | 1.8% | 79.3% |
+
+Over-blocking is the fraction of *legitimate* calls that were interrupted, and
+it is the headline number. A shield that interrupts real work gets switched
+off, and a switched-off shield detects nothing. Detection is reported second
+for that reason, not first.
+
+Latency, timing a full check per call including encoding: 0.247 ms mean, 0.663 ms p95 over 400 single-threaded calls on arm64.
+Timing the model's arithmetic alone would understate what a deployment pays.
+
+## Intended use
+
+Interlock sits between an agent's proposed tool call and its execution. Given
+the user's request, the proposed call and the tool's schema, it returns a
+verdict that a harness can act on: proceed, ask the user, or refuse. It is
+designed for agent runtimes where tool schemas are declared and where a
+confirmation prompt is a cheaper failure than an unwanted side effect.
+
+```python
+from interlock.model import load_shield
+
+shield = load_shield("artifacts")
+verdict = shield.check("archive the Q3 notes", {"tool": "fs.delete_file", "arguments": {"path": "notes/"}})
+print(verdict.decision, verdict.deviation)
+```
+
+It is not a content moderation model, not a prompt-injection detector, and not
+a substitute for sandboxing or for asking the user.
+
+## Limitations
+
+- **Synthetic data.** Every episode, tool schema and deviation in training is
+  generated. The tool families model common operation shapes rather than any
+  particular product's API, and no real service was contacted at any point.
+  Performance on production agent traffic is unmeasured here.
+- **English only.** Requests and tool descriptions are English. Nothing has
+  been measured in any other language.
+- **One layer among several.** Interlock reads the correspondence between a
+  request and a call. It does not read the content of a payload for harm, does
+  not sandbox anything, and cannot see effects that occur outside the tool
+  call it is shown.
+- **It does not guarantee safety.** An `allow` verdict means this shield found
+  no boundary deviation, which is a weaker statement than "this call is safe".
+  Deploy it beside content shields, sandboxing and human confirmation, not
+  instead of them.
+- **Unseen tools cost accuracy.** Detection falls from 88.0% to
+  79.3% on held-out tool families. The over-blocking rate holds, so
+  the degradation shows up as missed deviations rather than as new
+  interruptions, but it is real.
+- **The operating point is a choice.** Thresholds were fitted against an
+  explicit over-blocking budget on validation data. A deployment with a
+  different tolerance for interruption should refit them rather than inherit
+  these.
+
+## Files
+
+| file | what it is |
+|------|------------|
+| `interlock_linear.npz` | tier-1 weights, the default serving path |
+| `policy.json` | fitted decision thresholds |
+| `train_report_linear.json` | measured metrics for tier 1 |
+| `interlock.onnx` | tier-2 graph, when the encoder has been trained |
+| `interlock-linear.gguf` | tier-1 weight container, not a runtime |
+| `latency.json` | measured per-call latency and peak RSS |
+
+Card generated 2026-08-30T01:25:20+00:00 for `NagaYu/interlock`.