2026-05-23 13:01:17 +00:00
|
|
|
# Integration: Audita
|
2026-05-18 22:03:59 -05:00
|
|
|
|
|
|
|
|
## Purpose
|
2026-05-23 13:01:17 +00:00
|
|
|
Define the Audita adapter contract used by the `polish` stage.
|
|
|
|
|
|
2026-08-09 21:41:23 +00:00
|
|
|
## External Boundary
|
2026-05-23 13:01:17 +00:00
|
|
|
|
2026-08-09 21:41:23 +00:00
|
|
|
Narratio invokes `audita process` as a subprocess for each polish operation.
|
|
|
|
|
The configured timeout and parent cancellation bound the invocation. Internal
|
|
|
|
|
runner composition is documented in
|
|
|
|
|
[the adapter implementation guide](../internal/adapters.md).
|
2026-05-23 13:01:17 +00:00
|
|
|
|
|
|
|
|
## Request Contract
|
|
|
|
|
`PolishRequest` carries:
|
|
|
|
|
- required transcript/glossary/output/work-dir paths;
|
|
|
|
|
- optional report path (required when report mode is enabled);
|
|
|
|
|
- generated config and stdout/stderr log paths;
|
2026-08-10 22:43:22 +00:00
|
|
|
- optional per-invocation module override.
|
|
|
|
|
|
|
|
|
|
The constructed runner owns static Audita settings: binary, timeout,
|
|
|
|
|
credentials, default modules, model and endpoint settings, validation and output
|
|
|
|
|
settings, report mode, and concurrency. The `polish` stage supplies only
|
|
|
|
|
invocation-specific paths and may override modules for that invocation.
|
2026-05-23 13:01:17 +00:00
|
|
|
|
|
|
|
|
## Result Contract
|
|
|
|
|
`PolishResult` returns:
|
|
|
|
|
- processed transcript path;
|
|
|
|
|
- optional report path;
|
|
|
|
|
- work dir and generated-config/log paths;
|
|
|
|
|
- exit code, duration, binary provenance;
|
|
|
|
|
- adapter metadata map.
|
|
|
|
|
|
|
|
|
|
## Validation and Failure Semantics
|
|
|
|
|
Construction fails for invalid static config values, including:
|
|
|
|
|
- empty binary;
|
|
|
|
|
- non-positive timeout;
|
|
|
|
|
- invalid base URL;
|
|
|
|
|
- invalid output schema;
|
|
|
|
|
- invalid work-dir retention value;
|
|
|
|
|
- invalid concurrency values.
|
|
|
|
|
|
|
|
|
|
Run fails for:
|
|
|
|
|
- missing required request paths;
|
|
|
|
|
- missing required credential env var when configured (`llm_api_key_env`);
|
|
|
|
|
- subprocess execution failure;
|
|
|
|
|
- invalid processed transcript JSON (`segments` array required);
|
|
|
|
|
- invalid report JSON when reporting is enabled.
|
|
|
|
|
|
2026-08-10 18:30:28 +00:00
|
|
|
Processed transcript JSON is limited to 64 MiB and optional report JSON to 16
|
|
|
|
|
MiB. Both must be regular files without symlinked path components.
|
|
|
|
|
|
2026-05-23 13:01:17 +00:00
|
|
|
Failure results still include output/log/config/exit metadata for diagnostics.
|
|
|
|
|
|
|
|
|
|
## Deterministic Behavior
|
|
|
|
|
- CLI args are built from runner config + request in a fixed order.
|
|
|
|
|
- Generated invocation YAML (`audita.generated.v1`) is emitted when requested.
|
|
|
|
|
- Manifest writes are stage-owned; adapter itself is stateless.
|
|
|
|
|
|
2026-08-09 21:41:23 +00:00
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
Operator-selected values are defined under `pipeline.audita.*` in the
|
|
|
|
|
[configuration reference](../config.md#pipeline).
|
2026-05-23 13:01:17 +00:00
|
|
|
|
|
|
|
|
Maintained example with Audita config:
|
2026-08-09 21:50:21 +00:00
|
|
|
|
|
|
|
|
- [Full annotated pipeline](../../examples/pipeline.full.annotated.yml)
|
|
|
|
|
- [Production-shaped pipeline](../../examples/pipeline.production.yml)
|
