Installation

The core package has no required dependencies beyond the Python standard library and python-dotenv. Everything else — colored terminal output, framework middleware, observability backends, LLM analysis — is an opt-in extra.

Install the core package

bash

pip install runtime-narrative

That's enough to use story(), stage(), decorators, auto-instrumentation, diagnostics, and the built-in JsonRenderer and SqliteStoryRenderer. ConsoleRenderer — the default renderer — works too, falling back to plain print when the console extra isn't installed.

Install with an extra

Extras unlock additional renderers, analyzers, and framework integrations. Install one at a time:

bash

pip install "runtime-narrative[console]"    # colored terminal output
pip install "runtime-narrative[fastapi]"    # FastAPI / Starlette middleware
pip install "runtime-narrative[anthropic]"  # Anthropic Claude failure analysis
pip install "runtime-narrative[all]"        # everything

Or combine several in one install:

bash

pip install "runtime-narrative[console,fastapi,otel]"

Extras reference

Extra	Installs	Use for
`console`	`typer>=0.9.0`	Colored, bold terminal output via `ConsoleRenderer`
`fastapi`	`starlette>=0.27.0`	`RuntimeNarrativeMiddleware` for FastAPI / Starlette
`otel`	`opentelemetry-api`, `opentelemetry-sdk`	`OtelRenderer`, `OtelLogRenderer`, `OtelMetricsRenderer`
`prometheus`	`prometheus-client>=0.19.0`	`PrometheusRenderer` for Prometheus metrics
`anthropic`	`anthropic>=0.25.0`	`AnthropicFailureAnalyzer` via the Claude API
`django`	`django>=3.2`	`RuntimeNarrativeDjangoMiddleware` (ASGI + WSGI)
`celery`	`celery>=5.0`	`NarrativeTask` base class and `connect_narrative`
`grpc`	`grpcio>=1.50.0`	`RuntimeNarrativeInterceptor` and its async variant
`structlog`	`structlog>=25.5.0`	Richer default `ConsoleRenderer` style for captured `LogRecorded` events
`all`	everything above	Kitchen-sink install for development

Missing extras fail loudly, not silently

If you import a renderer or middleware whose extra isn't installed, you get a clear ImportError naming the missing package — not a degraded runtime behavior. RuntimeNarrativeMiddleware itself is conditionally imported at the package level, so it's silently absent (not an error) only when starlette truly isn't installed and you never reference it.

With uv

If your project uses uv:

bash

uv add runtime-narrative
uv add "runtime-narrative[console,fastapi]"
uv sync --group dev   # includes test and build tools, for contributing to the library itself

Python compatibility

Python 3.9+. NarrativeTaskGroup (async task groups) requires no additional dependencies and does not depend on Python 3.11's asyncio.TaskGroup. Type hints use from __future__ import annotations throughout for compatibility with older typing syntax.

Verify the install

python

import runtime_narrative
print(runtime_narrative.__version__)

Next step

Head to Quick Start to wrap your first block of code in a story(), or read Core Concepts first for the mental model behind stories, stages, events, and renderers.