#217 - P1 — add transcript-normalizer configuration, selection, status and diagnostics - nsaspy/zara

nsaspy commented

2026-08-28 03:23:52 +00:00

Owner

Parent: #215
Depends on: #216, #217
Integrates with: #3, #92, daemon/client configuration surfaces

Goal

Make transcript normalization an explicit user-selectable Zara setting with one configuration authority and clear runtime health/status.

Configuration

Extend existing TOML configuration with validated settings equivalent to:

[voice.transcript_normalization]
backend = "off"          # off | s1-mini
failure_policy = "raw"   # raw | fail-turn
language_policy = "auto"

[voice.transcript_normalization.s1_mini]
runtime = "openai-compatible"
base_url = "http://127.0.0.1:11434/v1"
model = "s1-mini"
style = "balanced"
structure = "prose"
context = "general"
timeout_ms = 1000

Exact naming is design-owned, but requirements are:

default remains off unless explicitly changed;
unknown backend/runtime rejected;
endpoint/model/timing values bounded and validated;
style/structure/context constrained to supported values;
localhost/local endpoint is the safe documented path;
configuring a remote endpoint is explicit and visibly changes privacy posture;
secrets, if ever required by a configured endpoint, use existing secret/config handling and never diagnostics output.

Selection and lifecycle

backend can be selected without changing the STT backend;
runtime reports selected backend, model, endpoint locality, ready/degraded/unavailable state and last bounded error class;
live reload is supported only if the owning config architecture makes it safe; otherwise restart requirement is explicit;
no silent model download/start of a third-party daemon merely because backend = "s1-mini" is selected.

User surfaces

Expose selection/status through the supported CLI/config diagnostics and, once #92 settings UI is available, the same underlying descriptors in desktop settings. Do not create a second desktop-only configuration store.

Settings should explain:

S1-mini is post-STT cleanup, not transcription;
current model is English-only;
local endpoint keeps cleanup local;
failure_policy = raw preserves the raw transcript if cleanup is unavailable;
#122 semantic rewrite is a separate later stage.

Tests

TDD config defaults, round-trip, invalid backend, invalid control values, remote/local endpoint classification, timeout bounds, unavailable provider status, redaction and restart/live-reload semantics.

Acceptance

A user can select off or s1-mini through Zara's normal configuration system and inspect whether normalization is actually active, local, ready or degraded without exposing secrets or confusing it with STT/#122.

Parent: #215 Depends on: #216, #217 Integrates with: #3, #92, daemon/client configuration surfaces ## Goal Make transcript normalization an explicit user-selectable Zara setting with one configuration authority and clear runtime health/status. ## Configuration Extend existing TOML configuration with validated settings equivalent to: ```toml [voice.transcript_normalization] backend = "off" # off | s1-mini failure_policy = "raw" # raw | fail-turn language_policy = "auto" [voice.transcript_normalization.s1_mini] runtime = "openai-compatible" base_url = "http://127.0.0.1:11434/v1" model = "s1-mini" style = "balanced" structure = "prose" context = "general" timeout_ms = 1000 ``` Exact naming is design-owned, but requirements are: - default remains `off` unless explicitly changed; - unknown backend/runtime rejected; - endpoint/model/timing values bounded and validated; - style/structure/context constrained to supported values; - localhost/local endpoint is the safe documented path; - configuring a remote endpoint is explicit and visibly changes privacy posture; - secrets, if ever required by a configured endpoint, use existing secret/config handling and never diagnostics output. ## Selection and lifecycle - backend can be selected without changing the STT backend; - runtime reports selected backend, model, endpoint locality, ready/degraded/unavailable state and last bounded error class; - live reload is supported only if the owning config architecture makes it safe; otherwise restart requirement is explicit; - no silent model download/start of a third-party daemon merely because `backend = "s1-mini"` is selected. ## User surfaces Expose selection/status through the supported CLI/config diagnostics and, once #92 settings UI is available, the same underlying descriptors in desktop settings. Do not create a second desktop-only configuration store. Settings should explain: - S1-mini is post-STT cleanup, not transcription; - current model is English-only; - local endpoint keeps cleanup local; - `failure_policy = raw` preserves the raw transcript if cleanup is unavailable; - #122 semantic rewrite is a separate later stage. ## Tests TDD config defaults, round-trip, invalid backend, invalid control values, remote/local endpoint classification, timeout bounds, unavailable provider status, redaction and restart/live-reload semantics. ## Acceptance A user can select `off` or `s1-mini` through Zara's normal configuration system and inspect whether normalization is actually active, local, ready or degraded without exposing secrets or confusing it with STT/#122.

nsaspy referenced this issue

2026-08-28 03:24:19 +00:00

[EPIC] Selectable post-STT transcript normalization backends, including local S1-mini #220