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 and ProfileDir are required. 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",
	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.

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, and structured-output spec. 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