136 lines
6.7 KiB
Markdown
136 lines
6.7 KiB
Markdown
# Audita
|
|
|
|
Audita is a framework-first transcript correction application. The public `audita` package provides:
|
|
|
|
- deterministic transcript normalization
|
|
- token-batched module orchestration
|
|
- concrete `glossary`, `homophones`, `spoken_word`, and `grammar` modules built on reusable proposal / validator 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
|
|
|
|
This project is set up for `uv`.
|
|
|
|
```sh
|
|
uv sync --extra dev
|
|
uv run pytest
|
|
```
|
|
|
|
## Usage
|
|
|
|
Process a transcript with the current framework implementation:
|
|
|
|
```sh
|
|
uv run audita process transcript.json --glossary glossary.yaml --output corrected.json
|
|
```
|
|
|
|
The framework currently runs this default module sequence:
|
|
|
|
1. `glossary`
|
|
2. `homophones`
|
|
3. `glossary`
|
|
4. `spoken_word`
|
|
5. `grammar`
|
|
|
|
Resolved run instance names are auto-numbered for repeats, so the default report pipeline is:
|
|
|
|
1. `glossary_1`
|
|
2. `homophones`
|
|
3. `glossary_2`
|
|
4. `spoken_word`
|
|
5. `grammar`
|
|
|
|
The default module sequence is fully implemented today:
|
|
|
|
- `glossary` proposes glossary-supported acoustic corrections
|
|
- `homophones` proposes conservative homophone and mistranscription corrections
|
|
- `spoken_word` proposes conservative dysfluency cleanup
|
|
- `grammar` proposes punctuation, capitalization, and spacing cleanup only
|
|
|
|
To run a custom module sequence, pass `--modules`:
|
|
|
|
```sh
|
|
uv run audita process transcript.json --glossary glossary.yaml --modules grammar --output corrected.json
|
|
```
|
|
|
|
To also write a structured JSON report:
|
|
|
|
```sh
|
|
uv run audita process transcript.json --glossary glossary.yaml --output corrected.json --report-json report.json
|
|
```
|
|
|
|
From a checked-out repository, you can also use the root launcher:
|
|
|
|
```sh
|
|
./audita process transcript.json --glossary glossary.yaml --output corrected.json
|
|
```
|
|
|
|
For a system-wide command, install the source tree under `/usr/local/src/audita`, sync dependencies there, and symlink the root launcher into your `PATH`:
|
|
|
|
```sh
|
|
cd /usr/local/src/audita
|
|
uv sync --extra dev
|
|
ln -s /usr/local/src/audita/audita /usr/local/bin/audita
|
|
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. Normal runs now require LLM API credentials, because the `glossary`, `homophones`, `spoken_word`, and `grammar` modules make real LLM calls. `AUDITA_LLM_API_KEY` and `--llm-api-key` are the preferred provider-neutral credential surfaces, while `OPENROUTER_API_KEY` remains supported as a backward-compatible fallback.
|
|
|
|
| Environment variable | CLI flag | Default | Purpose |
|
|
| --- | --- | --- | --- |
|
|
| `AUDITA_MODULES` | `--modules` | `glossary,homophones,glossary,spoken_word,grammar` | Comma-separated logical module keys to run; CLI overrides the environment value |
|
|
| `AUDITA_LLM_API_KEY` | `--llm-api-key` | unset | Preferred provider-neutral LLM API credential; CLI overrides both environment-key variants |
|
|
| `AUDITA_MODEL` | `--model` | `openrouter/google/gemma-4-31b-it` | LLM model name sent to the configured OpenAI-compatible endpoint |
|
|
| `AUDITA_BASE_URL` | `--base-url` | `https://openrouter.ai/api/v1` | OpenAI-compatible API base URL |
|
|
| `AUDITA_MAX_RETRIES` | `--max-retries` | `3` | Maximum Instructor retries for structured responses |
|
|
| `AUDITA_MAX_SECTION_TOKENS` | `--max-section-tokens` | `6144` | Maximum estimated tokens per transcript batch |
|
|
| `AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD` | `--glossary-confidence-threshold` | `0.8` | Minimum confidence required for glossary proposals to survive validation |
|
|
| `AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD` | `--grammar-confidence-threshold` | `0.8` | Minimum confidence required for grammar proposals to survive validation |
|
|
| `AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD` | `--homophones-confidence-threshold` | `0.8` | Minimum confidence required for homophone proposals to survive validation |
|
|
| `AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD` | `--spoken-word-confidence-threshold` | `0.8` | Minimum confidence required for spoken-word proposals to survive validation |
|
|
| `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 |
|
|
| `AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS` | `--normalize-max-segment-tokens` | `2048` | Maximum merged segment prompt payload size |
|
|
| `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` |
|
|
|
|
Set `AUDITA_MODULES=grammar` to run only the grammar module by default, or override it per command with `--modules`.
|
|
|
|
OpenRouter remains the default out of the box:
|
|
|
|
```sh
|
|
export AUDITA_LLM_API_KEY=your-openrouter-key
|
|
audita process transcript.json --glossary glossary.yaml --output corrected.json
|
|
```
|
|
|
|
You can point Audita at any OpenAI-compatible endpoint by changing `AUDITA_BASE_URL` and, if needed, `AUDITA_MODEL`. For example, a local vLLM server:
|
|
|
|
```sh
|
|
export AUDITA_LLM_API_KEY=local-dev-key
|
|
export AUDITA_BASE_URL=http://localhost:8000/v1
|
|
export AUDITA_MODEL=meta-llama/Llama-3.1-8B-Instruct
|
|
audita process transcript.json --glossary glossary.yaml --output corrected.json
|
|
```
|
|
|
|
Or the actual OpenAI API:
|
|
|
|
```sh
|
|
export AUDITA_LLM_API_KEY=your-openai-key
|
|
export AUDITA_BASE_URL=https://api.openai.com/v1
|
|
export AUDITA_MODEL=gpt-4.1-mini
|
|
audita process transcript.json --glossary glossary.yaml --output corrected.json
|
|
```
|
|
|
|
`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.
|
|
Failed runs always preserve the run directory and include an authoritative `report.json` alongside normalization and prompt/response diagnostics.
|
|
|
|
## 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 framework-oriented rewrite, not a thin wrapper around the old code.
|