# 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](pkg-scriptorium.md)
- CLI subprocess: [Subprocess integration](../integrations/subprocess.md)
- HTTP: [HTTP API reference](../api.md)
- File formats: [Configuration reference](../config.md)

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

```go
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:

```bash
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](../integrations/subprocess.md) 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](../api.md) 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.