scriptorium/docs/config/prompt-definitions.md

Prompt Definition Files

Prompt Definitions define what Scriptorium should do.

A prompt file is YAML, typically stored under prompts/, for example prompts/generic.structured_events.yaml.

Complete Example

id: generic.structured_events
version: "1.0.0"
default_profile: local-quality
description: Extract events from a transcript into structured JSON.

inputs:
  - name: transcript
    required: true
    content_type: text/markdown
    description: Source transcript
  - name: glossary
    required: false
    content_type: text/yaml
    description: Optional glossary context

messages:
  - role: system
    content: |
      You are a structured extraction assistant.
      Return only JSON.
  - role: user
    content_file: ./generic.structured_events.user.md

output:
  format: json
  validation_mode: json_schema
  schema_path: structured_events.schema.json
  repair_attempts: 1

Available Options

• id (required): Prompt identifier used by --prompt / prompt_id.
• version (required): Prompt version string.
• default_profile (optional): Execution profile ID used when no explicit profile is provided.
• description (optional): Human-readable description.

inputs[]

• name (required): Logical input name referenced in templates via {{input "name"}}.
• required (optional): If true, run fails when input is missing.
• content_type (optional): Metadata only (not enforced yet).
• description (optional): Human-readable input description.

messages[]

• role (required): Message role such as system or user.
• content (optional): Inline Go-template message body.
• content_file (optional): Path to a template file.

Each message must set exactly one of content or content_file.

output

• format (required): One of text, markdown, json.
• validation_mode (required): One of none, basic, json, json_schema.
• schema_path (required when validation_mode: json_schema): Path to JSON Schema file.
• repair_attempts (required): Number of bounded repair retries (>= 0).

Notes and Rules

• Unknown YAML fields fail to load (strict decoding).
• content_file paths are resolved relative to the prompt YAML file.
• For json_schema validation mode, Scriptorium also sends provider-level structured output requests automatically.