Integration: Scriptorium

Purpose

Define the Scriptorium adapter contract used by analyze and trim-bounds generation in trim.

External Boundary

Narratio invokes Scriptorium as a subprocess in these modes:

scriptorium run
scriptorium render

The request timeout and parent cancellation bound each invocation. Internal runner composition is documented in the adapter implementation guide.

Request Contract

Both request types carry:

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.

Result Contract

ArtifactResult returns:

output/log/generated-config paths;
exit code and duration;
command mode (run or render);
prompt/profile provenance;
ValidationFailed marker;
metadata map.

Validation and Failure Semantics

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.

Run behavior:

subprocess errors propagate with context;
run exit code 2 is mapped to ValidationFailed=true;
successful subprocess still fails if output file is missing or empty.

Render behavior:

subprocess errors propagate;
output file must exist and be non-empty.

Deterministic Behavior

input and var maps are sorted into deterministic --input and --var CLI args.
stage wiring adds session_id=narratio-session-<session_id> to every Scriptorium request for sticky upstream routing, overriding any configured vars.session_id.
generated invocation YAML (scriptorium.generated.v1) is emitted when requested.
adapter is stateless and does not own artifact-selection policy.

Configuration

Operator-selected values are defined under pipeline.scriptorium.*, including per-artifact settings under pipeline.scriptorium.artifacts.*, in the configuration reference.

Maintained examples with Scriptorium config:

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

2.2 KiB Raw Blame History