narratio/docs/integrations/audita.md

Integration: audita

Purpose

Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution.

Inputs and Outputs

Inputs (audita.PolishRequest):

• merged transcript path
• glossary path
• output processed transcript path
• optional report path (required when report enabled)
• work dir
• generated config path
• stdout/stderr log paths
• optional module/model/base URL and concurrency knobs

Outputs (audita.PolishResult):

• processed transcript path
• optional report path
• generated config path
• stdout/stderr log paths
• exit code, duration, invoked binary
• adapter metadata

Boundaries

Owns:

• Deterministic CLI argument construction for audita process
• Environment bridging for API credentials
• Invocation config emission
• Output validation for processed transcript and report

Does not own:

• Upstream/downstream stage orchestration
• Credential sourcing policy beyond required env-var presence check

Config Fields Used

Via pipeline.audita.* mapped in app/stage wiring:

• binary, timeout, llm_api_key_env, modules, base_url, model
• transcript_description, config_path, output_schema, work_dir_retention
• total_llm_concurrency, proposal_llm_concurrency, validation_model, validation_llm_concurrency, report

External Adapters Used

• Shared subprocess helper (internal/adapters/subprocess) to run CLI and capture logs.

State and Manifest Behavior

• No direct manifest writes.
• Stage-level metadata records adapter provenance and credential-present signal.
• Generated invocation YAML is written when GeneratedConfigPath is provided.

Skip and Resume Behavior

• Adapter has no skip/resume logic. Stage/runner controls this.

Failure Behavior

• Constructor validation fails on invalid binary/timeout/schema/concurrency/URL values.
• Run fails on missing required paths, missing required credential env var, subprocess errors, invalid processed JSON shape, or invalid report JSON.
• Failures preserve stdout/stderr paths in returned result metadata.

Tests to Inspect Before Changing

• internal/adapters/audita/subprocess_test.go
• internal/adapters/audita/fake_test.go
• internal/stage/polish_test.go

Architectural Invariants

• Processed output must be valid JSON with top-level segments array.
• When report is enabled, report output must be valid JSON.
• If llm_api_key_env is configured, credential must be present in environment.