docs: improve Premove ITN discovery metadata (#95)

Author: aryamantodkar

README.md

@@ -10,6 +10,10 @@
 Open-source, context-aware inverse text normalization for conversational
 voice-agent transcripts, with open weights.
 
+Premove ITN converts spoken ASR output into canonical written forms for phone
+numbers, email addresses, identifiers, dates, times, money, measurements, and
+alphanumeric codes.
+
 ## The ambiguity
 
 | System | Output |
@@ -28,7 +32,7 @@ These are the retained outputs for row `va6_collision_0013` in the
 
 ## Results
 
-On our frozen benchmark, Premove reaches **99.50% semantic accuracy on the
+On our frozen benchmark, Premove ITN reaches **99.50% semantic accuracy on the
 voice-agent subset**, compared with 68.25% for `text-processing-rs` and 67.00%
 for NVIDIA Thutmose.
 
@@ -99,13 +103,14 @@ That sent me looking for context-aware ITN. I tried [NVIDIA Thutmose](https://ca
 but on the structured values I cared about for tool calls, I still found
 surprisingly simple failures.
 
-Premove came from a different idea: do not ask the model to perform the entire
-normalization. Generate the valid written forms first, then train the model
-only to decide which one fits the context. An exact decoder handles the rest.
+Premove ITN came from a different idea: do not ask the model to perform the
+entire normalization. Generate the valid written forms first, then train the
+model only to decide which one fits the context. An exact decoder handles the
+rest.
 
 ## How Premove ITN works
 
-Premove splits normalization into three steps: **generate, score, decode**.
+Premove ITN splits normalization into three steps: **generate, score, decode**.
 
 Simplified example:
 
@@ -135,7 +140,7 @@ contextual source span + candidate kind labels + proposed replacement
                          ▼
 3. DECODE
 
-Candidates can overlap, so Premove uses exact dynamic programming
+Candidates can overlap, so Premove ITN uses exact dynamic programming
 to find the highest-scoring compatible path through the transcript.
                          │
                          ▼
@@ -148,7 +153,7 @@ context**. The decoder decides **which edits can coexist**.
 
 ## Supported forms
 
-Premove covers English structured values commonly needed by voice agents:
+Premove ITN covers English structured values commonly needed by voice agents:
 
 | Form | Example |
 | --- | --- |
@@ -168,7 +173,7 @@ Premove covers English structured values commonly needed by voice agents:
 
 ### Not supported
 
-Premove currently targets English structured text. It does not provide
+Premove ITN currently targets English structured text. It does not provide
 first-class normalization for non-English speech, street addresses, free-form
 rewriting, or arbitrary application-specific formats.
 
@@ -236,7 +241,7 @@ frozen evaluation was excluded from training and checkpoint selection; see the
 
 The contextual scorer uses
 [`microsoft/deberta-v3-large`](https://huggingface.co/microsoft/deberta-v3-large)
-at a pinned revision as its encoder backbone. Premove adds a custom candidate
+at a pinned revision as its encoder backbone. Premove ITN adds a custom candidate
 scorer and exact decoder around the
 [DeBERTaV3 architecture](https://arxiv.org/abs/2111.09543).
 
@@ -245,7 +250,7 @@ scorer and exact decoder around the
 Premove ITN source code and model weights are MIT licensed. The contextual
 scorer uses [`microsoft/deberta-v3-large`](https://huggingface.co/microsoft/deberta-v3-large)
 at a pinned revision as its encoder backbone. Candidate scoring and exact
-decoding are Premove-specific.
+decoding are Premove ITN-specific.
 
 The Rust realization layer uses
 [`text-processing-rs`](https://github.com/FluidInference/text-processing-rs),

benchmarks/README.md

@@ -35,7 +35,7 @@ RAYON_NUM_THREADS=8 TOKENIZERS_PARALLELISM=false \
   --thutmose-artifact /path/to/itn_en_thutmose_bert.nemo
 ```
 
-Replace placeholder paths before running. The selected Premove checkpoint must
+Replace placeholder paths before running. The selected Premove ITN checkpoint must
 be available at the path in `data/models/production.json`. Model weights and
 caches are not committed. The runner refuses a Rust extension whose profile is
 not `release`, or which has debug assertions enabled. It records native build

benchmarks/export_inference_artifact.py

@@ -149,7 +149,7 @@ def write_readme(root: Path, provenance: dict[str, Any]) -> None:
 | Thutmose | 59.39% | 57.61% | 268/400 (67.00%) | 15.98 ms |
 | text-processing-rs | 55.79% | 55.05% | 273/400 (68.25%) | 0.14 ms |
 
-Premove leads the measured semantic accuracy overall and on the 400
+Premove ITN leads the measured semantic accuracy overall and on the 400
 voice-agent-domain rows. It does not lead latency. This is a balanced synthetic
 stress benchmark, not an estimate of production traffic accuracy, and the run
 was not blind.

benchmarks/run_comparison.py

@@ -184,7 +184,7 @@ def row_kind(row: dict[str, Any]) -> str:
 
 
 def semantic_kind(row: dict[str, Any], span: dict[str, Any]) -> str | None:
-    # The dataset deliberately leaves PERCENT unmapped because Premove has no
+    # The dataset deliberately leaves PERCENT unmapped because Premove ITN has no
     # public PERCENT SpanKind.  Structured and electronic values are scored by
     # their canonical form (case-insensitive for identifiers).
     value = span.get("premove_span_kind")

benchmarks/summarize_comparison.py

@@ -53,7 +53,7 @@ def summarize(output: Path) -> None:
     lines = [
         "# First Evaluation",
         "",
-        "Premove leads semantic entity accuracy overall and in the voice-agent group. It remains slower than both comparison backends. This is the repository's retained release-artifact result.",
+        "Premove ITN leads semantic entity accuracy overall and in the voice-agent group. It remains slower than both comparison backends. This is the repository's retained release-artifact result.",
         "",
         "## Overall results",
         "",
@@ -86,7 +86,7 @@ def summarize(output: Path) -> None:
         )
     lines += [
         "",
-        "| Domain | Premove | Thutmose | text-processing-rs |",
+        "| Domain | Premove ITN | Thutmose | text-processing-rs |",
         "|---|---:|---:|---:|",
     ]
     for domain in sorted(
@@ -132,7 +132,7 @@ def summarize(output: Path) -> None:
         "",
         "Each count below scores only the named entity, including entities in multi-entity sentences.",
         "",
-        "| Category | Premove | Thutmose | text-processing-rs |",
+        "| Category | Premove ITN | Thutmose | text-processing-rs |",
         "|---|---:|---:|---:|",
     ]
     for category in sorted(categories[names[0]]):
@@ -157,7 +157,7 @@ def summarize(output: Path) -> None:
         "Warm-up records are saved separately for each backend. Thutmose also retains its startup warm-up in runtime metadata. Initialization timing is process/model initialization, not machine cold boot or first download.",
         "",
         "",
-        "## Premove timing components",
+        "## Premove ITN timing components",
         "",
         "| Component | Mean ms | p95 ms | p99 ms |",
         "|---|---:|---:|---:|",

docs/architecture.md

@@ -1,6 +1,6 @@
 # Architecture
 
-Premove separates three jobs that are often combined in inverse text
+Premove ITN separates three jobs that are often combined in inverse text
 normalization:
 
 1. Rust generates valid written forms.
@@ -37,7 +37,7 @@ span as a possible normalization region.
 Repeated span text is deduplicated, then all unique spans are sent to Rust in
 one batched call. Rust evaluates the 13 supported realizer kinds and returns
 every valid written form for each span. If multiple kinds produce the same
-replacement for the same source span, Premove stores one candidate with
+replacement for the same source span, Premove ITN stores one candidate with
 multiple kind labels.
 
 Each candidate contains:
@@ -78,7 +78,7 @@ flattening candidate metadata in stable input order.
 ## Score candidates with sentence context
 
 The complete transcript is encoded by DeBERTa once. For each candidate,
-Premove builds three feature groups:
+Premove ITN builds three feature groups:
 
 ```text
 source context
@@ -113,7 +113,7 @@ example, `seven eighty eight` can produce the same-kind alternatives `95` and
 
 Candidate scores are not applied independently. Two high-scoring replacements
 can overlap, and selecting one changes which other edits remain possible.
-Premove therefore solves the complete sentence as a character-interval graph.
+Premove ITN therefore solves the complete sentence as a character-interval graph.
 
 Candidates are weighted edges over source character intervals. Leaving a
 character unchanged is a zero-score `KEEP` edge. The decoder uses dynamic

docs/evaluations/voice-agent-itn-spec.md

@@ -25,16 +25,16 @@ collision groups intentionally use controlled sentence shells.
 ## Backend-neutral contract
 
 The backend-neutral semantic category and `premove_span_kind` are different
-fields. Every non-null Premove kind must be a current public `SpanKind` member.
-Each semantic category maps to at most one Premove kind. URL maps to
+fields. Every non-null Premove ITN kind must be a current public `SpanKind` member.
+Each semantic category maps to at most one Premove ITN kind. URL maps to
 `ELECTRONIC`. PERCENT remains a required benchmark category and has a null
-Premove mapping because Premove has no public PERCENT kind. This dataset does
-not add or change a Premove realization rule.
+Premove ITN mapping because Premove ITN has no public PERCENT kind. This dataset
+does not add or change a Premove ITN realization rule.
 
 The headline inference adapter receives only `text`. It must not receive gold
-spans, categories, Premove kinds, domains, difficulty, or semantic values. An
+spans, categories, Premove ITN kinds, domains, difficulty, or semantic values. An
 oracle span-kind realizer result can be reported only as a separate diagnostic.
-Premove versus text-processing-rs is an upstream ablation comparison, not a
+Premove ITN versus text-processing-rs is an upstream ablation comparison, not a
 comparison of fully independent systems.
 
 ## Semantic equivalence

docs/getting-started.md

@@ -108,7 +108,7 @@ the complete support boundary.
 
 ## More examples
 
-| Transcript | Premove output |
+| Transcript | Premove ITN output |
 | --- | --- |
 | `can you look up order d l t two nine eight two` | `can you look up order DLT2982` |
 | `I need to change flight m d o three five one` | `I need to change flight MDO351` |
@@ -118,4 +118,3 @@ the complete support boundary.
 
 The last two rows use the same spoken value. Sentence context selects a time or
 a dollar amount without exposing categories or gold metadata to the model.
-

docs/model-card.md

@@ -19,7 +19,8 @@ license: mit
 # Premove ITN v0.1.0
 
 Premove ITN is an open-weight contextual inverse text normalization system for
-English voice-agent transcripts. It turns spoken-form ASR text into structured
+English voice-agent transcripts. It is the contextual scoring model used by the
+`premove-itn` Python package. It turns spoken-form ASR text into structured
 written text:
 
 ```text
@@ -104,13 +105,13 @@ match separately measures the complete canonical output.
 | Thutmose | 59.39% | 22.13% | 15.98 ms |
 | text-processing-rs | 55.79% | 16.53% | 0.14 ms |
 
-Premove led measured semantic accuracy overall and on the 400 dedicated
+Premove ITN led measured semantic accuracy overall and on the 400 dedicated
 voice-agent rows. It did not lead latency.
 
 Latency used sequential batch-one requests on an Apple M4 MacBook Air with
 MPS, an optimized Rust extension, and eight Rayon workers. Models were loaded
 and warmed before request latency was measured. Download and initialization
-are excluded. The Premove timing used the release Rust extension. The backend
+are excluded. The Premove ITN timing used the release Rust extension. The backend
 evaluation was blind: each backend received only transcript text.
 Independent human gold adjudication is a separate task and remains pending.
 
@@ -121,7 +122,7 @@ and
 
 ## Intended use
 
-Use Premove for English voice-agent transcripts in which numbers, dates,
+Use Premove ITN for English voice-agent transcripts in which numbers, dates,
 times, money, phone values, identifiers, URLs, and related structured values
 need sentence-level disambiguation. The runtime receives only transcript text.
 Candidate metadata is generated internally.

docs/platform-evidence/README.md

@@ -6,7 +6,7 @@ This directory records the v0.1.0 compatibility certification.
   Python 3.11, 3.12, and 3.13. Linux release wheels use the
   `manylinux_2_28` platform contract.
 - MPS and CPU each produced **1,500/1,500 exact output matches** against the
-  retained First Evaluation Premove predictions.
+  retained First Evaluation Premove ITN predictions.
 - `device="auto"` selected MPS on Apple Silicon and CPU on Linux.
 - Explicit unavailable-device checks passed for CUDA on macOS and MPS on the
   CPU-only Linux runner.