123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# 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.
|