Metadata-Version: 2.4
Name: mirrorkit
Version: 0.1.0
Summary: Mirrors: build a high-fidelity simulation of a production environment from traces (and optional LangGraph code) to run and test agents with no external dependencies.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.1
Requires-Dist: litellm>=1.65.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: backends
Requires-Dist: localstripe>=1.15; extra == "backends"
Requires-Dist: aiosmtpd>=1.4; extra == "backends"
Requires-Dist: requests>=2.31; extra == "backends"
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == "langgraph"
Requires-Dist: langchain-core>=0.3; extra == "langgraph"
Requires-Dist: langchain-anthropic>=0.2; extra == "langgraph"
Provides-Extra: serve
Requires-Dist: fastapi>=0.110; extra == "serve"
Requires-Dist: uvicorn>=0.29; extra == "serve"
Requires-Dist: httpx>=0.27; extra == "serve"
Provides-Extra: backend
Requires-Dist: fastapi>=0.110; extra == "backend"
Requires-Dist: uvicorn>=0.29; extra == "backend"
Requires-Dist: httpx>=0.27; extra == "backend"
Requires-Dist: sqlalchemy>=2.0; extra == "backend"
Requires-Dist: psycopg[binary]>=3.1; extra == "backend"
Requires-Dist: pydantic-settings>=2.0; extra == "backend"
Requires-Dist: python-multipart>=0.0.9; extra == "backend"
Requires-Dist: boto3>=1.34; extra == "backend"
Requires-Dist: pyjwt[crypto]>=2.8; extra == "backend"
Requires-Dist: stripe>=9.0; extra == "backend"

# Mirrors
 
Build a runnable simulation of a customer's production agent environment from
their traces, then browse its assets, run evals, and play with it — all in a web
app. This monorepo holds **four independently-hostable parts**:  

```
┌─────────────┐   collect (Bearer key)   ┌──────────────────────────┐
│  collector/ │ ───────────────────────► │        backend/          │
│ (customer's │                          │  control-plane API       │ ──► Postgres
│   machine)  │                          │  (routing, orchestration)│ ──► ECS Fargate envs
└─────────────┘                          └───────────▲──────────────┘     (built on mirrorkit/)
                                                      │ REST (one origin)
                                          ┌───────────┴──────────────┐
                                          │        frontend/         │  (Vercel)
                                          └──────────────────────────┘
```

| Part | Dir | What it is | Hosted on |
|---|---|---|---|
| **Frontend** | `frontend/` | React + Vite app — Dashboard, Ingest, Simulation, Evals, Playground | **Vercel** | 
| **Backend** | `backend/` | FastAPI control plane: routing, env registry, Fargate orchestration, evals/playground, setup assistant, collector ingest. Depends on core `mirrorkit`. | **EC2** + external **Postgres** |
| **Core engine** | `mirrorkit/` | The simulation engine the backend runs: traces → schema + seed + tool bindings → a runnable Environment; serve + package it. See `mirrorkit/README.md`. | inside each **env container** |
| **Collector** | `collector/` | A 2-line, zero-dependency SDK that streams an agent's production traces to the backend. See `collector/README.md`. | **customer's machine** |

## The collector (2 lines)

```python
import mirror
mirror.init(api_key="mk_live_...", project="my-agent")
```

Auto-instruments LangChain/LangGraph, Anthropic, and OpenAI if present; captures
each run's messages + tool calls and ships them in the background (negligible
overhead, never raises into your app).

## Run it locally

```bash
# backend (SQLite for local; or point MIRROR_DATABASE_URL at any Postgres)
MIRROR_DATABASE_URL=sqlite:///data/mirror.db \
  uvicorn backend.app:create_app --factory --port 8001

python examples/seed_demo.py              # register the airline demo env
cd frontend && npm install && npm run dev # http://localhost:5173
```

The airline demo (agent + traces + seed) lives in `examples/`. For real
(non-mock) data, set `ANTHROPIC_API_KEY` + `MIRROR_SIM_MODEL` +
`MIRROR_BUILD_MODEL` (see `backend/.env.example`).

## Deploy

`DEPLOY.md` — backend on **EC2** + an **external Postgres**, **ECS Fargate** for
the per-customer env containers, **Vercel** for the frontend. `SWITCH.md` is the
architecture deep-dive.

## Develop / test

```bash
pip install -e ".[backend,langgraph,serve,backends,dev]"   # core + backend
pip install -e collector                                    # the SDK
pytest -q                  # core + backend tests
pytest collector/tests -q  # collector tests
```

## Install profiles

- Core engine only: `pip install -e .` (extras: `serve`, `langgraph`, `backends`).
- Backend (adds the control plane): `pip install -e ".[backend,langgraph]"`.
- Collector: `pip install -e collector` (zero required deps).
