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

Clarify user and integration documentation contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-08-09 21:41:23 +00:00
parent 115a44f629
commit bd2d5e2496
8 changed files with 187 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/cli.md
View File

@@ -135,14 +135,13 @@ narratio clean --all [--dry-run] [--clear-cache] [--config <pipeline.yml>]
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 <session_id> <source> [...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).

2
docs/config.md
View File

@@ -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

32
docs/integrations/README.md
View File

@@ -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.

20
docs/integrations/audita.md
View File

@@ -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`

22
docs/integrations/scriptorium.md
View File

@@ -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`

24
docs/integrations/seriatim.md
View File

@@ -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`

66
docs/integrations/whisperx.md Normal file
View File

@@ -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.

41
docs/troubleshooting.md
View File

@@ -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)