audita/docs/migrations/v2.md

Migrating to Audita v2

Audita v2 adopts ConfigKit for configuration and PromptKit for LLM execution. Version-1 configuration files, environment overlays, and retired flags are not accepted. Copy a maintained local or service example, then select real models in the accompanying examples/profiles/ files. A testing overlay is shown at examples/overlays/testing.yml; its model choice carries no cost, speed, or quality guarantee.

Configuration and invocation

Use version: 2 in a YAML main file. --config selects that file; otherwise process and config print-effective look at /usr/local/etc/audita/config.yml, then /etc/audita/config.yml. config validate requires --config. AUDITA_CONFIG no longer selects a file. Settings resolve from defaults, main file, optional --overlay <name> in overlays/<name>.yml, then explicitly supplied setting flags. General AUDITA_* environment overlays no longer apply. Unknown fields and version-1 files fail; there is no automatic converter.

Keep transcript as the positional path and --glossary and --output as invocation paths. The former --report-json output has been replaced by the default errors.yml, recoveries.yml, and report.md bundle; use --reporting=false to disable it or --report-dir for stdout output. Keep pipeline.modules / --modules and output.schema / --output-schema. An explicit pipeline.modules: [] or --modules '' runs no correction modules; omission uses the default sequence. Ordered repetitions still matter.

Move llm.proposal.base_url and llm.validation.base_url to a shared backends.<id>.endpoint when both roles use one service. Move old role models to PromptKit profile files and select them with llm.proposal_profile and llm.validation_profile, or --proposal-profile and --validation-profile. Omitted validation selection inherits the final proposal selection; explicit empty or null is invalid. profiles_dir defaults to profiles beside the main config. Complete profiles name a registered backend and model. Per-role --base-url, --validation-base-url, --model, and --validation-model are retired.

Move old llm.*.api_key_env to backends.<id>.credential, a scalar name of a nonempty environment variable, such as credential: AUDITA_SERVICE_KEY. Credentials on every surviving backend must resolve, including unselected backends. Omit or set null for an unauthenticated local backend. Profiles cannot perform another key lookup. --llm-api-key and --validation-llm-api-key are retired. AUDITA_LLM_API_KEY, OPENROUTER_API_KEY, and AUDITA_VALIDATION_LLM_API_KEY have no implicit meaning, though any of those names can be used explicitly as a credential reference.

Replace concurrency.total_llm, .proposal_llm, and .validation_llm plus --total-llm-concurrency, --llm-concurrency, --proposal-llm-concurrency, and --validation-llm-concurrency with backends.<id>.concurrency (default 1) and optional queue_capacity (default 1024; zero means no waiting admission). One backend capacity is shared by both roles and all retry/repair attempts within this Audita process. It does not coordinate other processes.

Move old role timeout values and --llm-timeout-seconds / --validation-llm-timeout-seconds to profile timeout_seconds, a per-attempt limit, and llm.operation_timeout, a Go duration such as 15m covering the whole logical call. Replace old max_retries and --max-retries / --validation-max-retries with common llm.transient_retries (additional eligible attempts per generation) and llm.repair_attempts (additional generations for structurally invalid JSON). Explicit zero disables either feature. Cancellation and the operation deadline cover capacity waiting, backoff, generation, and repairs. PromptKit owns which failures can retry or repair; Audita does not retry semantic rejections.

The following domain settings and explicit flags retain their meaning:

File field	Explicit flag
validation.max_prompt_tokens	--validation-max-prompt-tokens
chunking.target_sections	--target-sections
chunking.max_section_tokens, .min_section_tokens	--max-section-tokens, --min-section-tokens
normalization.max_segment_gap, .ellipsis_gap, .max_segment_duration, .max_segment_tokens	--normalize-max-segment-gap, --normalize-ellipsis-gap, --normalize-max-segment-duration, --normalize-max-segment-tokens
thresholds.glossary, .homophones, .spoken_word, .grammar	--glossary-confidence-threshold, --homophones-confidence-threshold, --spoken-word-confidence-threshold, --grammar-confidence-threshold
context.description	--transcript-description
reporting.enabled, .stdout_dir	--reporting[=true|false], --report-dir
diagnostics.debug, .work_dir	--debug[=true|false], --work-dir

Normalization gaps and durations are numeric seconds, so replace 4s, 3.5s, and 60s with 4.0, 3.5, and 60.0. The operation timeout remains a Go duration string. chunking.target_sections may be omitted or null for automatic chunking; zero is invalid. Null is not a general synonym for omission: nonoptional scalar settings reject it. Empty context.description clears context. Legacy diagnostics.retention and --work-dir-retention are removed. Debug is off by default and its directory is retained whenever enabled.

Remove old implicit variables AUDITA_MODULES, AUDITA_MODEL, AUDITA_VALIDATION_MODEL, AUDITA_BASE_URL, AUDITA_VALIDATION_BASE_URL, AUDITA_LLM_TIMEOUT_SECONDS, AUDITA_VALIDATION_LLM_TIMEOUT_SECONDS, AUDITA_MAX_RETRIES, AUDITA_VALIDATION_MAX_RETRIES, AUDITA_TOTAL_LLM_CONCURRENCY, AUDITA_LLM_CONCURRENCY, AUDITA_PROPOSAL_LLM_CONCURRENCY, AUDITA_VALIDATION_LLM_CONCURRENCY, AUDITA_VALIDATION_MAX_PROMPT_TOKENS, AUDITA_TARGET_SECTIONS, AUDITA_MAX_SECTION_TOKENS, AUDITA_MIN_SECTION_TOKENS, AUDITA_NORMALIZE_MAX_SEGMENT_GAP, AUDITA_NORMALIZE_ELLIPSIS_GAP, AUDITA_NORMALIZE_MAX_SEGMENT_DURATION, AUDITA_NORMALIZE_MAX_SEGMENT_TOKENS, AUDITA_GLOSSARY_CONFIDENCE_THRESHOLD, AUDITA_HOMOPHONES_CONFIDENCE_THRESHOLD, AUDITA_SPOKEN_WORD_CONFIDENCE_THRESHOLD, AUDITA_GRAMMAR_CONFIDENCE_THRESHOLD, AUDITA_WORK_DIR, and AUDITA_WORK_DIR_RETENTION. Put those values in the named fields above or pass their surviving explicit flags.

Inspecting and operating

Run audita config validate --config <file> before processing. Use audita config print-effective --config <file> --view settings|profiles|explain to inspect redacted ConfigKit YAML, selected PromptKit profile controls, or field origins and derivations. Each view resolves both roles offline without calling a provider. --overlay testing selects the same overlay for validation, inspection, and processing. The old effective-config JSON format is replaced by YAML; settings YAML alone does not show profile-owned model controls.

The ordinary output contract now uses version-1 audita-errors and audita-recoveries YAML documents plus a fixed Markdown overview. Compact outcomes distinguish logical operations from provider attempts. With debug enabled, utilization remains grouped by backend capacity and usage fields retain known/complete flags. Debug runs write effective-config.redacted.yaml, selected-profiles.yaml, config-origins.yaml, utilization-diagnostics.json, and llm-execution.json. Request and response artifacts remain redacted debugging material. See operations for placement and paths, configuration for all settings, and the CLI reference for current flags.

Debug ledger consumers should recognize the deterministic validator key non_empty_resulting_segment in place of non_empty_corrected_text. The empty_resulting_segment reason is unchanged. Candidate-backed ledger entries now include proposed_corrected_text: "" for an empty replacement, and applied deletions also include applied_corrected_text: ""; omitted fields still mean there was no candidate or no applied edit, respectively. See the debug artifact contract.