Examples

Every script under examples/ is runnable as-is: uv run python examples/<name>.py.

Core

Script	Demonstrates
`success.py`	Minimal `story()`/`stage()` API, no decorators, a success path
`basic.py`	`@runtime_narrative_story`/`@runtime_narrative_stage` decorators, a failure path
`basic_ollama.py`	Same failure path with `OllamaFailureAnalyzer` attached

Sub-stories and logging (newest features)

Script	Demonstrates
`substory_db_call.py`	Nested `story()` auto-linking as a sub-story (API call → DB call)
`logging_bridge.py`	`NarrativeLogHandler` folding `logging` calls into the story pipeline
`structured_log_routing.py`	`extra=` fields, `level_icons`, and `FilteredRenderer` per-story-family routing

Auto-instrumentation

Script	Demonstrates
`narrative_class.py`	`@narrative_class` and `@no_stage`
`instrument_module.py`	`instrument_module()` on an existing module
`auto_instrument.py`	`auto_instrument()` import-hook, zero call-site changes

Failure diagnostics and analysis

Script	Demonstrates
`diagnostics_config.py`	`FailureDiagnosticsConfig` — rich mode, redaction, production caps
`background_analysis.py`	`background_analysis=True` — non-blocking LLM analysis
`anthropic_analyzer.py`	`AnthropicFailureAnalyzer` + `DeduplicatingAnalyzer`

Renderers and observability

Script	Demonstrates
`html_report.py`	`HtmlReportRenderer` — self-contained HTML report
`sqlite_persistence.py`	`SqliteStoryRenderer` + the `runtime-narrative` CLI
`otel_tracing.py`	`OtelRenderer`, `OtelLogRenderer`, `OtelMetricsRenderer`
`alert_routing.py`	`AlertRoutingRenderer` — async webhook fan-out
`colorful_errors_and_emojis.py`	`ConsoleRenderer`'s built-in color + `level_icons` emoji across log levels and a failure

Framework integrations and concurrency

Script	Demonstrates
`middleware_skip_if.py`	`RuntimeNarrativeMiddleware(skip_if=...)` for FastAPI/Starlette
`task_group.py`	`NarrativeTaskGroup` — concurrent asyncio tasks under one story
`fastapi_app/`	Full FastAPI demo app (`uv run python -m examples.fastapi_app.run`)
`fastapi_ugly_traceback_demo.py`	The same deep async bug (route → orchestrator → retry-wrapped pricing engine → `asyncio.gather` fan-out → the actual TypeError), run once with no instrumentation and once with runtime-narrative — a raw ~35-frame traceback vs. one pinpointed line, source snippet, and locals

Testing and lifecycle utilities

Script	Demonstrates
`story_recorder.py`	`StoryRecorder` test assertion API
`dry_run_mode.py`	`dry_run=True` — verify wiring with no side effects
`optional_stage.py`	`has_active_story()` and `stage(optional=True)`
`saga_record_failure.py`	`StoryRuntime.record_failure()` in a saga/rollback flow
`stage_story_name.py`	`story_name` on `StageStarted`/`StageCompleted`

Start from the top

New to runtime-narrative? Head back to the homepage for the overview, or Installation to get the package into your project and start wrapping code in story().