Metadata-Version: 2.4
Name: mcpaisuite-planningmcp
Version: 1.0.3
Summary: Planning and execution engine for AI agents with MCP support
Project-URL: Homepage, https://github.com/gashel01/planningmcp
Project-URL: Repository, https://github.com/gashel01/planningmcp
Project-URL: Issues, https://github.com/gashel01/planningmcp/issues
Author-email: gashel01 <gaeldev@gmail.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.0
Requires-Dist: mcpaisuite-ltpmcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: httpx>=0.25; extra == 'all'
Requires-Dist: litellm>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-memorymcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-ragmcp>=1.0; extra == 'all'
Requires-Dist: opentelemetry-api>=1.20; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'all'
Requires-Dist: redis>=4.2; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == 'api'
Requires-Dist: uvicorn>=0.23; extra == 'api'
Provides-Extra: dev
Requires-Dist: httpx>=0.25; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: litellm
Requires-Dist: litellm>=1.0; extra == 'litellm'
Provides-Extra: memorymcp
Requires-Dist: mcpaisuite-memorymcp>=1.0; extra == 'memorymcp'
Provides-Extra: ragmcp
Requires-Dist: mcpaisuite-ragmcp>=1.0; extra == 'ragmcp'
Provides-Extra: redis
Requires-Dist: redis>=4.2; extra == 'redis'
Provides-Extra: tracing
Requires-Dist: opentelemetry-api>=1.20; extra == 'tracing'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'tracing'
Provides-Extra: webhooks
Requires-Dist: httpx>=0.25; extra == 'webhooks'
Description-Content-Type: text/markdown

# planningmcp

> Planning and execution engine for AI agents with MCP support

Part of the [MCP AI Suite](https://mcpaisuite.dev).

## Features

- **Goal decomposition** -- break goals into executable steps via pattern, template, LLM, or hybrid decomposers
- **Plan execution** with step-by-step tracking, parallel execution, and progress reporting
- **Replanning** -- automatic recovery from step failures via retry, skip, or LLM-based replan strategies
- **Cost estimation and budget management** with per-plan and per-namespace limits
- **Plan optimization** -- auto-parallelization, bottleneck detection, and critical path analysis
- **Plan templates** -- 8 built-in workflows: deploy, migrate, audit, analyze, setup, refactor, onboard, incident
- **LTP integration** -- compile goals into Lean Task Protocol plans for deterministic execution (provided by the separate [`ltpmcp`](https://pypi.org/project/mcpaisuite-ltpmcp/) dependency, whose LTP types planningmcp re-exports)
- **Mermaid diagram export** for plan visualization
- **OpenTelemetry tracing** support (optional)

## Installation

```bash
pip install mcpaisuite-planningmcp
# Optional extras:
pip install mcpaisuite-planningmcp[dev]       # Development tools
pip install mcpaisuite-planningmcp[all]       # All integrations
pip install mcpaisuite-planningmcp[litellm]   # LLM-based decomposition
pip install mcpaisuite-planningmcp[redis]     # Redis plan store
pip install mcpaisuite-planningmcp[tracing]   # OpenTelemetry tracing
```

## Quick Start

```python
from planningmcp import PlanningFactory

planner = PlanningFactory.create(plan_store="sqlite", sqlite_path="plans.db")
plan = await planner.create_plan("Research and summarize Python 3.13 features")
plan = await planner.execute_plan(plan.id)
print(f"Status: {plan.status}, Progress: {plan.progress:.0%}")
```

## MCP Server

```bash
planningmcp serve
```

## Configuration

| Variable | Default | Description |
|---|---|---|
| `PLANNINGMCP_DECOMPOSER` | `template` | Decomposer: `pattern`, `template`, `llm`, `hybrid` |
| `PLANNINGMCP_STORE` | `memory` | Plan store: `memory`, `sqlite`, `redis` |
| `PLANNINGMCP_SQLITE_PATH` | `planningmcp.db` | SQLite database path |
| `PLANNINGMCP_MODEL` | `default` | LLM model for cost estimation |
| `PLANNINGMCP_REPLAN` | `retry` | Replan strategy: `retry`, `skip`, `llm` |
| `REDIS_URL` | `redis://localhost:6379/0` | Redis URL (when store=redis) |
| `PLANNINGMCP_WEBHOOK_URLS` | -- | Comma-separated webhook URLs |

## API Reference

### PlanningPipeline

Central orchestrator for plan creation, execution, and learning.

```python
await planner.create_plan(goal, namespace="default", context="") -> Plan
await planner.execute_plan(plan_id) -> Plan
await planner.execute_step(plan_id, step_id) -> StepResult
await planner.estimate_cost(plan_id) -> CostEstimate
await planner.replan(plan_id, failed_step_id) -> Plan
await planner.optimize_plan(plan_id) -> Plan
await planner.get_bottlenecks(plan_id) -> list[dict]
await planner.get_critical_path(plan_id) -> list[dict]
await planner.to_mermaid(plan_id) -> str
await planner.compile_ltp(goal) -> LTPPlan
await planner.run_ltp(goal, tool_executor=None) -> dict
```

### PlanningFactory

```python
PlanningFactory.default()                # SQLite store (planningmcp.db), template decomposer
PlanningFactory.from_env()               # Build from environment variables
PlanningFactory.from_yaml("config.yaml") # Build from YAML config
PlanningFactory.create(decomposer="hybrid", plan_store="sqlite", completion_fn=my_llm, ...)
```

## Architecture

PlanningPipeline coordinates goal decomposition (via pluggable decomposers), step execution (via PlanExecutor with parallel support), and learning (via PlanHistory). ReplanEngine handles failure recovery with configurable strategies. BudgetManager enforces cost limits, and the optional memory/RAG integrations enrich plan context from prior executions. Plans are stored in pluggable backends (memory, SQLite, Redis).

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

AGPL-3.0 — see [LICENSE](LICENSE).

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [gaeldev@gmail.com](mailto:gaeldev@gmail.com).
