scriptorium/docs/consumers/pkg-scriptorium.md

Package scriptorium

Import path:

import "gitea.maximumdirect.net/eric/scriptorium"

The root package is a public facade over Scriptorium's prompt execution use case. It keeps internal/* packages private while exposing typed construction, preparation, execution, inputs, results, and errors.

Construct An Engine

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

PromptDir is required. ProfileDir is optional; omit it to use built-in profiles only, or set it to overlay custom profiles above built-ins. SchemaDir defaults to the built-in schema directory. Timeout and HTTPClient configure the default OpenAI-compatible client used by Run when no custom LLM client is supplied.

Prepare A Prompt

Prepare resolves the prompt definition, profile, inputs, variables, output contract, structured-output metadata, and rendered messages without calling an LLM.

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

Input helpers:

• scriptorium.File(path) loads an input artifact from a file.
• scriptorium.Inline(body) passes inline input content.
• scriptorium.InlineWithURI(uri, body) passes inline content with URI metadata.

Run A Prompt

Run prepares the prompt, calls the configured LLM client, builds the output artifact, and validates the output.

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

RunResult includes the run ID, output artifact, raw output, validation result, prompt/profile/model metadata, effective model parameters, input hashes, token/cache usage, and timing fields. Validation content failures return a successful RunResult with failed validation status. Runtime validation errors return ErrValidation.

For the public Go API, pass provider credentials with RunRequest.APIKey. The value is request-scoped, uses json:"-", is preferred over profile api_key_env by the default OpenAI-compatible client, and is not included in PreparedRun or RunResult JSON. Do not store raw keys in config, prompt files, or profile YAML.

Inject An LLM Client

Use WithLLMClient for tests or custom model integrations:

type fakeLLM struct{}

func (fakeLLM) Generate(ctx context.Context, req scriptorium.GenerateRequest) (*scriptorium.GenerateResponse, error) {
	return &scriptorium.GenerateResponse{
		Content: "generated text",
		Usage:   scriptorium.TokenUsage{TotalTokens: 12},
	}, nil
}

engine, err := scriptorium.NewEngine(cfg, scriptorium.WithLLMClient(fakeLLM{}))

The injected client receives the rendered prompt, effective execution target, target presence metadata for explicit numeric overrides, structured-output spec, and request API key when provided. GenerateRequest.APIKey also uses json:"-"; custom and fake clients should avoid logging or serializing it. WithLLMClient(nil) returns ErrInvalidConfig.

Request Overrides

RunRequest.Execution accepts per-request overrides. Numeric override fields are pointers so explicit zero values are preserved:

zero := 0
req.Execution = &scriptorium.ExecutionTargetOverride{
	MaxTokens: &zero,
}

Errors

Public methods wrap context while preserving stable sentinel checks with errors.Is:

• ErrInvalidConfig
• ErrInvalidRequest
• ErrPromptNotFound
• ErrProfileNotFound
• ErrPromptLoad
• ErrProfileLoad
• ErrArtifactLoad
• ErrPromptRender
• ErrLLMGenerate
• ErrValidation

Example:

if errors.Is(err, scriptorium.ErrPromptNotFound) {
	return err
}

Examples

Run the prepare-only example from the repository root:

go run ./examples/go-library/prepare