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

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: ten 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.