68 lines
2.1 KiB
Markdown
68 lines
2.1 KiB
Markdown
# Integration: Scriptorium
|
|
|
|
## 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)`
|
|
|
|
Primary implementation:
|
|
- `internal/adapters/scriptorium/SubprocessRunner`
|
|
|
|
Execution modes:
|
|
- `scriptorium run`
|
|
- `scriptorium render`
|
|
|
|
## 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.
|
|
|
|
## Config Mapping
|
|
Config fields consumed through runner/stage wiring are under `pipeline.scriptorium.*` plus per-artifact settings under `pipeline.scriptorium.artifacts.*`.
|
|
|
|
Maintained examples with Scriptorium config:
|
|
- `examples/pipeline.full.annotated.yml`
|
|
- `examples/pipeline.production.yml`
|