audita/python

Audita

This directory contains the frozen Python implementation of Audita.
It is retained as the behavioral reference for the Go port.

The canonical implementation is now the Go code at the repository root.
This Python implementation is legacy/reference and is no longer the primary operational path.
Do not add new features here except to fix reference-test issues needed for port validation.

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.

uv sync --extra dev
uv run pytest

Usage

Process a transcript with the current framework implementation:

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:

uv run audita process transcript.json --glossary glossary.yaml --modules grammar --output corrected.json

To also write a structured JSON report:

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:

./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:

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. Default OpenRouter runs require LLM API credentials, because the glossary, homophones, spoken_word, and grammar modules make real LLM calls. Self-hosted or other non-default OpenAI-compatible endpoints may not require credentials. 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; required for the default OpenRouter endpoint and optional for non-default endpoints; CLI overrides both environment-key variants
AUDITA_VALIDATION_LLM_API_KEY	--validation-llm-api-key	unset	Validation-phase LLM API credential; defaults to the primary LLM API key and is optional for non-default validation endpoints
AUDITA_MODEL	--model	openrouter/google/gemma-4-31b-it	LLM model name sent to the configured OpenAI-compatible endpoint
AUDITA_VALIDATION_MODEL	--validation-model	unset	Validation-phase LLM model; defaults to AUDITA_MODEL
AUDITA_BASE_URL	--base-url	https://openrouter.ai/api/v1	OpenAI-compatible API base URL
AUDITA_VALIDATION_BASE_URL	--validation-base-url	unset	Validation-phase OpenAI-compatible API base URL; defaults to AUDITA_BASE_URL
AUDITA_LLM_TIMEOUT_SECONDS	--llm-timeout-seconds	600	Per-request timeout in seconds for LLM calls to the configured OpenAI-compatible endpoint
AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS	--validation-llm-timeout-seconds	unset	Validation-phase per-request timeout in seconds; defaults to AUDITA_LLM_TIMEOUT_SECONDS
AUDITA_VALIDATION_MAX_PROMPT_TOKENS	--validation-max-prompt-tokens	2048	Maximum estimated tokens per validation-phase LLM prompt batch
AUDITA_TARGET_SECTIONS	--target-sections	unset	Exact number of contiguous proposal-stage transcript sections; errors if min/max token bounds cannot be satisfied
AUDITA_MAX_RETRIES	--max-retries	3	Maximum Instructor retries for structured responses
AUDITA_VALIDATION_MAX_RETRIES	--validation-max-retries	unset	Validation-phase structured-output retries; defaults to AUDITA_MAX_RETRIES
AUDITA_VALIDATION_LLM_CONCURRENCY	--validation-llm-concurrency	unset	Validation-phase LLM concurrency; defaults to AUDITA_LLM_CONCURRENCY
AUDITA_MAX_SECTION_TOKENS	--max-section-tokens	8192	Maximum estimated tokens per proposal-stage transcript section
AUDITA_MIN_SECTION_TOKENS	--min-section-tokens	2048	Minimum estimated tokens per proposal-stage transcript section when balancing for concurrency
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.

Validation-phase LLM settings inherit from the primary AUDITA_* LLM settings by default. Set any of the AUDITA_VALIDATION_* values only when you want LLM-backed validators to use a different model, endpoint, credential, timeout, retry budget, or concurrency level.

OpenRouter remains the default out of the box:

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:

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

If your self-hosted endpoint requires authentication, you can still set AUDITA_LLM_API_KEY; Audita simply no longer requires it for non-default endpoints.

Or the actual OpenAI API:

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.