narratio/docs/integrations/audita.md

Integration: Audita

Purpose

Define the Audita adapter contract used by the polish stage.

Adapter Boundary

Interface:

• audita.Runner
• method: Run(ctx, PolishRequest) (PolishResult, error)

Primary implementation:

• internal/adapters/audita/SubprocessRunner

Execution mode:

• subprocess invocation of audita process

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;
• optional module/model/base-url/config/output-schema/concurrency settings.

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.

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.

Config Mapping

Config fields consumed through runner/stage wiring are under pipeline.audita.*.

Maintained example with Audita config:

• examples/pipeline.full.annotated.yml
• examples/pipeline.production.yml