72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
# 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.
|
|
|
|
## Development
|
|
|
|
This project is set up for `uv`.
|
|
|
|
```sh
|
|
uv sync --extra dev
|
|
uv run pytest
|
|
```
|
|
|
|
## Usage
|
|
|
|
Set an OpenRouter API key, then process a transcript with a glossary:
|
|
|
|
```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:
|
|
|
|
```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.
|
|
|
|
| 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_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_NORMALIZE_MAX_SEGMENT_GAP` | `--normalize-max-segment-gap` | `5.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` |
|
|
|
|
`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.
|