Turn any Python execution into a
traceable story
Minimal logs when everything works. Surgical, LLM-powered diagnostics the moment something breaks. No restructuring of existing code required.
Built for how engineers already talk about failures
"We ran Import Customers, it loaded the CSV, validated the rows, then failed during Insert Records." That's exactly what the library captures — automatically.
story() / stage() are dual sync/async context managers — or decorators, or auto-instrumentation. No restructuring needed.
Nest a story() inside an active one and it auto-links as a traceable child with its own success/failure and duration — no new API.
A compressed stack summary and exact failure frame always; local-variable capture with automatic secret redaction only when you ask.
Ollama, any OpenAI-compatible endpoint, or Anthropic Claude turns a traceback into an exact-cause explanation and a targeted fix.
Any object with handle(event) is a renderer; any object with analyze_failure(...) is an analyzer.
Console, JSON, SQLite, OpenTelemetry, Prometheus, HTML, webhooks, FastAPI, Django, Celery, gRPC — all built in.
Install, then wrap your code
The core package has no required dependencies beyond the standard library and python-dotenv.
pip install runtime-narrativepip install "runtime-narrative[console,fastapi,anthropic]"from runtime_narrative import story, stage
with story("Import Customers"):
with stage("Load CSV"):
rows = load_csv("customers.csv")
with stage("Validate Data"):
validate(rows)
with stage("Insert Records"):
db.insert(rows)Everything works the same way everywhere
Sync/async, decorators, auto-instrumentation, any framework middleware — one line here, full detail in the docs.
@runtime_narrative_story / @runtime_narrative_stage — wrap functions without restructuring call sites.
@narrative_class, instrument_module(), auto_instrument() — zero call-site changes.
Lean/rich modes, production traceback caps, secret redaction, FailureDiagnosticsConfig.
Console, JSON, SQLite, OpenTelemetry, Prometheus, HTML reports, webhook alert routing.
FastAPI/Starlette middleware, Django ASGI/WSGI, Celery task base class, gRPC interceptors.
NarrativeTaskGroup — concurrent asyncio tasks under one shared story.
SqliteStoryRenderer plus runtime-narrative failures / story <id>.
StoryRecorder — a dual sync/async assertion API that produces no output.
End-to-end call tracing, plus folding existing logging calls into one event stream.
Ready to see it fail on purpose?
Every example in the docs is a runnable script. Start with the Quick Start, or jump straight to the full API reference.