Metadata-Version: 2.4
Name: modelmri
Version: 0.1.0
Summary: Chrome DevTools for AI models and agents — see attention, features, and agent steps inside any local model.
Project-URL: Homepage, https://github.com/muhammadmahadazher/ModelMRI
Project-URL: Repository, https://github.com/muhammadmahadazher/ModelMRI
Author-email: Muhammad Mahad Azher <mahadazher@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,debugging,devtools,interpretability,llm,sparse-autoencoder
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: accelerate>=1.2
Requires-Dist: fastapi>=0.115
Requires-Dist: pydantic>=2.9
Requires-Dist: torch>=2.5
Requires-Dist: transformers>=4.48
Requires-Dist: uvicorn[standard]>=0.32
Description-Content-Type: text/markdown

# ModelMRI

**Chrome DevTools for AI models and agents.** Load any local model — LLM, VLM, or robot policy — and see inside it while it runs: attention, features, circuits, agent steps. Local-first. MIT.

> 🚧 **Under active construction, in public.** v0.1 (live attention playground) ships in ~2 weeks.
> Follow the build: [Substack](https://modelmri.substack.com)

## Why

When a model gives a wrong answer, you can't see why. When an agent fails at step 47, you get a wall of logs. When a robot policy drops the object, you get nothing. The research tools that *can* see inside (SAEs, attention analysis, circuit tracing) live in notebooks only specialists can drive.

ModelMRI packages that research into a tool with the ergonomics of browser DevTools: one-line install, open `localhost:5900`, look inside.

## Planned (the 12-week public roadmap)

- **v0.1** — load a HuggingFace LLM, watch attention flow live at 60fps (WebGL)
- **v0.2** — SAE feature browser: see the *concepts* inside the model, steer them
- **v0.3** — agent mode: record any Anthropic-SDK/Claude-Code agent run, replay it, find the failing step
- **v0.4** — the first interactive tool for looking inside a robot policy (SmolVLA + LeRobot)
- **v0.5** — polish, zero-install hosted demo, launch

## Install

```bash
pip install modelmri
modelmri serve               # then open http://localhost:5900
```

Or from source (dev):

```bash
git clone https://github.com/muhammadmahadazher/ModelMRI && cd ModelMRI
cd frontend && npm install && npm run build && cd ..
uv sync
uv run modelmri serve
```

Click **Load Qwen2.5-0.5B-Instruct** (~1 GB one-time download), type a prompt, watch tokens stream — then hover any token to see what the model attended to.

## Status

| Piece | State |
|---|---|
| FastAPI backend: model loading, REST, WebSocket token streaming | ✅ working |
| Built-in playground page (temporary, pre-React) | ✅ working |
| **Attention inspector: hover any token, see what it attended to** | ✅ working |
| SAE feature browser | 🏗️ next |
| Frontend (React + WebGL) | 🏗️ next |
| `pip install modelmri` | placeholder published (real release at v0.1) |

MIT © Muhammad Mahad Azher
