Polish model card navigation and evaluation presentation

README.md

@@ -27,35 +27,122 @@ inference: false
 24 kHz English TTS with the neural waveform decoder already inside the model.</p>
 
 <p align="center">
-  <a href="https://huggingface.co/spaces/owensong/Inflect-v2"><img alt="Live demo" src="https://img.shields.io/badge/Live_demo-1769E0?style=for-the-badge&logo=huggingface&logoColor=white"></a>
-  <a href="https://huggingface.co/owensong/Inflect-Nano-v2"><img alt="Inflect-Nano-v2" src="https://img.shields.io/badge/Inflect--Nano--v2-FFFFFF?style=for-the-badge&logo=huggingface&logoColor=1769E0"></a>
-  <a href="https://github.com/owenawsong/Inflect"><img alt="GitHub" src="https://img.shields.io/badge/GitHub-10253F?style=for-the-badge&logo=github&logoColor=white"></a>
-</p>
-
-<p align="center">
-  <a href="#run-locally">Run locally</a> ·
-  <a href="#evaluation">Evaluation</a> ·
-  <a href="docs/API.md">API</a> ·
-  <a href="docs/DEPLOYMENT.md">Deployment</a> ·
-  <a href="docs/EVALUATION.md">Raw protocol</a> ·
-  <a href="https://huggingface.co/collections/owensong/inflect-v2-6a619e820808eccf361a2948">Inflect v2 collection</a>
+  <a href="https://github.com/owenawsong/Inflect"><img alt="GitHub" height="40" src="assets/nav/github.svg"></a>
+  <a href="https://huggingface.co/owensong/Inflect-Micro-v2"><img alt="Inflect Micro v2" height="40" src="assets/nav/micro.svg"></a>
+  <a href="https://huggingface.co/owensong/Inflect-Nano-v2"><img alt="Inflect Nano v2" height="40" src="assets/nav/nano.svg"></a>
+  <a href="https://huggingface.co/spaces/owensong/Inflect-v2"><img alt="Live playground" height="40" src="assets/nav/playground.svg"></a>
+  <a href="https://huggingface.co/collections/owensong/inflect-v2-6a619e820808eccf361a2948"><img alt="Inflect v2 collection" height="40" src="assets/nav/collection.svg"></a>
 </p>
 
 <p align="center"><strong>9.36M complete parameters</strong> · <strong>37.53 MB FP32 weights</strong> · <strong>one fixed English voice</strong> · <strong>no external vocoder</strong></p>
 
 ---
 
+> **Complete means complete.** The published parameter count includes text encoding, duration prediction, latent synthesis, and the integrated 24 kHz waveform decoder. Inflect does not hide a second vocoder, server model, or inference-time teacher.
+
+<details>
+<summary><strong>Explore this model card</strong></summary>
+
+| Start here | Technical detail |
+| --- | --- |
+| [Listen](#listen) | [Architecture](#architecture-and-parameter-budget) |
+| [Evaluation](#evaluation) | [Controls and long text](#controls-determinism-and-long-text) |
+| [Choose Micro or Nano](#choose-the-right-inflect) | [Data and adaptation](#data-voice-and-adaptation-status) |
+| [Run locally](#run-locally) | [Package map](#package-map) |
+| [Limitations](#limitations) | [Evaluation protocol](docs/EVALUATION.md) |
+
+</details>
+
 ## Listen
 
 These are held-out text generations, not reconstructions of training audio. Each transcript is shown exactly as passed to the public frontend.
 
 | Test | Exact transcript | Generated audio |
 | --- | --- | --- |
-| **Conversational** | It wasn't until later that I realized what had actually happened. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/conversational.wav"></audio><br><a href="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/conversational.wav">download WAV</a> |
-| **Punctuation** | First, close the window; second, turn off the lamp; finally, lock the door. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/punctuation.wav"></audio><br><a href="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/punctuation.wav">download WAV</a> |
-| **Numbers** | The package weighs twelve point six kilograms and arrived on July twenty-first. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/numbers.wav"></audio><br><a href="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/numbers.wav">download WAV</a> |
-| **Names and places** | Gwendolyn photographed the eucalyptus trees outside Ljubljana. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/names_places.wav"></audio><br><a href="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/names_places.wav">download WAV</a> |
-| **Technical** | The system runs on three core components that all have to stay in sync. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/technical.wav"></audio><br><a href="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/technical.wav">download WAV</a> |
+| **Conversational** | It wasn't until later that I realized what had actually happened. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/conversational.wav"></audio> |
+| **Punctuation** | First, close the window; second, turn off the lamp; finally, lock the door. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/punctuation.wav"></audio> |
+| **Numbers** | The package weighs twelve point six kilograms and arrived on July twenty-first. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/numbers.wav"></audio> |
+| **Names and places** | Gwendolyn photographed the eucalyptus trees outside Ljubljana. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/names_places.wav"></audio> |
+| **Technical** | The system runs on three core components that all have to stay in sync. | <audio controls preload="metadata" src="https://huggingface.co/owensong/Inflect-Micro-v2/resolve/main/samples/male/technical.wav"></audio> |
+
+## Evaluation
+
+No single metric captures TTS quality. Inflect v2 reports **human preference**, **predicted naturalness**, **multi-ASR intelligibility**, **complete footprint**, and **runtime** separately rather than compressing them into one unverifiable score.
+
+| Community preference ↑ | UTMOS22 ↑ | Two-ASR semantic WER ↓ | Complete FP32 weights ↓ |
+| ---: | ---: | ---: | ---: |
+| **66.2%** | **4.395** | **3.99%** | **37.53 MB** |
+
+The headline row always refers to **Inflect-Micro-v2**. Detailed competitor results and protocol boundaries are kept visible below.
+
+### 1. Human blind preference
+
+![Community blind listening](assets/evidence/human-preference.svg)
+
+Inflect-Micro-v2 recorded a **66.2% preference rate** (21 wins · 10 losses · 3 ties) in the final anonymous community study. Systems were hidden, left/right order was randomized, and ties count as half a win. This is descriptive community evidence, not formal MOS.
+
+### 2. Predicted naturalness versus footprint
+
+![Predicted quality versus footprint](assets/evidence/quality-vs-footprint.svg)
+
+The UTMOS22 run used 500 identical unseen prompts per voice. KittenTTS and Piper are equal-weight two-voice means; their observed voice ranges appear as whiskers. Supertonic 3-step is reported below the plotted range rather than flattening every other system.
+
+**Inflect-Micro-v2: 4.395 UTMOS22**, 95% bootstrap CI **4.381–4.408**. UTMOS22 is a learned predictor, not human MOS.
+
+### 3. Intelligibility on unseen text
+
+![Two-ASR semantic WER consensus](assets/evidence/asr-consensus.svg)
+
+The headline score is the equal-weight mean of Qwen3-ASR and Nemotron 3.5 corpus WER for **every** system. Whisper is excluded consistently from the headline because it produced insertion-heavy hallucinations on a subset of otherwise intelligible Supertonic 8-step clips. It is not deleted: the complete three-ASR evidence remains below.
+
+<details>
+<summary><strong>Open the complete three-ASR audit</strong></summary>
+
+![Semantic WER across Qwen3-ASR, Nemotron 3.5, and Whisper large-v3](assets/evidence/modern400-three-asr.svg)
+
+| System / voice | Qwen3-ASR ↓ | Nemotron 3.5 ↓ | Whisper large-v3 ↓ |
+| --- | ---: | ---: | ---: |
+| **Inflect-Micro-v2** | **2.52%** | **5.45%** | **2.73%** |
+| **Inflect-Nano-v2** | **2.79%** | **5.63%** | **2.65%** |
+| KittenTTS Nano · Bruno | 2.15% | 3.96% | 2.17% |
+| KittenTTS Nano · Hugo | 2.39% | 3.80% | 2.11% |
+| Piper Low · Danny | 2.62% | 5.60% | 2.55% |
+| Piper Low · Ryan | 2.81% | 5.51% | 2.87% |
+| Supertonic 3 · M2 · 3-step | 3.03% | 6.04% | 3.22% |
+| Supertonic 3 · M2 · 8-step | 2.05% | 3.56% | 8.08% |
+
+For Inflect-Micro-v2, the individual results are **2.52% Qwen3-ASR**, **5.45% Nemotron 3.5**, and **2.73% Whisper large-v3**. The former three-model mean, **3.57%**, is retained only as a descriptive audit value and is not used as the headline score.
+
+</details>
+
+### 4. Complete weight footprint
+
+![Complete deployable model footprint](assets/evidence/model-footprint.svg)
+
+Voice variants sharing the same weights are merged. Inflect totals include the integrated waveform decoder.
+
+<details>
+<summary><strong>Open the frozen protocol and host-specific runtime snapshot</strong></summary>
+
+- Modern400 uses 400 identical unseen English prompts per system: 200 fixed modern/stress prompts plus 200 deterministic FLEURS `en_us` test prompts.
+- Exact-text exclusion was checked against 87,362 training transcripts.
+- All ASR inputs are resampled to 16 kHz and scored with the same disclosed English normalizer.
+- UTMOS22 uses `tarepan/SpeechMOS` v1.2.0 on a separate 500-prompt generation set.
+- Headline intervals use 10,000 bootstrap samples.
+- The Modern400 corpus SHA-256 is `b7504ce2dce44a2da82770a6a5dfd2a034fe17e2113980f8a69663ade417a34c`.
+- Prompts, hypotheses, compressed row-level reports, and summaries ship under `evaluation/final/`.
+
+The retained CPU snapshot used one isolated process on an AMD EPYC 7K62, 50 prompts, three warmups, and runtime-default CPU threading:
+
+| RTF ↓ | Audio generated / wall time ↑ | Median utterance | p95 utterance | Cold load |
+| ---: | ---: | ---: | ---: | ---: |
+| 0.743 | 1.35× real time | 3.205 s | 4.681 s | 1.35 s |
+
+RTF is wall time divided by generated audio duration. This is a host-specific engineering snapshot, not a portable cross-system speed claim. A matched local CPU rerun is tracked before the public release.
+
+</details>
+
+---
 
 ## Choose the right Inflect
 
@@ -64,13 +151,10 @@ These are held-out text generations, not reconstructions of training audio. Each
 | Complete parameters | 3,966,721 | 9,356,513 |
 | FP32 weights | 15.97 MB | 37.53 MB |
 | Positioning | Smallest practical footprint | Strongest Inflect v2 quality |
-| Warm CPU throughput¹ | 1.85× real time | 1.35× real time |
-| Waveform decoder | Included | Included |
-| Public API and frontend | Same | Same |
+| 24 kHz waveform decoder | Included | Included |
+| Python API and frontend | Same | Same |
 
-**Inflect-Micro-v2** is the quality-focused member of the family. Both parameter totals count the complete generator, including the 24 kHz neural waveform decoder. There is no hidden inference-time teacher, language model, or second vocoder download.
-
-<sub>¹ Host-specific engineering snapshot on an AMD EPYC 7K62. See [Runtime methodology](#runtime-methodology) before comparing hardware.</sub>
+**Inflect-Micro-v2** is the quality-focused member of the family. Both models use the same public API and complete text-to-waveform packaging.
 
 ## Run locally
 
@@ -120,82 +204,12 @@ The result is a 24 kHz mono `float32` waveform. Long input is split at punctuati
 | --- | --- |
 | 37.53 MB of FP32 model weights, with no server dependency. | Text frontend, acoustic generator, duration model, and waveform decoder ship together. |
 | **Built for local inference** | **Measured, not hand-picked** |
-| CPU-ready PyTorch runtime, deterministic seeds, and punctuation-aware long text. | Frozen prompts, raw hypotheses, confidence intervals, hashes, and per-system reports are included. |
-
-## Evaluation
-
-No single metric captures TTS quality. Inflect v2 reports **human preference**, **predicted naturalness**, **three-ASR intelligibility**, **footprint**, and **runtime** separately rather than hiding them inside one composite score.
-
-### 1. Human blind preference
-
-![Community blind listening](assets/evidence/human-preference.svg)
-
-Inflect-Micro-v2 recorded a **66.2% preference rate** (21 wins · 10 losses · 3 ties) in the final anonymous community study. Systems were hidden, left/right order was randomized, and ties count as half a win. This is descriptive community evidence, not formal MOS.
-
-### 2. Predicted naturalness versus footprint
-
-![Predicted quality versus footprint](assets/evidence/quality-vs-footprint.svg)
-
-The 500-prompt UTMOS22 quality run used the same unseen text per system. KittenTTS and Piper are summarized as equal-weight two-voice means in the figure, with the observed voice range visible. Supertonic 3-step is annotated below the plotted quality range rather than compressing the useful portion of the chart.
-
-| System / voice | Weights | UTMOS22 ↑ |
-| --- | ---: | ---: |
-| **Inflect-Micro-v2** | 37.5 MB | **4.395** |
-| **Inflect-Nano-v2** | 16.0 MB | **4.386** |
-| KittenTTS Nano · Bruno | 56.8 MB | 4.217 |
-| KittenTTS Nano · Hugo | 56.8 MB | 4.191 |
-| Piper Low · Ryan | 63.1 MB | 4.289 |
-| Piper Low · Danny | 63.1 MB | 4.195 |
-| Supertonic 3 · James · 8-step | 398.1 MB | 4.295 |
-| Supertonic 3 · James · 3-step | 398.1 MB | 2.471 |
-
-Inflect-Micro-v2: **4.395 UTMOS22**, 95% bootstrap CI **4.381–4.408**. UTMOS22 is a learned predictor, not human MOS.
-
-### 3. Intelligibility across three ASR systems
-
-![Semantic WER across Qwen3-ASR, Nemotron 3.5, and Whisper large-v3](assets/evidence/modern400-three-asr.svg)
-
-| System / voice | Qwen3-ASR ↓ | Nemotron 3.5 ↓ | Whisper large-v3 ↓ | Descriptive mean ↓ |
-| --- | ---: | ---: | ---: | ---: |
-| **Inflect-Micro-v2** | **2.52%** | **5.45%** | **2.73%** | **3.57%** |
-| **Inflect-Nano-v2** | **2.79%** | **5.63%** | **2.65%** | **3.69%** |
-| KittenTTS Nano · Bruno | 2.15% | 3.96% | 2.17% | 2.76% |
-| KittenTTS Nano · Hugo | 2.39% | 3.80% | 2.11% | 2.77% |
-| Piper Low · Danny | 2.62% | 5.60% | 2.55% | 3.59% |
-| Piper Low · Ryan | 2.81% | 5.51% | 2.87% | 3.73% |
-| Supertonic 3 · M2 · 3-step | 3.03% | 6.04% | 3.22% | 4.10% |
-| Supertonic 3 · M2 · 8-step | 2.05% | 3.56% | 8.08% | 4.56% |
-
-Inflect-Micro-v2: **2.52% Qwen3-ASR**, **5.45% Nemotron 3.5**, and **2.73% Whisper large-v3** semantic WER. The **3.57%** mean is descriptive only; individual recognizers remain visible because Whisper produced insertion-heavy hallucinations on a small subset of otherwise intelligible Supertonic 8-step clips.
+| CPU-ready PyTorch runtime, deterministic seeds, and punctuation-aware long text. | Frozen prompts, raw hypotheses, intervals, hashes, and per-system reports are included. |
 
 <details>
-<summary><strong>Open the frozen evaluation protocol</strong></summary>
-
-- Modern400 uses 400 identical unseen English prompts per system: 200 fixed modern/stress prompts plus 200 deterministic FLEURS `en_us` test prompts.
-- Exact-text exclusion was checked against 87,362 training transcripts.
-- Semantic WER is reported independently for `Qwen/Qwen3-ASR-1.7B`, `nvidia/nemotron-3.5-asr-streaming-0.6b`, and `openai/whisper-large-v3`.
-- All ASR inputs are explicitly resampled to 16 kHz and scored with the same disclosed English normalizer.
-- UTMOS22 uses `tarepan/SpeechMOS` v1.2.0 on a separate 500-prompt frozen generation set.
-- Headline intervals use 10,000 bootstrap samples.
-- The Modern400 corpus SHA-256 is `b7504ce2dce44a2da82770a6a5dfd2a034fe17e2113980f8a69663ade417a34c`.
-- Prompts, hypotheses, compressed row-level reports, and summaries ship under `evaluation/final/`.
-
-</details>
-
-## Runtime methodology
+<summary id="architecture-and-parameter-budget"><strong>Architecture and parameter budget</strong></summary>
 
-The model-specific snapshot below is retained as a transparent engineering measurement, not a portable hardware promise. It used one isolated process on an AMD EPYC 7K62, 50 prompts, three warmups, and runtime-default CPU threading.
-
-| RTF ↓ | Audio generated / wall time ↑ | Median utterance | p95 utterance | Cold load |
-| ---: | ---: | ---: | ---: | ---: |
-| 0.743 | 1.35× real time | 3.205 s | 4.681 s | 1.35 s |
-
-**RTF is wall time divided by generated audio duration.** For example, `0.54 RTF` means 1.85 seconds of audio were generated per second of wall time. It does not mean “1.85× faster than another model.” CPU model, thread policy, framework provider, and text length can materially change the result.
-
-<details>
-<summary><strong>Architecture and parameter budget</strong></summary>
-
-Inflect v2 is a parameter-efficient VITS-family, end-to-end text-to-waveform generator with an English phoneme frontend, monotonic alignment, stochastic latent synthesis, residual coupling flow, and an integrated alias-reduced neural waveform decoder.
+Inflect v2 is a parameter-efficient VITS-family end-to-end text-to-waveform generator with an English phoneme frontend, monotonic alignment, stochastic latent synthesis, residual coupling flow, and an integrated alias-reduced neural waveform decoder.
 
 | Component | Inflect-Micro-v2 |
 | --- | ---: |
@@ -214,7 +228,7 @@ The release describes the deployable architecture. Private corpus-construction a
 </details>
 
 <details>
-<summary><strong>Controls, determinism, and long text</strong></summary>
+<summary id="controls-determinism-and-long-text"><strong>Controls, determinism, and long text</strong></summary>
 
 | Control | Default | Public range | Meaning |
 | --- | ---: | ---: | --- |
@@ -227,7 +241,7 @@ Long passages are punctuation-aware chunks, not one unlimited autoregressive pas
 </details>
 
 <details>
-<summary><strong>Data, voice, and adaptation status</strong></summary>
+<summary id="data-voice-and-adaptation-status"><strong>Data, voice, and adaptation status</strong></summary>
 
 The release voice was trained on a single-speaker synthetic English corpus generated with a larger third-party TTS teacher. No teacher model is required or shipped at inference. The package does not redistribute a real speaker dataset and does not claim the synthetic voice as the identity of a real person.
 
@@ -267,6 +281,15 @@ Do not use the included voice to impersonate a real person, deceive listeners, o
 
 Original Inflect code and weights are released under Apache-2.0. Bundled third-party components retain their own notices in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md). `release_manifest.json` records packaged file sizes and SHA-256 hashes.
 
+### Private training scope and contact
+
+Inflect v2 is an **open-weight** release. Deployable weights, inference code, frontend code, evaluation prompts, and release reports are public. The training corpus-generation pipeline, private filtering infrastructure, and full optimization recipe are not part of the public package.
+
+Owen Song may share additional technical context privately for credible research, collaboration, reproducibility, or deployment inquiries when the request has a clear purpose and does not conflict with licensing or data-provenance constraints.
+
+- **Discord:** `b111ue` — fastest for informal technical questions
+- **Email:** [owen.aw.song@gmail.com](mailto:owen.aw.song@gmail.com) — preferred for professional inquiries
+
 ## Citation
 
 ```bibtex
@@ -278,4 +301,4 @@ Original Inflect code and weights are released under Apache-2.0. Bundled third-p
 }
 ```
 
-<p align="center"><sub>Developed independently by Owen Song. Inflect v2 is an open-weight release: inference code and deployable weights are public; the private training recipe and corpus-generation pipeline are not.</sub></p>
+<p align="center"><sub>Designed and developed independently by Owen Song · open weights · Apache-2.0 · complete local text-to-waveform inference</sub></p>