Add example profiles, schemas, and an end-to-end local fixture

README.md

@@ -1,25 +1,102 @@
 # scriptorium
 
-Scriptorium is a prompt-profile execution engine written in Go.
+Scriptorium (Analyzer) is a generic prompt-profile execution engine written in Go.
 
-Current implementation scope:
-- domain model and core interfaces
-- YAML-backed prompt profile loading
-- inline and file artifact reading
-- provider-neutral prompt rendering
+It loads a prompt profile, resolves named input artifacts, renders a prompt, calls an OpenAI-compatible LLM endpoint, validates output, and returns an artifact plus metadata.
 
-## Local CLI usage
+## Relationship to Narratio
 
-Run a profile locally against an OpenAI-compatible endpoint:
+In the broader workflow, Narratio handles pipeline orchestration (transcription, cleanup, storage, notifications). Scriptorium handles only prompt-profile execution for a single run.
+
+## Repository Example Assets
+
+- Profiles: `profiles/`
+- Schemas: `schemas/`
+- Tiny fixtures: `examples/fixtures/`
+
+Included profiles:
+- `generic.markdown_summary`
+- `dnd.session_recap` (example content only; no D&D-specific Go logic)
+- `generic.structured_events` (JSON + JSON Schema validation)
+
+## Run a Local Profile (CLI)
 
 ```bash
 go run ./cmd/scriptorium run \
   --profile-dir ./profiles \
-  --profile-id recap \
-  --input transcript=./testdata/transcript.md \
-  --input glossary=./testdata/glossary.yml \
-  --var session_date=2026-05-04 \
+  --profile-id generic.markdown_summary \
+  --input transcript=./examples/fixtures/transcript.md \
+  --input glossary=./examples/fixtures/glossary.yml \
   --llm-base-url http://localhost:8000/v1 \
   --model gpt-4o-mini \
   --out ./out.md
 ```
+
+For schema-validated JSON output:
+
+```bash
+go run ./cmd/scriptorium run \
+  --profile-dir ./profiles \
+  --profile-id generic.structured_events \
+  --input transcript=./examples/fixtures/transcript.md \
+  --input glossary=./examples/fixtures/glossary.yml \
+  --llm-base-url http://localhost:8000/v1 \
+  --model gpt-4o-mini \
+  --schema-dir ./schemas \
+  --out ./events.json
+```
+
+## Start Local HTTP API
+
+```bash
+go run ./cmd/scriptorium serve \
+  --addr :8080 \
+  --profile-dir ./profiles \
+  --schema-dir ./schemas \
+  --llm-base-url http://localhost:8000/v1 \
+  --model gpt-4o-mini
+```
+
+## Call `POST /v1/runs`
+
+```bash
+curl -sS http://localhost:8080/v1/runs \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "profile_id": "generic.structured_events",
+    "inputs": {
+      "transcript": {"type": "file", "uri": "./examples/fixtures/transcript.md"},
+      "glossary": {"type": "file", "uri": "./examples/fixtures/glossary.yml"}
+    },
+    "model": {"model": "gpt-4o-mini"}
+  }'
+```
+
+Response shape:
+- `artifact`
+- `validation`
+- `metadata`
+- `raw_model_output`
+
+## Add a New Prompt Profile
+
+1. Add a YAML file under `profiles/` with:
+   - `id`, `version`, `expected_inputs`, `templates`, `model_defaults`, `output_format`, `validation`
+2. Use template helpers such as `{{input "transcript"}}`.
+3. For structured JSON output, set:
+   - `output_format: json`
+   - `validation.validation_mode: json_schema`
+   - `validation.schema_path: <schema file>`
+4. Place schema files in `schemas/` and pass `--schema-dir ./schemas` for CLI/serve.
+
+## Validation Behavior
+
+Validation modes currently implemented:
+- `none`
+- `basic` (non-empty output)
+- `json` (must parse as JSON)
+- `json_schema` (must parse JSON and satisfy schema)
+
+Important behavior:
+- Validation content failures are returned as structured run results (`validation.status = failed`) and preserve `raw_model_output`.
+- Validation runtime/configuration failures are treated as run errors.