Document open-weight release and public loading API

README.md

@@ -23,23 +23,34 @@ utterances. This release is the first frozen, inference-only artifact for its
 structured-value contextual scorer. It ranks deterministic Rust candidates
 using sentence context, then applies exact maximum-score decoding.
 
+**Premove ITN is released as an open-weight contextual inverse text
+normalization model. The inference code and model weights are licensed under
+MIT.**
+
 The artifact contains the complete trained parameters in `model.safetensors`,
 the exact DeBERTa configuration, and the tokenizer files used by the selected
 production checkpoint. Optimizer state, scheduler state, training counters,
 training data, and evaluation rows are not included.
 
 The artifact is loaded through the `premove-itn` package. It is not a generic
-Transformers model; use the package loader so candidate generation and scoring
-stay aligned with the release implementation:
+Transformers model; use `PremoveITN.from_pretrained()` so candidate generation,
+scoring, and decoding stay aligned with the release implementation:
 
 ```python
-from premove_itn.inference_artifact import load_inference_artifact
+from premove_itn import PremoveITN
 
-artifact = load_inference_artifact(".")
-model = artifact.model
-tokenizer = artifact.tokenizer
+itn = PremoveITN.from_pretrained(
+    "premove-itn/premove-itn",
+    revision="v0.1.0",
+)
+print(itn.normalize("call me at four thirty"))  # call me at 04:30
 ```
 
+Source code, deterministic Rust realization rules, the Python API, benchmark
+code, and retained results are available in the
+[`premove-ai/premove-itn`](https://github.com/premove-ai/premove-itn)
+repository.
+
 The model uses `microsoft/deberta-v3-large` at the exact revision recorded in
 `provenance.json`. The artifact includes the tokenizer and base configuration;
 the base model is not separately redistributed. Microsoft lists the base model
@@ -64,6 +75,15 @@ The supported span kinds are listed in `config.json`: `DIGIT_SEQUENCE`,
 `CARDINAL`, `TIME`, `DATE`, `MONEY`, `DECIMAL`, `PHONE`, `ELECTRONIC`,
 `MEASUREMENT`, `ORDINAL`, `PUNCTUATION`, `WHITELIST`, and `WORD`.
 
+## Runtime
+
+The contextual API requires Python 3.11 or newer, PyTorch, Transformers,
+SentencePiece, safetensors, and huggingface_hub. `device="auto"` selects CUDA,
+then Apple MPS, then CPU. Pass `device="cpu"`, `device="mps"`, or
+`device="cuda"` to select a device explicitly. The retained latency result was
+measured with batch size one on Apple MPS. Other runtimes and devices can have
+different latency and memory use.
+
 ## First Evaluation
 
 The retained First Evaluation used 1,500 frozen VoiceAgent ITN rows and three
@@ -85,7 +105,8 @@ was not blind.
 ## Limitations
 
 - This custom scorer is not directly loadable with `AutoModel.from_pretrained`.
-  Use `load_inference_artifact` and the matching `premove-itn` package version.
+  Use `PremoveITN.from_pretrained()` and the matching `premove-itn` package
+  version.
 - The artifact is English-only and depends on the package's candidate graph and
   decoder for end-to-end normalization.
 - Benchmark results are not a guarantee for unseen domains or formatting
@@ -99,9 +120,12 @@ was not blind.
 - Package version: `0.1.0`
 - Hub repository: `premove-itn/premove-itn`
 - Hub revision: `v0.1.0`
+- Hub commit: `80bda5e2e1fe9542aa628597090242df57c1a157`
+- Base model: `microsoft/deberta-v3-large`
+- Base model revision: `64a8c8eab3e352a784c658aef62be1662607476f`
 - Source checkpoint SHA-256: `9021fa11a028faefb31ef67878170cbe29ed25e68a9a78999f37b120c2ad00d5`
 - Inference artifact SHA-256: `119c0f19767b61446e04da1f8f01a001edf97a47a66965e7146db2483b4937a1`
 
 ## Licensing
 
-Premove ITN is MIT licensed. The pinned base model is `microsoft/deberta-v3-large`, whose model card lists an MIT license. Review and retain both notices when redistributing this artifact.
+Premove ITN is MIT licensed. The pinned base model is [`microsoft/deberta-v3-large`](https://huggingface.co/microsoft/deberta-v3-large), whose model card lists an MIT license. The architecture derives from [DeBERTaV3](https://arxiv.org/abs/2111.09543). Review and retain both notices when redistributing this artifact.