Running the Interpreter

Turn a folder of captures into an ExtractionResult and a Screenplay .play file, and optionally configure a language model to refine the names.

Prerequisites

• A folder of .jsonl capture files, produced by the Extractor (see Point Prologue at your system).
• Docker, to run cratis/prologue-interpreter.

Run batch mode

Batch mode is the image’s default — no flags needed:

docker run --rm \
  -v "$(pwd)/captures:/captures" \
  -v "$(pwd)/output:/output" \
  cratis/prologue-interpreter

It reads every capture file under /captures, analyzes the correlated evidence, writes a provisional /output/extraction-result.json plus a generated .play file, and exits.

Every input and output path is overridable, as a CLI argument on the binary or an environment variable on the container:

CLI argument	Environment variable	Default	Meaning
--captures <folder>	PROLOGUE_CAPTURES	/captures in the image	Folder to read .jsonl capture files from
--output <file>	PROLOGUE_OUTPUT	/output/extraction-result.json in the image	Where to write the ExtractionResult JSON
--play-output <file>	PROLOGUE_PLAY_OUTPUT	next to the output file, named after the derived system name	Where to write the generated .play file
--prologue-id <guid>	PROLOGUE_ID	—	Which Prologue’s captures to interpret, when a folder holds more than one

cratis-prologue.json (mounted at /config/cratis-prologue.json, or wherever PROLOGUE_CONFIG points) is optional in batch mode — it’s only needed to configure LLM refinement, since the capture folder and output paths are already explicit.

Run service mode

Service mode embeds an Orleans silo and hosts interpretation as resumable session grains over HTTP, with state persisted in MongoDB:

docker run --rm -p 5004:5004 \
  -e PROLOGUE_MODE=service \
  -v "$(pwd)/cratis-prologue.json:/config/cratis-prologue.json:ro" \
  cratis/prologue-interpreter

(--serve on the binary is equivalent to PROLOGUE_MODE=service on the container.) Three more environment variables shape service mode’s lifecycle:

Environment variable	Default	Meaning
PROLOGUE_SERVICE_PORT	5004	The HTTP API port
PROLOGUE_GRACE_PERIOD	300 seconds	How long a session waits for an answer to a clarifying question before the container is allowed to exit
PROLOGUE_IDLE_TIMEOUT	600 seconds	How long an idle session waits before the container is allowed to exit

When the grace period or idle timeout elapses, the container exits cleanly. An orchestrator can restart it and resume the session from its last MongoDB-backed checkpoint.

Service mode does not write the batch output files. After a session completes, GET /sessions/{prologueId}/result returns a SessionResult containing the ExtractionResult and generated Screenplay source. Use batch mode when you need file-based input and output.

Configure LLM refinement

Add an llm section to cratis-prologue.json to have the Interpreter rename the heuristic model into domain language and derive a system name, instead of stopping at mechanical names:

cratis-prologue.json (excerpt)

{
    "llm": {
        "enabled": true,
        "kind": "Anthropic",
        "accessToken": "sk-...",
        "modelId": "claude-opus-4-6"
    }
}

kind is one of Ollama (the default, a local model over its native chat API — no accessToken needed), OpenAI, AzureOpenAI (where modelId is the deployment name, not a model name), OpenAICompatible (any /v1-compatible endpoint — set endpoint explicitly), or Anthropic. The hosted providers default to their public endpoint; override it with endpoint for a private or self-hosted deployment.

With refinement enabled, service mode can return clarification questions through its session API and resume after answers are submitted. Batch mode sets the question limit to zero and finalizes without asking questions. In both modes, refinement changes names and descriptions around the heuristic candidate; review the resulting structure before relying on it.

Note

The Cratis CLI’s cratis prologue interpret wraps batch mode with the same configuration precedence and prints the same result — use it if you’d rather not hand-roll docker run for every capture folder.

Next

• Reference — Extraction result — the full shape of what gets written.
• Validate and review the generated .play file before using it with a supported Screenplay runtime.