# Agent Task Planner

**Optimal, re-planning task selection for AI agents.** Give it candidate actions with a value
and a cost, a budget, and optional conflicts and prerequisites. It returns the provably best plan
and, as things happen, the single best next action. It works as a Claude Code plugin, as an MCP
server for any MCP-capable agent, or as a Python library.

Why this algorithm: it won a pre-registered benchmark against QAOA, Grover Adaptive Search,
simulated annealing and LP-guided sampling ([research report](docs/research-report.pdf)).
CP-SAT found the optimum of every test instance in under 1 ms. Re-planning after every event
added 14–28 % utility over a fixed plan, and quantum methods did not beat classical ones at
any size tested.

## Install

**Claude Code** (one step, Claude Code ≥ 2.1.275):

```
/plugin install agent-task-planner --marketplace maxkyliu/agent-task-planner
```

or in two steps:

```
/plugin marketplace add maxkyliu/agent-task-planner
/plugin install agent-task-planner@agent-task-planner
```

Requires [uv](https://docs.astral.sh/uv/) on your `PATH`; the plugin's MCP server runs with
`uv run`, which installs its Python dependencies on first start.

**Any MCP client** (Claude Desktop, other agents), stdio server:

```json
{
  "mcpServers": {
    "task-planner": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/maxkyliu/agent-task-planner", "agent-task-planner-mcp"]
    }
  }
}
```

**Python:**

```bash
uv add git+https://github.com/maxkyliu/agent-task-planner
```

```python
from agent_task_planner.planner import PlanRequest, select_tasks

plan = select_tasks(
    PlanRequest.model_validate(
        {
            "budget": 10,
            "tasks": [
                {"id": "retrieve", "utility": 5, "cost": 4},
                {"id": "verify", "utility": 3, "cost": 3},
                {"id": "deep_dive", "utility": 4, "cost": 5},
            ],
            "conflicts": [["retrieve", "deep_dive"]],
            "prerequisites": [{"task": "verify", "requires": "retrieve"}],
        }
    )
)
print(plan.execution_order, plan.total_utility, plan.optimal)  # ['retrieve', 'verify'] 8 True
```

## Tools

| Tool | Use it to | Key inputs | Returns |
|---|---|---|---|
| `plan_tasks` | plan once | `tasks`, `budget`, `conflicts`, `prerequisites` | `selected`, `execution_order`, totals, `optimal` |
| `plan_next_action` | adapt after each outcome | all known `tasks`, `remaining_budget`, `succeeded` / `failed` / `cancelled` | `action` to run now, the re-plan, `expected_utility` |
| `check_plan` | validate any proposed selection | `tasks`, `budget`, `selected` | `feasible`, `violations` |

The rules:
- **Integers only:** utilities, costs and budgets are non-negative integers, so scale fractions (for example ×100).
- **Conflicts** are pairs that cannot both run.
- **Prerequisites** mean "B only after A succeeded".
- **Fallback:** if CP-SAT hits its time limit, the best plan found is returned with `optimal: false`. If CP-SAT finds nothing in time, a feasible greedy plan is returned instead.

## The research behind it

The planner comes out of an 8-week, pre-registered study comparing classical and quantum methods
for budgeted agent task selection at 4–24 tasks. Full report:
**[docs/research-report.pdf](docs/research-report.pdf)**.

| Hypothesis (held-out data, frozen protocol) | Result |
|---|---|
| QAOA beats simulated annealing per shot on the same QUBO | ✗: 0.29× (95 % CI 0.12–0.42), loses 59/75 |
| Grover Adaptive Search needs fewer evaluations | ✓ vs uniform random (0.14×) · ✗ vs LP-guided sampling (1.43×) |
| Warm-started quantum re-planning saves work | ✗: median ratio 1.00 |
| Real hardware ≈ vendor noise model | closer to it than to ideal, but 2–3× noisier (IBM ibm_kingston, 8 s free tier) |

## Development

```bash
uv sync
uv run pytest            # unit, property (vs brute force) and MCP stdio tests
uv run ruff check . && uv run mypy
claude plugin validate .
```

## License

MIT