# TOMAPE

Token-optimized multi-agent orchestration exposed as an MCP server. TOMAPE owns session state, compacts context between agent hops, routes work to smaller models when safe, and reports estimated token savings.

## Features

- **Session-owning orchestrator** — clients send tasks, not full transcripts
- **Context compaction** — structured handoff state between planner/worker/reviewer hops (typically 3–5× compression)
- **Dynamic routing** — rule-based small/large model selection with escalation
- **Token metrics** — per-hop breakdown and estimated baseline savings
- **Dual transport** — stdio (Cursor/Claude Desktop) and HTTP (hosted teams)
- **API key auth** — Bearer token authentication for HTTP mode
- **MCP resources** — inspect handoff state and hop logs per session

## Quick Start

> Full walkthrough: **[docs/SETUP.md](docs/SETUP.md)**

### Prerequisites

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) (recommended)

### Install

```bash
git clone https://github.com/sudharsanbabu83/TOMAPE.git
cd TOMAPE
uv sync --extra dev
cp .env.example .env
uv run tomape init-db
```

Add your LLM API key to `.env` (see [Model configuration](#model-configuration)).

### Run locally (mock — no API key)

```powershell
# Windows PowerShell
$env:TOMAPE_MOCK_LLM="1"; uv run tomape serve --transport stdio
```

```bash
# macOS / Linux
TOMAPE_MOCK_LLM=1 uv run tomape serve --transport stdio
```

### Run locally (live LLM)

```bash
uv run tomape serve --transport stdio
```

### Run (HTTP — hosted)

```bash
uv run tomape serve --transport http --port 8080
```

Health check: `GET http://localhost:8080/health`

## Cursor MCP Setup

1. Copy an example config into your project:

   | Platform | Template |
   |----------|----------|
   | macOS / Linux | [`examples/cursor-mcp.json`](examples/cursor-mcp.json) |
   | Windows | [`examples/cursor-mcp.windows.json`](examples/cursor-mcp.windows.json) |

   ```bash
   mkdir -p .cursor
   cp examples/cursor-mcp.json .cursor/mcp.json   # adjust for your OS
   ```

2. Edit `.cursor/mcp.json`:
   - Set `cwd` to your TOMAPE repo root (required so config and `.env` load)
   - Add `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` in `env`
   - On Windows, use the full path to `uv.exe` if `uv` is not on PATH

3. Restart Cursor and confirm the `tomape` MCP server is connected.

### Example config (macOS / Linux)

```json
{
  "mcpServers": {
    "tomape": {
      "command": "uv",
      "args": ["run", "tomape", "serve", "--transport", "stdio"],
      "cwd": "/path/to/TOMAPE",
      "env": {
        "OPENAI_API_KEY": "your-key",
        "TOMAPE_MOCK_LLM": "0"
      }
    }
  }
}
```

## MCP Tools

| Tool | Description |
|------|-------------|
| `submit_task` | Start a session (`task`, `constraints`, `budget_tokens`, `profile`, `compaction_policy`) |
| `continue_session` | Follow-up without resending history |
| `get_session_status` | Poll running/completed/failed status |
| `get_result` | Final output + `token_report` |
| `cancel_session` | Abort a session |
| `get_token_report` | Token metrics and savings |

### MCP Resources

| Resource | Description |
|----------|-------------|
| `session://{session_id}/handoff` | Current compact handoff JSON |
| `session://{session_id}/logs` | Truncated raw output per hop |

### Example prompts (in Cursor)

```
Use TOMAPE submit_task: summarize the benefits of context compaction. Budget 5000 tokens. Profile economy.
```

```
Use TOMAPE get_result for session sess_abc123
```

### Token report

`get_result` and `get_token_report` return a `token_report` with:

- `total_tokens` — tokens used in the session
- `budget_tokens` — session cap
- `estimated_baseline` — estimated cost without compaction
- `savings_percent` — reduction vs baseline
- `hops[]` — per-hop model, tokens, and `compaction_ratio`

## HTTP API

Authenticate with `Authorization: Bearer <api-key>`.

```bash
# List tools
curl -H "Authorization: Bearer dev-key-change-me" http://localhost:8080/tools

# Submit task
curl -X POST http://localhost:8080/tools/call \
  -H "Authorization: Bearer dev-key-change-me" \
  -H "Content-Type: application/json" \
  -d '{"name":"submit_task","arguments":{"task":"Classify these items: apple, car, dog","profile":"economy","budget_tokens":5000}}'
```

## Docker

```bash
cd docker
TOMAPE_API_KEYS=dev-key-change-me OPENAI_API_KEY=sk-... docker compose up --build
```

## Configuration

- Environment: [`.env.example`](.env.example)
- Policies: [`config/default.yaml`](config/default.yaml)

### Model configuration

Default models (OpenAI via LiteLLM):

| Tier | Model |
|------|-------|
| small | `openai/gpt-4o-mini` |
| large | `openai/gpt-4o` |

Switch to Anthropic or any LiteLLM-supported provider by editing `config/default.yaml` and setting the matching API key in `.env`.

### Profiles

| Profile | Behavior |
|---------|----------|
| `economy` | Small models, aggressive compaction, no escalation |
| `balanced` | Small default, escalate on failure |
| `quality` | Large models, light compaction |

### Compaction policies

| Policy | Best for |
|--------|----------|
| `default` | General tasks |
| `code-agent` | Coding, file edits, test output |
| `research-agent` | Search, sources, key findings |

## Development

```bash
uv run pytest
uv run ruff check tomape tests
```

Set `TOMAPE_MOCK_LLM=1` to run without API keys.

## Architecture

```
Client → MCP (stdio/HTTP) → Orchestrator → Router → LLM
                              ↓
                         Compaction → Session Store → Metrics
```

Internal agents: **Planner** → **Worker** (per step) → **Reviewer**

## License

MIT