Moved the current implementation to src/audita_prototype, moved current test suite to tests/audita_prototype, and started a new, more modular application skeleton in src/audita

README.md

@@ -1,6 +1,13 @@
 # Audita
 
-Audita takes raw audio transcripts, deterministically merges short same-speaker segments into speaking turns, and uses an LLM to identify and fix misheard words, jargon, domain-specific terms, and conservative readability issues.
+Audita is now a framework-first transcript correction application. The public `audita` package provides:
+
+- deterministic transcript normalization
+- token-batched module orchestration
+- reusable module / filter / review-stage contracts
+- structured run reporting and work-dir diagnostics
+
+The previous working implementation has been preserved as `audita_prototype` inside this repository. Its full regression suite lives under `tests/audita_prototype`.
 
 ## Development
 
@@ -13,14 +20,23 @@ uv run pytest
 
 ## Usage
 
-Set an OpenRouter API key, then process a transcript with a glossary:
+Process a transcript with the new framework skeleton:
 
 ```sh
-export OPENROUTER_API_KEY=...
 uv run audita process transcript.json --glossary glossary.yaml --output corrected.json
 ```
 
-To also write a structured JSON report describing what Audita applied or skipped:
+The framework currently runs this default module sequence:
+
+1. `glossary_primary`
+2. `homophones`
+3. `glossary_secondary`
+4. `spoken_word`
+5. `grammar`
+
+At this stage the module implementations are stubs. The framework is executable end to end, performs deterministic normalization, runs the full module lifecycle, and emits structured reports, but does not yet apply substantive LLM-driven corrections.
+
+To also write a structured JSON report:
 
 ```sh
 uv run audita process transcript.json --glossary glossary.yaml --output corrected.json --report-json report.json
@@ -44,21 +60,14 @@ audita process transcript.json --glossary glossary.yaml --output corrected.json
 Without `--output`, Audita writes the corrected transcript JSON to stdout and progress logs to stderr.
 `--report-json` writes a separate machine-readable run report and never mixes report data into stdout.
 
-Useful configuration can be supplied by CLI flag or environment variable. CLI flags take precedence over environment variables.
+Useful configuration can be supplied by CLI flag or environment variable. CLI flags take precedence over environment variables. The framework does not currently require `OPENROUTER_API_KEY`, but the config fields remain available for future module implementations.
 
 | Environment variable | CLI flag | Default | Purpose |
 | --- | --- | --- | --- |
-| `AUDITA_MODEL` | `--model` | `openrouter/google/gemma-4-31b-it` | OpenRouter model to use |
-| `AUDITA_BASE_URL` | `--base-url` | `https://openrouter.ai/api/v1` | OpenAI-compatible API base URL |
-| `AUDITA_MAX_SECTION_TOKENS` | `--max-section-tokens` | `6144` | Maximum estimated tokens per LLM transcript section |
-| `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD` | `--glossary-confidence-threshold` | `0.80` | Minimum confidence required to apply a glossary correction |
-| `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD` | `--grammar-confidence-threshold` | `0.80` | Minimum confidence required to apply a grammar correction |
-| `AUDITA_GRAMMAR_VALIDATION_ENABLED` | `--grammar-validation-enabled` / `--no-grammar-validation-enabled` | `true` | Whether grammar corrections are checked by the semantic validator |
-| `AUDITA_GRAMMAR_VALIDATION_CONFIDENCE_THRESHOLD` | `--grammar-validation-confidence-threshold` | `0.80` | Minimum validator confidence required for validated grammar corrections |
-| `AUDITA_GRAMMAR_SPOKEN_FORM_VALIDATION_CONFIDENCE_THRESHOLD` | `--grammar-spoken-form-validation-confidence-threshold` | `0.80` | Minimum validator confidence required for spoken-form rescue corrections |
+| `AUDITA_MODEL` | `--model` | `openrouter/google/gemma-4-31b-it` | Reserved LLM model setting for future module implementations |
+| `AUDITA_BASE_URL` | `--base-url` | `https://openrouter.ai/api/v1` | Reserved OpenAI-compatible API base URL |
 | `AUDITA_MAX_RETRIES` | `--max-retries` | `3` | Maximum Instructor retries for structured responses |
-| `AUDITA_GLOSSARY_MAX_LLM_PASSES` | `--glossary-max-llm-passes` | `3` | Total glossary correction passes |
-| `AUDITA_GRAMMAR_MAX_LLM_PASSES` | `--grammar-max-llm-passes` | `3` | Total grammar/readability correction passes |
+| `AUDITA_MAX_SECTION_TOKENS` | `--max-section-tokens` | `6144` | Maximum estimated tokens per transcript batch |
 | `AUDITA_NORMALIZE_MAX_SEGMENT_GAP` | `--normalize-max-segment-gap` | `4.0` | Same-speaker gaps eligible for deterministic merging |
 | `AUDITA_NORMALIZE_ELLIPSIS_GAP` | `--normalize-ellipsis-gap` | `3.5` | Same-speaker gaps above this value are joined with ` ... ` |
 | `AUDITA_NORMALIZE_MAX_SEGMENT_DURATION` | `--normalize-max-segment-duration` | `60.0` | Maximum merged segment duration |
@@ -66,6 +75,8 @@ Useful configuration can be supplied by CLI flag or environment variable. CLI fl
 | `AUDITA_WORK_DIR` | `--work-dir` | `/tmp/audita` | Per-run scratch diagnostics directory |
 | `AUDITA_WORK_DIR_RETENTION` | `--work-dir-retention` | `auto` | Whether to retain the per-run work directory: `auto`, `always`, or `never` |
 
-`OPENROUTER_API_KEY` is required and is read from the environment.
-
 `AUDITA_WORK_DIR` stores per-run diagnostics while processing. Under the default `AUDITA_WORK_DIR_RETENTION=auto`, clean successful runs are removed, while failed runs and successful runs with final skipped corrections are preserved. Use `always` to keep every run directory and `never` to remove successful run directories even when skips remain.
+
+## Prototype Archive
+
+The archived prototype remains importable as `audita_prototype` and is still covered by its original regression suite. This is intentional: the new `audita` package is a fresh framework skeleton, not a thin wrapper around the old code.