Metadata-Version: 2.4
Name: agentlens-server
Version: 0.1.0
Summary: AgentLens observability server for AI agents
Project-URL: Homepage, https://github.com/ArkFelix7/agentlens
Project-URL: Repository, https://github.com/ArkFelix7/agentlens
Project-URL: Bug Tracker, https://github.com/ArkFelix7/agentlens/issues
Author: AgentLens Contributors
License: MIT
Keywords: agents,ai,fastapi,llm,observability,server,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: python-ulid>=2.7.0
Requires-Dist: sentence-transformers>=3.1.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.35
Requires-Dist: uvicorn[standard]>=0.30.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: httpx-ws>=0.6.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# agentlens-server

FastAPI backend for [AgentLens](https://github.com/ArkFelix7/agentlens) — real-time observability for AI agents.

## Install

```bash
pip install agentlens-server
```

## Run

```bash
agentlens-server
# REST API: http://localhost:8766/api/v1
# WebSocket: ws://localhost:8766/ws
# Dashboard: http://localhost:5173 (start separately)
```

## Run from source

```bash
git clone https://github.com/ArkFelix7/agentlens
cd agentlens
make install && make dev
```

## API Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/sessions` | List all sessions |
| GET | `/api/v1/traces/{session_id}` | Get all trace events for a session |
| POST | `/api/v1/traces/{session_id}` | Ingest trace events |
| GET | `/api/v1/costs/{session_id}` | Cost breakdown |
| GET | `/api/v1/hallucinations/{session_id}` | Hallucination alerts |
| POST | `/api/v1/hallucinations/{session_id}/detect` | Run detection |
| GET | `/api/v1/memory/{session_id}` | Memory entries |
| PATCH | `/api/v1/memory/entry/{id}` | Edit memory entry |
| DELETE | `/api/v1/memory/entry/{id}` | Delete memory entry |
| GET | `/api/v1/replay/{session_id}` | Replay event stream |
| GET | `/health` | Health check |

## WebSocket Protocol

Connect to `ws://localhost:8766/ws` and send a hello message:

```json
{ "type": "hello", "role": "sdk" }
```

Roles: `"sdk"` (agent sending events) or `"dashboard"` (browser receiving events).

## Configuration

Environment variables (all optional):

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABASE_URL` | `sqlite+aiosqlite:///agentlens.db` | Database URL |
| `HOST` | `0.0.0.0` | Bind address |
| `PORT` | `8766` | Port |
| `CORS_ORIGINS` | `["*"]` | Allowed CORS origins |

## License

MIT
