AI Agent Based Travel Assistant Claude API + MCP

What exists here

| Piece | File | What it does |
|---|---|---|
| Sandbox data layer | `src/tp_mcp/sandbox.py` | Loads TravelPlanner queries, parses `reference_information` into per-city sections |
| **MCP server** | `src/tp_mcp/server.py` | Exposes the sandbox as MCP tools over stdio |
| **Agent loop** | `src/agent/loop.py` | Claude tool-use loop driving the MCP session |
| Prompts | `src/agent/prompts.py` | Versioned system prompts (planner, sole-planning, chat) |
| Plan schema | `src/agent/schema.py` | Pydantic contract matching the benchmark's plan format |
| **Evaluator** | `src/eval/constraints.py` | Commonsense + hard constraint checks, benchmark-style metrics |
| Batch runner | `src/eval/run_eval.py` | Runs N queries, writes traces + a metrics summary |
| UI | `src/ui/app.py` | Streamlit chat for participant testing |
| Tests | `tests/test_constraints.py` | 9 offline tests, no API key needed |

## Setup (30 minutes)

```bash
python -m venv .venv
source .venv/bin/activate          # Windows cmd:  .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env 
python scripts/prepare_data.py

pytest -q                          # 9 tests, no API calls
python scripts/check_setup.py      # key, dataset, MCP server, one API call
```

Then, first real run. Use `run.py` and everything works the same on every
platform -- no PYTHONPATH to set:

```bash
python run.py eval.run_eval --mode sole-planning --n 5 --level easy   # cheap, ~1 min
python run.py agent.loop 0                    # one agentic run, prints the full trace
python run.py eval.run_eval --mode tool-use --n 5 --level easy
streamlit run src/ui/app.py
```

 Architecture

```
  Streamlit UI ──┐
                 ├──► agent/loop.py ──── Anthropic Messages API (Claude)
  eval runner ───┘         │                      ▲
                           │  tool_use blocks     │  tool_result blocks
                           ▼                      │
                    MCP ClientSession ────────────┘
                           │  stdio (JSON-RPC)
                           ▼
                    tp_mcp/server.py  (FastMCP)
                           │
                           ▼
              TravelPlanner sandbox (reference_information / CSV database)
```