From bd2d5e249690f655eb1970973beeb5cddb0e298e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 9 Aug 2026 21:41:23 +0000 Subject: [PATCH] Clarify user and integration documentation contracts --- docs/cli.md | 43 +++++++++++++-------- docs/config.md | 2 +- docs/integrations/README.md | 32 +++++++++++----- docs/integrations/audita.md | 20 +++++----- docs/integrations/scriptorium.md | 22 +++++------ docs/integrations/seriatim.md | 24 ++++++------ docs/integrations/whisperx.md | 66 ++++++++++++++++++++++++++++++++ docs/troubleshooting.md | 41 +++++++++++++++++++- 8 files changed, 187 insertions(+), 63 deletions(-) create mode 100644 docs/integrations/whisperx.md diff --git a/docs/cli.md b/docs/cli.md index d0de5c1..f104db7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -135,14 +135,13 @@ narratio clean --all [--dry-run] [--clear-cache] [--config ] Behavior: -- session mode removes: - - `{workspace.root}/work/{campaign}/{session_id}` - - `{spool.root}/{campaign}/{session_id}` -- `--all` removes: - - `{workspace.root}/work/*` - - direct children under `{spool.root}` +- session mode removes the selected session's local work and spool state; +- `--all` removes all local session work and spool state; - cache remains unless `--clear-cache` is provided. +See [Operations: Cleanup](./operations.md#cleanup) for deletion scope and +post-publish cleanup behavior. + ### `session plan` ```bash @@ -207,17 +206,11 @@ Behavior: - discovers committed remote current state; - plans local restores; -- writes `reports/restore-latest.json` on execution; +- writes an execution report; - blocks conflicting overwrites unless `--force` is set. -Default restore scope: - -- `manifest.json` -- `transcripts/**` -- `artifacts/**` -- `previous/**` when required by configured previous-session inputs - -`audio/**` is included only with `--include-audio`. +See [Operations: Restore Workflow](./operations.md#restore-workflow) for the +default restore scope, report location, and conflict-handling workflow. ### `session artifacts` @@ -237,10 +230,13 @@ narratio session locks remove [...common config flags] Behavior: -- list mode merges static `pipeline.publish.locks` with remote `{session_prefix}/locks.yml`; +- list mode reports the effective merge of static and remote locks; - add/remove mutate only remote locks; - static locks from pipeline config cannot be removed by CLI commands. +See [Operations: Publish Locks](./operations.md#publish-locks) for lock storage +and precedence. + ## `--artifacts` Selection Rules - accepted on `run`, `run-stage`, `analyze`, and `publish`; @@ -279,3 +275,18 @@ Force publish only: ```bash narratio publish 2026-04-04 ``` + +## Output And Exit Behavior + +- Successful commands write their result or summary to standard output and + exit with status `0`. +- Command failures and invalid invocations write an error to standard error and + exit with status `1`. +- An unknown top-level command also prints the top-level usage summary to + standard error. +- `session restore --help` prints its command-specific usage and exits with + status `0`. + +Output is intended for operator inspection. Narratio does not currently offer +a machine-readable CLI output mode; durable machine-readable state is recorded +in manifests and reports described in [Operations](./operations.md). diff --git a/docs/config.md b/docs/config.md index c21abe7..3289901 100644 --- a/docs/config.md +++ b/docs/config.md @@ -209,7 +209,7 @@ Rules: | `pipeline.scriptorium.artifacts` | map | No | empty | | `pipeline.notification.backend` | string | No | empty | | `pipeline.notification.recipient` | string | No | empty | -| `pipeline.notification.timeout` | duration | No | `30s` | +| `pipeline.notification.timeout` | duration | No | empty | ### Scriptorium Artifact Entries diff --git a/docs/integrations/README.md b/docs/integrations/README.md index 533ac93..7b86eeb 100644 --- a/docs/integrations/README.md +++ b/docs/integrations/README.md @@ -1,19 +1,33 @@ # Integrations Index ## Audience -Developers and coding agents changing Narratio's external integration boundaries. + +Operators, developers, and coding agents who need to understand Narratio's +externally observable integration boundaries. ## Scope -`docs/integrations/` is the implementation-level reference for downstream tool adapter contracts. -These docs cover what Narratio expects from external tools and what each adapter guarantees back to stage code. +`docs/integrations/` is the canonical reference for protocols, invocation and +data contracts, logical outputs, and compatibility behavior at external tool +boundaries. + +These documents describe what Narratio sends or invokes, what it accepts in +return, and how failures are surfaced. Internal composition and stage mechanics +belong in [the adapter implementation guide](../internal/adapters.md) and the +focused stage documents. ## Integration Contracts -- `audita.md`: transcript polishing adapter (`audita process`). -- `seriatim.md`: merge/normalize/trim/render adapter (`seriatim`). -- `scriptorium.md`: artifact run/render adapter (`scriptorium run|render`). + +- [Audita](./audita.md): transcript polishing (`audita process`). +- [Seriatim](./seriatim.md): merge, normalize, trim, and render operations. +- [Scriptorium](./scriptorium.md): artifact generation and debug rendering + (`scriptorium run|render`). +- [WhisperX](./whisperx.md): speaker-audio transcription over HTTP. ## 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. + +- [Configuration](../config.md): operator-facing configuration reference. +- [Adapter implementation](../internal/adapters.md): shared adapter boundary and + runner wiring. +- [Internal documentation](../internal/overview.md): stage-specific integration + usage and component ownership. diff --git a/docs/integrations/audita.md b/docs/integrations/audita.md index 6d57410..3f95a65 100644 --- a/docs/integrations/audita.md +++ b/docs/integrations/audita.md @@ -3,16 +3,12 @@ ## Purpose Define the Audita adapter contract used by the `polish` stage. -## Adapter Boundary -Interface: -- `audita.Runner` -- method: `Run(ctx, PolishRequest) (PolishResult, error)` +## External Boundary -Primary implementation: -- `internal/adapters/audita/SubprocessRunner` - -Execution mode: -- subprocess invocation of `audita process` +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). ## Request Contract `PolishRequest` carries: @@ -52,8 +48,10 @@ Failure results still include output/log/config/exit metadata for diagnostics. - 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.*`. +## Configuration + +Operator-selected values are defined under `pipeline.audita.*` in the +[configuration reference](../config.md#pipeline). Maintained example with Audita config: - `examples/pipeline.full.annotated.yml` diff --git a/docs/integrations/scriptorium.md b/docs/integrations/scriptorium.md index 5f9c0af..36cd645 100644 --- a/docs/integrations/scriptorium.md +++ b/docs/integrations/scriptorium.md @@ -3,20 +3,17 @@ ## Purpose Define the Scriptorium adapter contract used by `analyze` and trim-bounds generation in `trim`. -## Adapter Boundary -Interface: -- `scriptorium.Runner` -- methods: - - `RunArtifact(ctx, RunArtifactRequest)` - - `RenderArtifact(ctx, RenderArtifactRequest)` +## External Boundary -Primary implementation: -- `internal/adapters/scriptorium/SubprocessRunner` +Narratio invokes Scriptorium as a subprocess in these modes: -Execution modes: - `scriptorium run` - `scriptorium render` +The request timeout and parent cancellation bound each invocation. Internal +runner composition is documented in +[the adapter implementation guide](../internal/adapters.md). + ## Request Contract Both request types carry: - binary/config/prompt/profile IDs; @@ -59,8 +56,11 @@ Render behavior: - generated invocation YAML (`scriptorium.generated.v1`) is emitted when requested. - adapter is stateless and does not own artifact-selection policy. -## Config Mapping -Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`. +## Configuration + +Operator-selected values are defined under `pipeline.scriptorium.*`, including +per-artifact settings under `pipeline.scriptorium.artifacts.*`, in the +[configuration reference](../config.md#pipeline). Maintained examples with Scriptorium config: - `examples/pipeline.full.annotated.yml` diff --git a/docs/integrations/seriatim.md b/docs/integrations/seriatim.md index 33821a1..cd9e26e 100644 --- a/docs/integrations/seriatim.md +++ b/docs/integrations/seriatim.md @@ -3,24 +3,19 @@ ## Purpose Define the Seriatim adapter contract used by `merge`, `normalize`, `trim`, and `render`. -## Adapter Boundary -Interface: -- `seriatim.Runner` -- methods: - - `Run(ctx, MergeRequest)` - - `Normalize(ctx, NormalizeRequest)` - - `Trim(ctx, TrimRequest)` - - `Render(ctx, RenderRequest)` +## External Boundary -Primary implementation: -- `internal/adapters/seriatim/SubprocessRunner` +Narratio invokes Seriatim as a subprocess in these modes: -Execution modes: - `seriatim merge` - `seriatim normalize` - `seriatim trim` - `seriatim render` +The configured timeout and parent cancellation bound each invocation. Internal +runner composition is documented in +[the adapter implementation guide](../internal/adapters.md). + ## Request/Result Contracts - `MergeRequest`/`MergeResult`: multi-input merge to base transcript, optional report. - `NormalizeRequest`/`NormalizeResult`: transcript normalization with explicit schema. @@ -53,8 +48,11 @@ When report paths are provided/enabled, report files must parse as JSON. - generated invocation YAML (`seriatim.generated.v1`) is emitted when requested. - adapter does not write manifests or choose stage inputs. -## Config Mapping -Config fields consumed through runner/stage wiring are under `pipeline.seriatim.*` and `pipeline.render.*`. +## Configuration + +Operator-selected values are defined under `pipeline.seriatim.*` and +`pipeline.render.*` in the +[configuration reference](../config.md#pipeline). Maintained examples with Seriatim config: - `examples/pipeline.full.annotated.yml` diff --git a/docs/integrations/whisperx.md b/docs/integrations/whisperx.md new file mode 100644 index 0000000..038c695 --- /dev/null +++ b/docs/integrations/whisperx.md @@ -0,0 +1,66 @@ +# Integration: WhisperX + +## Purpose + +WhisperX transcribes each prepared speaker audio file for Narratio's +`transcribe` stage. Narratio uses an HTTP boundary and installs each successful +response as that speaker's raw transcript JSON. + +## HTTP Boundary + +Narratio sends an HTTP `POST` to the configured transcription URL using +`multipart/form-data` with: + +- `file`: the audio file, retaining its base filename; and +- `language`: the configured language string. + +The server must return a `2xx` response whose body is valid JSON. Narratio does +not currently require a more specific response schema at this boundary. + +## Request And Result Contract + +Each adapter request identifies a speaker, a readable audio file, and the +destination for the raw transcript. The HTTP request carries the audio and +language; the speaker identifier remains Narratio orchestration metadata. + +On success, Narratio atomically writes the response body to the requested +destination. The adapter result reports that logical output together with the +attempt count, final HTTP status when available, elapsed duration, and adapter +identity metadata. A failed or invalid response is not installed as the +transcript output. + +## Retry, Timeout, And Cancellation + +- The configured timeout applies independently to each HTTP attempt. +- `retries` means additional attempts after the first. +- HTTP `429`, HTTP `5xx`, attempt timeouts, and network errors are retryable. +- Other HTTP `4xx` responses and explicit cancellation are not retryable. +- Narratio waits the configured retry delay between attempts and aborts that + wait when the parent context is canceled. + +## Validation And Failure Semantics + +Client construction rejects a missing or invalid absolute transcription URL, +a missing language, a non-positive timeout, negative retries, or a negative +retry delay. A request fails before transmission when its audio or output path +is missing. + +Non-`2xx` status, transport failure, response-size overflow, invalid JSON, or +failure to install the output causes the transcription to fail. Errors include +attempt context, and the result retains attempts, final status when available, +and elapsed duration for diagnostics. + +## Determinism And Concurrency + +Each audio request has stable multipart field names, and successful bytes are +installed atomically. The transcribe stage may process speaker files in +parallel, bounded by the configured concurrency. It records results in stable +speaker order after all work completes; any speaker failure fails the stage. + +## Related Canonical Docs + +- [Configuration](../config.md#pipeline) defines the operator-selected + WhisperX URL, language, timeouts, retry policy, and concurrency. +- [Adapter implementation](../internal/adapters.md) describes internal wiring. +- [Transcribe stage](../internal/stage-transcribe.md) describes stage mechanics, + durable artifacts, and manifests. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d3362b4..8efd254 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -24,6 +24,8 @@ Safe fix: - pass explicit `--config`, `--campaign` or `--campaign-file`, and `--session`. +Relevant reference: [Configuration discovery](./config.md#discovery-and-selection). + ## Session template placeholders rejected Symptom: @@ -44,6 +46,8 @@ Safe fix: - generate concrete session YAML with `narratio session init`. +Relevant reference: [Operations: Session Initialization](./operations.md#session-initialization). + ## Strict decode or schema validation failure Symptom: @@ -64,6 +68,8 @@ Safe fix: - align config with [docs/config.md](./config.md) and maintained files under `examples/`. +Relevant reference: [Configuration](./config.md). + ## Audio mode conflict Symptom: @@ -74,10 +80,18 @@ Likely cause: - configured both local and S3 session audio inputs. +Diagnostics: + +```bash +narratio session validate 2026-04-04 +``` + Safe fix: - use local mode (`audio_dir` or `audio_files`) or S3 mode (`audio_s3.prefix`), not both. +Relevant reference: [Session configuration](./config.md#session). + ## `--artifacts` selection error Symptom: @@ -90,10 +104,18 @@ Likely causes: - empty list entry (for example trailing comma); - `run-stage` used with non-`analyze`/`publish` target. +Diagnostics: + +```bash +narratio session artifacts 2026-04-04 +``` + Safe fix: - provide only configured keys and use `--artifacts` with supported commands/stages. +Relevant reference: [CLI artifact selection](./cli.md). + ## Previous-session artifact input missing Symptom: @@ -124,6 +146,8 @@ or rerun prepare after correcting session config: narratio run-stage prepare 2026-04-04 --force ``` +Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow). + ## Session lock conflict (`.lock`) Symptom: @@ -147,6 +171,8 @@ Safe fix: - wait for active process completion; - remove stale lock only after confirming no live process owns it. +Relevant reference: [Operations: Local State Layout](./operations.md#local-state-layout). + ## Restore conflict without `--force` Symptom: @@ -168,6 +194,8 @@ Safe fix: - review conflicts; - rerun with `--force` only when remote state should overwrite local. +Relevant reference: [Operations: Restore Workflow](./operations.md#restore-workflow). + ## Restore current-state discovery failure Symptom: @@ -191,6 +219,8 @@ Safe fix: - resolve storage/auth issue; - republish from healthy local state if current pointer is missing. +Relevant reference: [Operations: Publish Workflow](./operations.md#publish-workflow). + ## Publish output failure Symptom: @@ -217,6 +247,8 @@ Safe fix: - correct publish source/destination rules; - retry after storage failure is resolved. +Relevant reference: [Publish configuration](./config.md#publish-configuration-summary). + ## Render markdown source missing Symptom: @@ -232,7 +264,6 @@ Diagnostics: ```bash narratio session status 2026-04-04 -narratio run-stage render 2026-04-04 --force ``` Safe fix: @@ -244,6 +275,8 @@ narratio run-stage render 2026-04-04 --force narratio run-stage analyze 2026-04-04 --force ``` +Relevant reference: [Operations: Stage Execution](./operations.md#stage-execution-and-continuation-behavior). + ## Secrets or storage credential failure Symptom: @@ -269,6 +302,8 @@ Safe fix: - provide required env vars; - keep secret values out of YAML. +Relevant reference: [Secrets](./config.md#secrets-handling). + ## S3 audio prepare failure Symptom: @@ -284,7 +319,7 @@ Likely causes: Diagnostics: ```bash -narratio run-stage prepare 2026-04-04 --force +narratio session validate 2026-04-04 ``` Safe fix: @@ -292,6 +327,8 @@ Safe fix: - verify prefix contents and storage access; - keep session audio mode consistent. +Relevant reference: [Operations](./operations.md). + ## References - [docs/cli.md](./cli.md)