mirrorkit 0.2.3

Mirrors client: a drop-in production trace collector for LLM agents, plus the `mirrors` CLI (install `mirrorkit[cli]`).

mirrorkit

A lightweight, drop-in production trace collector for LLM agents. Add two lines to your existing LangChain / LangGraph / Anthropic / OpenAI script and your agent's traces start streaming to your Mirrors backend — keyed by an API key, with negligible latency (non-blocking, background-batched).

Install

pip install mirrorkit

Zero required runtime dependencies — the sender uses only the Python stdlib. LangChain / Anthropic / OpenAI are instrumented only if they're importable.

Usage (2 lines)

import mirrorkit
mirrorkit.init(api_key="mk_live_...", project="my-agent")

That's it. Run your agent normally — traces are captured automatically and shipped in the background. The endpoint defaults to the MIRROR_ENDPOINT environment variable, then to the production URL.

mirrorkit.init(
    api_key="mk_live_...",
    project="my-agent",
    endpoint="https://api.mirror.dev",  # optional override
    flush_interval=2.0,                  # seconds between batch flushes
    max_batch=50,                        # max traces per POST
    instrument=True,                     # auto-hook LangChain/Anthropic/OpenAI
)

Manual logging

For frameworks you don't auto-instrument, enqueue a trace yourself. Messages are OpenAI-style chat dicts:

import mirrorkit
mirrorkit.init(api_key="mk_live_...", project="my-agent")

mirrorkit.log_trace(
    [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What's the weather in Paris?"},
        {
            "role": "assistant",
            "content": None,
            "tool_calls": [
                {
                    "id": "call_1",
                    "function": {"name": "get_weather", "arguments": '{"city": "Paris"}'},
                }
            ],
        },
        {"role": "tool", "tool_call_id": "call_1", "content": "18C, sunny"},
        {"role": "assistant", "content": "It's 18C and sunny in Paris."},
    ],
    trace_id="optional-id",
    model="gpt-4o",
)

mirrorkit.flush()  # also runs automatically at interpreter exit

LangChain global handler

init() registers a global LangChain callback handler automatically, so you don't need to pass callbacks. If your setup doesn't honor the global hook, pass the handler explicitly:

from langchain_core.runnables import RunnableConfig
import mirrorkit

mirrorkit.init(api_key="mk_live_...", project="my-agent")
chain.invoke(inputs, config=RunnableConfig(callbacks=[mirrorkit.handler()]))

API

• mirrorkit.init(api_key, project="default", endpoint=None, *, flush_interval=2.0, max_batch=50, instrument=True)
• mirrorkit.log_trace(messages, *, trace_id=None, model=None)
• mirrorkit.flush(timeout=5.0)
• mirrorkit.shutdown()
• mirrorkit.handler() — LangChain callback handler for manual registration

The mirrors CLI

The same package ships a terminal client of the hosted backend — the things you'd otherwise do in the web app (log in, ingest+build a twin, explore it, run evals). It needs a few extra deps, so install the cli extra:

pip install "mirrorkit[cli]"   # adds the `mirrors` command (click + httpx + pydantic)

Authenticate with a workspace API key (mk_live_…, minted in the web app), then:

mirrors login                              # paste the key (or --api-key / --dev)
mirrors env ls                             # list environments
mirrors build traces.jsonl --name airline  # ingest + build a twin (streams the log)
mirrors build --project airline --name airline   # build from a collector stream
mirrors env assets|schema|fidelity|traces <env>   # explore the twin
mirrors eval create <env> --name smoke --from cases.json
mirrors eval run <eval-set-id>             # run evals; `mirrors run show <run-id>`

Credentials live in ~/.mirrors/config.json (or MIRRORS_BASE_URL / MIRRORS_API_KEY for CI). Add --json to any command for machine-readable output. The CLI talks only HTTP to the backend — it has no engine/build logic of its own.

MCP server (drive Mirrors from an AI client)

The MCP server is now hosted by Mirrors — there's nothing to install from this package. Point any MCP client (Claude Desktop, Cursor, Claude Code, …) at the hosted endpoint and authenticate with a workspace API key, and it can build, inspect, and evaluate your mirrors with the same operations as the CLI (list_mirrors, get_schema, build_mirror, generate_eval_set, run_eval_set, and more — 15 tools).

{
  "mcpServers": {
    "mirrors": {
      "url": "https://mcp.runmirrors.com/mcp",
      "headers": { "Authorization": "Bearer mk_live_..." }
    }
  }
}

Mint a key in the Mirrors web app (Collector → API keys). Every request is scoped to that key's workspace. (This package ships only the trace collector and the optional mirrors CLI.)

Wire format

Batches are POSTed to {endpoint}/api/collect with Authorization: Bearer {api_key}:

{
  "project": "my-agent",
  "traces": [
    {"id": "abc", "model": "gpt-4o", "messages": [{"role": "user", "content": "hi"}]}
  ]
}

Failures (non-2xx / network errors) are retried a couple of times then dropped — the collector never raises into your program.