eric/narratio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 15 Wiki Activity

Rewrite integration documentation and verify maintained examples

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-23 13:01:17 +00:00
parent 0299b128cf
commit 0d02cb9fa0
4 changed files with 156 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/integrations/README.md
View File

@@ -1,15 +1,19 @@
# Integration Documentation Index # Integrations Index
## Audience ## Audience
Developers and LLM coding agents changing Narratio's external integration contracts. Developers and coding agents changing Narratio's external integration boundaries.
## Scope ## Scope
Implemented-only reference notes for the external systems Narratio currently integrates with. `docs/integrations/` is the implementation-level reference for downstream tool adapter contracts.
## Integration Docs These docs cover what Narratio expects from external tools and what each adapter guarantees back to stage code.
- `audita.md`: Audita adapter invocation and validation contract.
- `seriatim.md`: Seriatim normalize/merge/trim adapter contract.
- `scriptorium.md`: Scriptorium run/render adapter contract.
## Canonical Owner ## Integration Contracts
`docs/integrations/` is the canonical home for external integration reference notes per `docs/policy/documentation.md`. - `audita.md`: transcript polishing adapter (`audita process`).
- `seriatim.md`: merge/normalize/trim adapter (`seriatim`).
- `scriptorium.md`: artifact run/render adapter (`scriptorium run|render`).
## Related Canonical Docs
- `docs/config.md`: operator-facing configuration reference.
- `docs/internal/adapters.md`: shared adapter boundary and runner wiring.
- `docs/internal/stage-*.md`: stage-specific integration usage.

100
docs/integrations/audita.md
View File

@@ -1,66 +1,60 @@
# Integration: audita # Integration: Audita
## Purpose ## Purpose
Define Narratio's adapter contract for transcript polishing via Audita CLI subprocess execution. Define the Audita adapter contract used by the `polish` stage.
## Inputs and Outputs ## Adapter Boundary
Inputs (`audita.PolishRequest`): Interface:
- base transcript path - `audita.Runner`
- glossary path - method: `Run(ctx, PolishRequest) (PolishResult, error)`
- output polished 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`): Primary implementation:
- polished transcript path - `internal/adapters/audita/SubprocessRunner`
- optional report path
- generated config path
- stdout/stderr log paths
- exit code, duration, invoked binary
- adapter metadata
## Boundaries Execution mode:
Owns: - subprocess invocation of `audita process`
- Deterministic CLI argument construction for `audita process`
- Environment bridging for API credentials
- Invocation config emission
- Output validation for polished transcript and report
Does not own: ## Request Contract
- Upstream/downstream stage orchestration `PolishRequest` carries:
- Credential sourcing policy beyond required env-var presence check - 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.
## Config Fields Used ## Result Contract
Via `pipeline.audita.*` mapped in app/stage wiring: `PolishResult` returns:
- `binary`, `timeout`, `llm_api_key_env`, `modules`, `base_url`, `model` - processed transcript path;
- `transcript_description`, `config_path`, `output_schema`, `work_dir_retention` - optional report path;
- `total_llm_concurrency`, `proposal_llm_concurrency`, `validation_model`, `validation_llm_concurrency`, `report` - work dir and generated-config/log paths;
- exit code, duration, binary provenance;
- adapter metadata map.
## External Adapters Used ## Validation and Failure Semantics
- Shared subprocess helper (`internal/adapters/subprocess`) to run CLI and capture logs. 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.
## State and Manifest Behavior Run fails for:
- No direct manifest writes. - missing required request paths;
- Stage-level metadata records adapter provenance and credential-present signal. - missing required credential env var when configured (`llm_api_key_env`);
- Generated invocation YAML is written when `GeneratedConfigPath` is provided. - subprocess execution failure;
- invalid processed transcript JSON (`segments` array required);
- invalid report JSON when reporting is enabled.
## Skip and Resume Behavior Failure results still include output/log/config/exit metadata for diagnostics.
- Adapter has no skip/resume logic. Stage/runner controls this.
## Failure Behavior ## Deterministic Behavior
- Constructor validation fails on invalid binary/timeout/schema/concurrency/URL values. - CLI args are built from runner config + request in a fixed order.
- Run fails on missing required paths, missing required credential env var, subprocess errors, invalid polished JSON shape, or invalid report JSON. - Generated invocation YAML (`audita.generated.v1`) is emitted when requested.
- Failures preserve stdout/stderr paths in returned result metadata. - Manifest writes are stage-owned; adapter itself is stateless.
## Tests to Inspect Before Changing ## Config Mapping
- `internal/adapters/audita/subprocess_test.go` Config fields consumed through runner/stage wiring are under `pipeline.audita.*`.
- `internal/adapters/audita/fake_test.go`
- `internal/stage/polish_test.go`
## Architectural Invariants Maintained example with Audita config:
- Polished output must be valid JSON with top-level `segments` array. - `examples/pipeline.full.annotated.yml`
- When report is enabled, report output must be valid JSON. - `examples/pipeline.production.yml`
- If `llm_api_key_env` is configured, credential must be present in environment.

104
docs/integrations/scriptorium.md
View File

@@ -1,64 +1,66 @@
# Integration: scriptorium # Integration: Scriptorium
## Purpose ## Purpose
Define Narratio's adapter contract for Scriptorium artifact generation and render-debug subprocess invocations. Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`.
## Inputs and Outputs ## Adapter Boundary
Inputs: Interface:
- `RunArtifactRequest`: binary, config path, prompt/profile IDs, input map, vars map, timeout, output path, logs/config paths, optional API env and working dir - `scriptorium.Runner`
- `RenderArtifactRequest`: same core fields for render mode - methods:
- `RunArtifact(ctx, RunArtifactRequest)`
- `RenderArtifact(ctx, RenderArtifactRequest)`
Outputs (`ArtifactResult`): Primary implementation:
- output path - `internal/adapters/scriptorium/SubprocessRunner`
- stdout/stderr log paths
- generated config path
- exit code and duration
- command mode (`run` or `render`)
- prompt/profile provenance
- validation failure signal
- adapter metadata
## Boundaries Execution modes:
Owns: - `scriptorium run`
- Deterministic CLI arg construction for `scriptorium run` and `scriptorium render` - `scriptorium render`
- Common request validation
- Invocation config emission
- Output existence/non-empty checks
- Validation-failure mapping for run exit code 2
Does not own: ## Request Contract
- Artifact selection policy (`analyze` stage) Both request types carry:
- Bounds semantic validation (`trim` stage) - binary/config/prompt/profile IDs;
- input map and vars map;
- output path;
- timeout;
- generated config + stdout/stderr log paths;
- optional API-key env var name;
- optional working directory.
## Config Fields Used ## Result Contract
Via `pipeline.scriptorium.*` and stage-level artifact config: `ArtifactResult` returns:
- `binary`, `config_path`, `timeout`, `render_debug` - output/log/generated-config paths;
- artifact-level `prompt_id`, `profile_id`, `timeout`, `inputs`, `vars`, `output_path` - exit code and duration;
- command mode (`run` or `render`);
- prompt/profile provenance;
- `ValidationFailed` marker;
- metadata map.
## External Adapters Used ## Validation and Failure Semantics
- Shared subprocess helper (`internal/adapters/subprocess`). Request validation fails for:
- missing binary, prompt id, or output path;
- non-positive timeout;
- empty input/var names;
- empty input path values;
- missing required credential env var when `APIKeyEnv` is set.
## State and Manifest Behavior Run behavior:
- No direct manifest writes. - subprocess errors propagate with context;
- Stage metadata records adapter outputs and command mode. - `run` exit code `2` is mapped to `ValidationFailed=true`;
- Generated invocation YAML is written when requested. - successful subprocess still fails if output file is missing or empty.
## Skip and Resume Behavior Render behavior:
- Adapter has no skip/resume logic. Stage/runner controls execution. - subprocess errors propagate;
- output file must exist and be non-empty.
## Failure Behavior ## Deterministic Behavior
- Request validation fails for missing binary/prompt/output, invalid timeout, invalid input/var names, or missing required API env var. - input and var maps are sorted into deterministic `--input` and `--var` CLI args.
- Subprocess errors bubble with command context. - generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested.
- `run` exit code 2 is treated as `ValidationFailed=true` and surfaced as error by calling stage. - adapter is stateless and does not own artifact-selection policy.
- Successful subprocess still fails if output file is missing/empty.
## Tests to Inspect Before Changing ## Config Mapping
- `internal/adapters/scriptorium/subprocess_test.go` Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`.
- `internal/adapters/scriptorium/fake_test.go`
- `internal/stage/analyze_test.go`
- `internal/stage/trim_test.go`
## Architectural Invariants Maintained examples with Scriptorium config:
- Both modes require explicit timeout > 0. - `examples/pipeline.full.annotated.yml`
- Input/var maps are sorted into deterministic CLI argument order. - `examples/pipeline.production.yml`
- Run-mode validation failures are represented explicitly, not silently skipped.

90
docs/integrations/seriatim.md
View File

@@ -1,60 +1,56 @@
# Integration: seriatim # Integration: Seriatim
## Purpose ## Purpose
Define Narratio's adapter contract for merge, normalize, and trim subprocess invocations of Seriatim. Define the Seriatim adapter contract used by `merge`, `normalize`, and `trim`.
## Inputs and Outputs ## Adapter Boundary
Inputs: Interface:
- `MergeRequest`: raw/per-speaker normalized transcript inputs, base output path, optional report, speaker/autocorrect paths, logs/config - `seriatim.Runner`
- `NormalizeRequest`: input transcript, output path, schema, optional report, timeout/log/config - methods:
- `TrimRequest`: input transcript, output path, keep selector, timeout/log/config - `Run(ctx, MergeRequest)`
- `Normalize(ctx, NormalizeRequest)`
- `Trim(ctx, TrimRequest)`
Outputs: Primary implementation:
- `MergeResult`, `NormalizeResult`, `TrimResult` with output paths, logs/config paths, exit code, duration, binary provenance, and metadata. - `internal/adapters/seriatim/SubprocessRunner`
## Boundaries Execution modes:
Owns: - `seriatim merge`
- Validated deterministic CLI invocation construction - `seriatim normalize`
- Optional env tuning propagation for merge - `seriatim trim`
- Invocation config file emission
- JSON output validation
Does not own: ## Request/Result Contracts
- Transcript input selection/materialization logic (stage-owned) - `MergeRequest`/`MergeResult`: multi-input merge to base transcript, optional report.
- Bounds computation (scriptorium/trim-stage-owned) - `NormalizeRequest`/`NormalizeResult`: transcript normalization with explicit schema.
- `TrimRequest`/`TrimResult`: transcript trimming with required keep selector.
## Config Fields Used Results include output/log/config paths, timing, exit code, and metadata.
Via `pipeline.seriatim.*` mapped in app/stage wiring:
- `binary`, `timeout`, `output_schema`, `coalesce_gap`, `report`
- `env.overlap_word_run_gap`
- `env.overlap_word_run_reorder_window`
- `env.backchannel_max_duration`
- `env.filler_max_duration`
## External Adapters Used ## Validation and Failure Semantics
- Shared subprocess helper (`internal/adapters/subprocess`). Runner construction validates:
- binary presence;
- timeout > 0;
- supported output schema (`seriatim-minimal|seriatim-intermediate|seriatim-full`);
- non-negative coalesce gap.
## State and Manifest Behavior Invocation fails on:
- No direct manifest writes. - missing required request paths/inputs;
- Stage metadata consumes adapter result fields and preserves generated config/log references. - invalid normalize schema override;
- subprocess failure;
- invalid JSON outputs;
- missing `segments` array for normalize/trim transcript outputs.
## Skip and Resume Behavior When report paths are provided/enabled, report files must parse as JSON.
- Adapter has no skip/resume logic. Runner controls stage execution.
## Failure Behavior ## Deterministic Behavior
- Constructor fails for invalid binary/timeout/output-schema/coalesce-gap. - argument ordering is deterministic per command construction.
- Merge fails on missing output path/inputs/report path (if enabled), subprocess errors, invalid merged output JSON, invalid report JSON. - merge env overrides are explicit (`SERIATIM_*`) and only emitted when configured.
- Normalize fails on missing input/output, invalid schema, subprocess errors, invalid final output JSON shape, invalid report JSON. - generated invocation YAML (`seriatim.generated.v1`) is emitted when requested.
- Trim fails on missing input/output/keep selector, subprocess errors, invalid final-trimmed output JSON shape. - adapter does not write manifests or choose stage inputs.
## Tests to Inspect Before Changing ## Config Mapping
- `internal/adapters/seriatim/subprocess_test.go` Config fields consumed through runner/stage wiring are under `pipeline.seriatim.*`.
- `internal/adapters/seriatim/fake_test.go`
- `internal/stage/merge_test.go`
- `internal/stage/normalize_test.go`
- `internal/stage/trim_test.go`
## Architectural Invariants Maintained examples with Seriatim config:
- Supported output schemas are limited to `seriatim-minimal`, `seriatim-intermediate`, `seriatim-full`. - `examples/pipeline.full.annotated.yml`
- Final and final-trimmed outputs must include `segments` arrays. - `examples/pipeline.production.yml`
- Merge/normalize/trim all route through deterministic subprocess invocation.