Upload README.md with huggingface_hub

README.md

@@ -36,9 +36,11 @@ language:
   - tr
 ---
 
-# flowxai/topic-scope
+# topic_scope[border]
 
-The `topic_scope` detector for [flowx-border](https://github.com/flowx-ai/border), an embeddable library that inspects the text going into and coming out of an LLM and returns a structured decision plus an audit-grade evidence record.
+The `topic_scope` detector for [border](https://github.com/flowx-ai/border), an embeddable library that inspects the text going into and coming out of an LLM and returns a structured decision plus an audit-grade evidence record.
+
+`flowxai/topic-scope` on the hub. It is one detector of 28, and it is not a general purpose topic_scope classifier: it was trained for this library's policy, is read at the operating point below, and reports through the evidence record rather than returning a bare score.
 
 This card is generated from the evaluation and export artifacts of the training run, so every number on it is reproducible from this repository rather than asserted.
 
@@ -54,6 +56,55 @@ This card is generated from the evaluation and export artifacts of the training
 
 This head is read with argmax and has no threshold.
 
+## How to use it
+
+Through the library, which is what this model is for. It loads the artifact below, applies the operating point above, and returns a decision with an evidence record rather than a bare score.
+
+```sh
+pip install flowx-border
+```
+
+```yaml
+# policy.yaml
+policy_id: default
+version: 1
+
+detectors:
+  topic_scope:
+    enabled: true
+    on_fail: flag
+```
+
+```python
+from flowx_border import load_policy, scan_input
+
+policy = load_policy("policy.yaml")
+
+decision = scan_input(user_text, policy)
+
+print(decision.verdict)      # allow | flag | redact | block
+print([f.label for f in decision.findings if f.detector_id == "topic_scope"])
+print(decision.evidence.record_id)
+```
+
+This detector reads the input side, so `scan_input` is where it fires. It is T3, so it runs only when a lower tier flags, or when the policy sets `always: true`. Its budget is 300 ms at 87 tokens on one CPU thread.
+
+The weights are fetched once and cached, and a scan needs no network after that. Nothing here calls out to a hosted model, and the evidence record carries hashes rather than your text.
+
+### Without the library
+
+The artifact is plain ONNX, so it will load in `onnxruntime` directly. Two things you then own yourself, and they are the reason the library exists: the operating point above is not in the graph, and neither is the chunking. Inputs longer than the trained window have to be split and recombined, or the scores past it are extrapolation.
+
+```python
+import onnxruntime as ort
+from huggingface_hub import hf_hub_download
+from tokenizers import Tokenizer
+
+repo = "flowxai/topic-scope"
+session = ort.InferenceSession(hf_hub_download(repo, "onnx/model.int8.onnx"))
+tokenizer = Tokenizer.from_file(hf_hub_download(repo, "tokenizer.json"))
+```
+
 ## Per language
 
 Per language rather than an aggregate, because an aggregate across 26 languages hides the tail and the tail is the point.