scriptorium/docs/consumers/api.md

Consumer Integration Overview

This guide is for applications that call Scriptorium from another codebase.

Scriptorium exposes three integration surfaces:

Surface	Use when
Go package	The consumer is Go, needs typed requests/results, or wants injected LLM clients for tests.
CLI subprocess	The consumer wants process isolation or is not written in Go.
HTTP API	The consumer needs a service boundary or remote access to POST /v1/runs.

Canonical references:

• Go package: Package scriptorium
• CLI subprocess: Subprocess integration
• HTTP: HTTP API reference
• File formats: Configuration reference

Required Deployment Inputs

Every integration needs operators to provide:

• prompt definitions;
• profile definitions or built-in profile IDs;
• schema files when prompts use json_schema;
• input artifacts or inline input bodies;
• API-key environment variables or direct per-request keys where supported.

Raw API keys do not belong in config, prompt files, profile YAML, CLI arguments, or HTTP request bodies.

Recommended Workflow

Use the Go package when:

• the consumer is a Go application;
• the application needs context.Context cancellation;
• repeated calls should avoid subprocess startup;
• tests need a fake LLM client;
• direct per-request RunRequest.APIKey is required.

Use the CLI subprocess when:

• the consumer is not Go;
• process isolation is useful;
• stdout/stderr separation and exit codes are enough;
• the consumer already manages local files and environment variables.

Use HTTP when:

• Scriptorium should run as a service;
• multiple clients need a shared prompt/profile deployment;
• clients can reach a trusted, protected HTTP boundary.

Minimal Go Example

engine, err := scriptorium.NewEngine(scriptorium.Config{
	PromptDir:  "./examples/prompts",
	ProfileDir: "./examples/profiles",
	SchemaDir:  "./examples/schemas",
})
if err != nil {
	return err
}

prepared, err := engine.Prepare(ctx, scriptorium.RunRequest{
	PromptID: "generic.markdown_summary",
	Inputs: map[string]scriptorium.ArtifactRef{
		"transcript": scriptorium.File("./examples/fixtures/transcript.md"),
		"glossary":   scriptorium.File("./examples/fixtures/glossary.yml"),
	},
})
if err != nil {
	return err
}
_ = prepared.Messages

Run the maintained package example:

go run ./examples/go-library/prepare

Subprocess Workflow

Invoke scriptorium render for preflight and scriptorium run for generation. Capture stdout and stderr separately. Treat exit code 2 from run as a completed generation with failed validation.

See Subprocess integration for the stable invocation contract.

HTTP Workflow

Run scriptorium serve behind trusted controls and send JSON requests to POST /v1/runs.

Do not duplicate endpoint schemas in consumers. Use the HTTP API reference as the authoritative contract.

Consumer Responsibilities

Consumers are responsible for:

• selecting prompt/profile IDs as deployment configuration;
• supplying all required inputs and vars;
• protecting generated artifacts and rendered prompts as sensitive data;
• deciding whether to keep output when validation fails;
• implementing retries only when another model call is acceptable.

Scriptorium does not persist run state. Retrying a failed or timed-out request can produce different output and can incur another provider request.

Status Behavior

• Go package methods return typed results or errors that support errors.Is.
• CLI run exits 2 when generation succeeds but validation fails.
• HTTP returns 200 OK for generated-content validation failures and exposes the failed status in the response body.
• Runtime validation failures are errors.