llm-refract

Provider-neutral Python instrumentation for AI systems, with an optional MCP interface.

Docs · Examples · Source · Issues

Instrument synchronous and asynchronous AI applications with provider-neutral events. Export portable .rfr files or submit snapshots to the Refract REST service. Record model calls, tools, retrieval, decisions, state changes, checkpoints and failures — then inspect, replay, fork and diff them.

Install

If Refract helps you, a GitHub star or feedback would be appreciated. The SDK prints this thank-you once per process when you create a run or service client with stderr connected to a terminal. Set REFRACT_NO_BANNER=1 to silence it.

pip install llm-refract

MCP support is an optional extra:

pip install "llm-refract[mcp]"

SDK usage

import refract

with refract.run("agent", path="run.rfr"):
    refract.event(type="generation", name="answer", output={"text": "Hello"})

Try python examples/python/basic/record.py after installing. Outputs go to .examples/.

See the Python usage guide for async patterns, redaction, failure capture and submitting to a remote endpoint.

MCP server

Executable stdio interface to the Rust Refract API: fourteen read-only tools, plus import/fork tools when REFRACT_MCP_ALLOW_WRITES=1. Requires the mcp extra above. Start with:

refract-mcp

See configuration, tool inventory and limits. Implementation: server.py.

Links

• Documentation
• TypeScript / npm SDK
• Rust CLI and engine
• Issues

License

Apache-2.0 — see LICENSE.

See provider coverage for Azure, Gemini/Vertex, Bedrock and custom model adapters, and production operation for reliable remote capture.

Use refract.instrument_litellm() with llm-refract[litellm] to observe LiteLLM module or Router calls. Provider documentation covers configuration, mock examples and nested-call deduplication.