136 lines
8.1 KiB
Markdown
136 lines
8.1 KiB
Markdown
# 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](../../examples/minimal-config.yml) or
|
|
[service](../../examples/production-config.yml) 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](../integrations/output-files.md) 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](../operations.md#diagnostics-directory) for placement
|
|
and paths, [configuration](../config.md) for all settings, and the
|
|
[CLI reference](../cli.md) 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](../integrations/output-files.md#debug-only-files).
|