narratio/docs/integrations/scriptorium.md

Narratio -> Scriptorium CLI Integration

1. Purpose

This document defines how Narratio should invoke Scriptorium through the public CLI.

This is a subprocess integration contract, not an internal Go API contract.

2. Assumptions

• scriptorium is installed and available on PATH.
• Scriptorium is configured with config.yml.
• config.yml provides prompt_dir, profile_dir, and schema_dir as needed.
• Prompt and profile libraries are already deployed for the environment.
• Narratio provides prepared artifact files (for example polished transcript, glossary, previous recap, campaign notes).
• Initial integration is synchronous subprocess execution.
• Narratio remains the orchestrator.

In normal operation, Narratio does not need to pass --prompt-dir and --profile-dir if they are supplied by Scriptorium config.

Narratio may pass --config <PATH> when it must use a non-default Scriptorium config file.

3. Core Commands Narratio May Call

Primary commands for subprocess integration:

• scriptorium run
• scriptorium render

For production generation, use scriptorium run.

scriptorium render is for debugging, dry-runs, test assertions, and validating command construction without LLM execution.

Note: scriptorium serve and HTTP API exist, but they are not the initial integration path.

4. Command Selection Guidance

• Use run to generate an output artifact.
• Use render to inspect the prepared prompt and effective settings without calling the LLM.
• Use render --format json when Narratio/tests need structured prepare output.

5. Recommended run Invocation Shape

Production shape:

scriptorium run \
  --prompt <prompt_id> \
  --input transcript=<processed-transcript-path> \
  --out <output-artifact-path>

Common optional additions:

• --config <path>: use a specific Scriptorium config file.
• --profile <profile_id>: override prompt default profile.
• --var name=value (repeatable): small metadata values.
• --input name=path (repeatable): additional named artifacts.
• --timeout <duration>: per-run timeout override.
• Runtime model override flags (--llm-base-url, --model, etc.) only for exceptional/operator-directed cases.

6. Recommended render Invocation Shape

Human-readable debug shape:

scriptorium render \
  --prompt <prompt_id> \
  --input transcript=<processed-transcript-path> \
  --format text

Structured debug/test shape:

scriptorium render \
  --prompt <prompt_id> \
  --input transcript=<processed-transcript-path> \
  --format json \
  --out <render-debug-path>

render does not call the LLM, does not validate model output, and does not perform repair.

7. Inputs

• Pass inputs as repeated --input name=path flags.
• name must match the Prompt Definition input name.
• Prefer absolute paths, or paths relative to a working directory controlled by Narratio.
• Pass Audita output as the primary transcript input.
• Additional inputs may include glossary, previous recap, campaign notes, event logs, final state maps, or other prompt-specific artifacts.
• Scriptorium reads input files directly; Narratio does not need to inline file content for CLI use.

8. Variables

Use repeated --var name=value for small metadata values.

Typical examples:

• session_date
• session_id
• campaign_name
• previous_session_id
• output_kind

Large content belongs in input files, not --var values.

9. Prompt IDs and Output Artifact Types

Narratio should treat prompt IDs as configuration, not hardcoded business logic.

Narratio config may map stage/output names to prompt IDs, for example:

• session recap prompt
• structured event extraction prompt
• glossary suggestion prompt
• player-facing summary prompt

Prompt IDs used by Narratio should come from the deployed Scriptorium prompt library.

10. Profiles

• Prompts may declare default_profile.
• Narratio may omit --profile to use prompt default profile.
• Narratio may pass --profile to force profile selection.
• This enables environment/profile selection like local-fast, local-quality, frontier, batch, or test profiles.
• Profile names should generally be Narratio configuration values.

11. Runtime Overrides

Supported runtime override flags:

• --llm-base-url
• --model
• --api-key-env
• --temperature
• --max-tokens
• --top-p
• --timeout

Guidance:

• Keep normal model/runtime settings in Execution Profiles.
• Use runtime overrides only for explicit per-run exceptions, tests, or operator overrides.
• Never pass raw API keys on the command line.
• --api-key-env names an environment variable; Narratio must ensure that variable is set in subprocess environment.

12. Config Behavior

• Default config path: /etc/scriptorium/config.yml.
• --config <PATH> overrides default path.
• Missing default config is allowed by Scriptorium.
• If --config is provided explicitly, the file must exist and be valid.
• CLI flags override config.yml.
• config.yml overrides built-in application defaults.

Narratio can either:

• rely on system default config path, or
• carry an explicit config path and pass --config.

13. Environment Handling

Subprocess environment recommendations:

• Pass through required API-key environment variables referenced by api_key_env.
• Do not pass raw API keys as CLI arguments.
• Avoid logging full environment dumps.
• Capture stdout and stderr separately.
• Use a controlled working directory.
• Prefer absolute artifact paths.

14. Output Handling

For scriptorium run:

• Use --out when Narratio needs durable artifact files.
• Without --out, artifact content is written to stdout.
• Preferred orchestration pattern: always use --out, then treat the file as stage output artifact.
• Capture stderr for diagnostics.

For scriptorium render:

• Use --out to store render diagnostics.
• Use --format json when tests need to inspect selected profile, effective runtime settings, input hashes, prompt hash, and rendered messages.

15. Exit Status and Errors

Current CLI behavior (verified from implementation/tests):

• 0: success.
• 1: runtime/parse/config/load/render/generation/IO error.
• 2: run completed but output validation failed (ValidationFailed).

Additional details:

• On run, output artifact write happens before exit code selection. If validation fails, artifact may still be written and exit code is 2.
• stderr carries both errors and normal run summary output; non-empty stderr alone does not imply failure.
• render returns 0 on success and 1 on failures.

Narratio should treat non-zero exit codes as failed stage execution, but may record generated artifact paths if a run exited 2 and output file exists.

16. Recommended Narratio Integration Pattern

1. Build CLI args from Narratio stage configuration.
2. Use subprocess context cancellation/timeout.
3. Pass absolute input paths.
4. Pass --out to a session-scoped artifact path.
5. Add --var metadata values.
6. Optionally add --config.
7. Optionally add --profile.
8. Ensure required API-key env vars are present.
9. Run subprocess synchronously.
10. Capture stdout/stderr separately.
11. On success, store output artifact path and invocation metadata in stage artifacts.
12. On failure, store exit code and stderr diagnostics in stage status.

17. Suggested Narratio Configuration Shape

Illustrative pipeline.yml shape:

scriptorium:
  binary: scriptorium
  config_path: /etc/scriptorium/config.yml
  timeout: 10m
  render_debug: false
  artifacts:
    session_recap:
      enabled: true
      prompt_id: dnd.session_recap
      profile_id: local-quality   # optional
      output_path: artifacts/session_recap.md
      timeout: 10m
      render_debug: false          # optional artifact override
      inputs:
        transcript:
          source: processed_transcript
          required: true
        previous_recap:
          source: previous_session_artifact
          artifact: session_recap
          path: ""                 # optional
          required: false
      vars:
        session_id: true
        session_date: true
        campaign_name: true
        previous_session_id: true
        output_kind: session_recap

The key idea: map Narratio artifact names to prompt ID, optional profile, expected inputs, vars, and output destination.

18. Testing Strategy for Narratio Integration

• Use scriptorium render --format json to verify command construction without LLM calls.
• Use dedicated test prompt/profile libraries for integration tests.
• Use small fixture transcripts.
• Verify missing-input failure behavior.
• Verify prompt default_profile behavior.
• Verify explicit --profile override behavior.
• Verify --config behavior (default and explicit).
• Verify output file creation when --out is used.
• Verify stderr capture on failures.
• Avoid real API keys in tests.

19. Security and Privacy Notes

• Never pass raw API keys on command line.
• Do not log full rendered prompts by default; transcripts may contain sensitive content.
• Avoid logging prompt content unless explicit debug mode is enabled.
• Treat generated artifacts as potentially sensitive.
• Use session-scoped, access-controlled output paths.
• api_key_env names should come from environment management, not embedded secrets.

20. Initial D&D Artifact Generation Examples

These are examples only. Use prompt IDs from the deployed prompt library.

Session recap:

scriptorium run \
  --prompt dnd.session_recap \
  --input transcript=/work/session-42/transcript.polished.md \
  --input glossary=/work/session-42/glossary.yml \
  --out /work/session-42/artifacts/session_recap.md

Structured events:

scriptorium run \
  --prompt dnd.structured_events \
  --input transcript=/work/session-42/transcript.polished.md \
  --out /work/session-42/artifacts/structured_events.json

Glossary suggestions:

scriptorium run \
  --prompt dnd.glossary_suggestions \
  --input transcript=/work/session-42/transcript.polished.md \
  --input previous_recap=/work/session-41/artifacts/session_recap.md \
  --out /work/session-42/artifacts/glossary_suggestions.md

Player-facing summary:

scriptorium run \
  --prompt dnd.player_summary \
  --input transcript=/work/session-42/transcript.polished.md \
  --input structured_events=/work/session-42/artifacts/structured_events.json \
  --out /work/session-42/artifacts/player_summary.md

21. Non-Goals

Initial Narratio integration should not:

• call Scriptorium internal Go packages
• use HTTP API as the primary path
• expect Scriptorium to read S3 refs directly
• make Scriptorium responsible for Narratio stage state
• make Scriptorium responsible for notification
• require Scriptorium to understand D&D workflow semantics beyond prompt definitions

22. Future Extension Notes

Possible later extensions:

• HTTP API integration
• S3 artifact references if Scriptorium adds S3 reader support
• richer render diagnostics and policy controls
• token budgeting/prompt-size checks
• batch execution if Scriptorium later adds batch support