scriptorium/docs/consumers/api.md

Consumer Integration Overview

This guide helps applications choose a Scriptorium interface and understand their responsibilities. The linked contracts own interface syntax and wire semantics.

Interface	Use when
Go package	The consumer is Go and needs typed requests, results, or an injected LLM client.
CLI subprocess	The consumer needs process isolation or is not written in Go.
HTTP API	The consumer needs a service boundary or remote access.

• Go package: package contract
• CLI subprocess: subprocess integration
• HTTP service: HTTP API reference
• Prompt, profile, schema, and credential configuration: configuration reference

Minimal Go Use

engine, err := scriptorium.NewEngine(scriptorium.Config{
	PromptDir:  "./examples/prompts",
	ProfileDir: "./examples/profiles",
})
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"),
	},
})
if err != nil {
	return err
}
_ = prepared

For a maintained program, see examples/go-library/prepare.

Consumer Responsibilities

Consumers are responsible for:

• selecting and deploying prompt, profile, and schema assets;
• supplying required inputs and template variables;
• supplying credentials through the applicable interface;
• protecting rendered prompts and generated artifacts as potentially sensitive;
• deciding whether validation-failed output is usable; and
• retrying only when another model call is acceptable.

Scriptorium does not persist run state. A retry can produce different output and can incur another provider request. CLI exit behavior belongs to the CLI reference; HTTP status behavior belongs to the HTTP API reference; package errors and results belong to the package contract.