Metadata-Version: 2.4
Name: statelens-ai
Version: 0.1.0
Summary: Chrome DevTools for AI Agents — one install, full debugging experience
Project-URL: Homepage, https://github.com/0xkaushal/StateLens
Project-URL: Repository, https://github.com/0xkaushal/StateLens
Project-URL: Issues, https://github.com/0xkaushal/StateLens/issues
Author: Satvik Kaushal
License: MIT
Keywords: agents,ai,debugging,devtools,langgraph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Debuggers
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.111.0
Requires-Dist: pydantic>=2.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: langgraph
Requires-Dist: langchain-core>=0.3.0; extra == 'langgraph'
Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
Description-Content-Type: text/markdown

# StateLens

> **Chrome DevTools for AI Agents**

StateLens is a local-first debugging workspace for AI applications. Inspect every node, state transition, tool call, prompt, and execution path in your LangGraph agents.

---

## Quick Start

### 1. Install the SDK

```bash
cd sdk
uv sync --extra langgraph
# or: pip install -e ".[langgraph]"
```

### 2. Instrument your graph

```python
from statelens import observe

app = graph.compile()
app = observe(app)  # ← one line, zero config

result = app.invoke({"messages": [...]})
```

### 3. Start the server

```bash
cd backend
uv sync
statelens-server
```

### 4. View your executions

Open [http://localhost:8000/conversations](http://localhost:8000/conversations)

---

## Architecture

```
SDK (writes)  →  SQLite (~/.statelens/statelens.db)  ←  Backend (reads)  →  Frontend (displays)
```

- **SDK** — instruments LangGraph via callbacks, writes events to SQLite
- **Backend** — FastAPI server, reads from the same SQLite, serves REST API
- **Frontend** — Next.js app (separate repo concern), consumes the REST API

---

## Project Structure

```
statelens/
├── contracts/      # Shared schemas and API contracts
├── sdk/            # Python SDK (statelens-sdk package)
├── backend/        # FastAPI server (statelens-server package)
├── frontend/       # Next.js UI (managed by OpenCode)
├── examples/       # Example LangGraph apps
└── docs/           # Documentation
```

---

## API Endpoints

| Method | Path                       | Description                  |
|--------|----------------------------|------------------------------|
| GET    | /health                    | Health check                 |
| GET    | /conversations             | List all conversations       |
| GET    | /conversations/{id}        | Get conversation with events |
| GET    | /events/{conversationId}   | Get events for a conversation|

---

## Configuration

| Env Variable        | Default                      | Description          |
|---------------------|------------------------------|----------------------|
| STATELENS_DB_PATH   | ~/.statelens/statelens.db    | SQLite database path |
| STATELENS_HOST      | 127.0.0.1                    | Server bind address  |
| STATELENS_PORT      | 8000                         | Server port          |

---

## License

MIT
