# AgentMesh — Agent Coordination Runtime

## What This Project Is
AgentMesh is a middleware runtime for multi-agent AI systems. It sits between agent frameworks (LangGraph, CrewAI) and observability tools (LangSmith, Braintrust) to handle:
1. **Intelligent task routing** — cost/latency/capability-aware model selection per sub-task
2. **Stateful handoff management** — context preservation across agent boundaries with checkpointing
3. **Real-time failure detection** — anomaly detection on execution graphs with automatic recovery

## Tech Stack
- **Language:** Python 3.11+
- **Package manager:** uv (preferred) or pip
- **Async:** asyncio throughout — all public APIs must be async
- **State store:** Redis (hot state), SQLite (durable checkpoints, local dev), Postgres (production)
- **Testing:** pytest + pytest-asyncio
- **Linting:** ruff
- **Type checking:** pyright in strict mode
- **Docs:** mkdocs-material

## Project Structure
```
agentmesh/
├── src/agentmesh/
│   ├── __init__.py
│   ├── core/              # Core runtime: router, state manager, failure detector
│   │   ├── router.py      # Task routing engine
│   │   ├── state.py       # State/checkpoint management
│   │   ├── detector.py    # Failure/anomaly detection
│   │   └── runtime.py     # Main runtime orchestrator
│   ├── adapters/           # Framework integrations
│   │   ├── langgraph.py
│   │   └── crewai.py
│   ├── providers/          # LLM provider connectors
│   │   ├── base.py
│   │   ├── anthropic.py
│   │   ├── openai.py
│   │   └── openrouter.py
│   ├── store/              # State storage backends
│   │   ├── redis.py
│   │   ├── sqlite.py
│   │   └── memory.py      # In-memory store for testing
│   ├── dashboard/          # CLI + basic web dashboard
│   └── config.py           # Configuration management
├── tests/
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── examples/               # Example integrations
├── docs/
├── pyproject.toml
├── CLAUDE.md
└── README.md
```

## Commands
- `uv run pytest` — run all tests
- `uv run pytest tests/unit` — unit tests only
- `uv run ruff check src/` — lint
- `uv run ruff format src/` — format
- `uv run pyright src/` — type check
- `uv run mkdocs serve` — local docs

## Conventions
- All public functions and classes have docstrings (Google style)
- Use `typing` annotations everywhere — no `Any` unless truly necessary
- Error handling: custom exception hierarchy rooted in `AgentMeshError`
- Logging via `structlog` — structured JSON logs, no print statements
- Config via pydantic-settings with env var support (AGENTMESH_ prefix)
- All state operations are idempotent and safe under concurrent access
- Router decisions are logged with full context for later ML training
- Test coverage target: 80%+ on core/, 60%+ on adapters/

## Architecture Principles
- **Framework-agnostic:** AgentMesh wraps existing frameworks, never replaces them
- **Minimal integration surface:** Adding AgentMesh to an existing project should require <20 lines of code
- **Fail-open by default:** If AgentMesh is unavailable, agents fall back to direct execution
- **Data gravity:** Every routing decision and handoff is logged — this data trains the learned router (Stage 2)

## What NOT To Do
- Don't import framework-specific code (langgraph, crewai) in core/ — adapters only
- Don't use synchronous blocking calls in async code paths
- Don't store secrets in code — use env vars or config files
- Don't add dependencies without checking: is there a lighter alternative?
