> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Planning Module

> Planning mode for creating implementation plans before execution

# Planning Module

The planning module provides Planning Mode functionality similar to Cursor Plan Mode, Windsurf Planning Mode, Claude Code Plan Mode, and Gemini CLI Plan Mode.

## Installation

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents
```

## Features

* **PlanningAgent** - Creates implementation plans before execution
* **Plan and PlanStep** - Dataclasses for plan structure
* **TodoList** - Track progress through plan steps
* **PlanStorage** - Persistence for plans
* **ApprovalCallback** - Plan approval flow
* **Read-only mode** - Safe research without modifications

## Quick Start

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam

agent = Agent(
    name="Developer",
    role="Software Developer",
    goal="Implement features"
)

task = Task(
    description="Build a REST API",
    agent=agent
)

from praisonaiagents import AgentFlowPlanningConfig

agents = AgentTeam(
    agents=[agent],
    tasks=[task],
    planning=WorkflowPlanningConfig(enabled=True, llm="gpt-4o-mini")
)

result = agents.start()
```

## Classes

### Plan

Represents an implementation plan.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import Plan, PlanStep

plan = Plan(
    title="Build REST API",
    description="Implementation plan for REST API",
    steps=[
        PlanStep(
            title="Set up project structure",
            description="Create directories and files",
            status="pending"
        ),
        PlanStep(
            title="Implement endpoints",
            description="Create API endpoints",
            status="pending"
        )
    ]
)
```

#### Attributes

| Attribute     | Type             | Description           |
| ------------- | ---------------- | --------------------- |
| `title`       | `str`            | Plan title            |
| `description` | `str`            | Plan description      |
| `steps`       | `list[PlanStep]` | List of plan steps    |
| `created_at`  | `datetime`       | Creation timestamp    |
| `updated_at`  | `datetime`       | Last update timestamp |

### PlanStep

A single step in a plan.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import PlanStep

step = PlanStep(
    title="Implement authentication",
    description="Add JWT authentication",
    status="pending",  # pending, in_progress, completed, failed
    dependencies=["step_1"],
    estimated_time="30 minutes"
)
```

#### Attributes

| Attribute        | Type        | Description                                    |
| ---------------- | ----------- | ---------------------------------------------- |
| `title`          | `str`       | Step title                                     |
| `description`    | `str`       | Step description                               |
| `status`         | `str`       | Status (pending/in\_progress/completed/failed) |
| `dependencies`   | `list[str]` | IDs of dependent steps                         |
| `estimated_time` | `str`       | Estimated completion time                      |
| `result`         | `str`       | Execution result                               |

### TodoList

Track progress through plan steps.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import TodoList, TodoItem

todo = TodoList()
todo.add(TodoItem(
    title="Research API frameworks",
    priority="high"
))
todo.add(TodoItem(
    title="Write tests",
    priority="medium"
))

# Mark as complete
todo.complete("Research API frameworks")
```

#### Methods

| Method            | Description           |
| ----------------- | --------------------- |
| `add(item)`       | Add a todo item       |
| `remove(title)`   | Remove an item        |
| `complete(title)` | Mark item as complete |
| `get_pending()`   | Get pending items     |
| `get_completed()` | Get completed items   |

### TodoItem

A single todo item.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import TodoItem

item = TodoItem(
    title="Implement feature",
    description="Add new feature",
    priority="high",  # high, medium, low
    status="pending"  # pending, in_progress, completed, cancelled
)
```

#### Attributes

| Attribute      | Type        | Description                                       |
| -------------- | ----------- | ------------------------------------------------- |
| `description`  | `str`       | What needs to be done                             |
| `status`       | `str`       | Status (pending/in\_progress/completed/cancelled) |
| `priority`     | `str`       | Priority (low/medium/high)                        |
| `dependencies` | `list[str]` | IDs of items that must complete first             |
| `agent`        | `str`       | Name of the agent responsible                     |

### PlanStorage

Persist plans to storage.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import PlanStorage

storage = PlanStorage(path=".praison/plans")

# Save a plan
storage.save(plan)

# Load a plan
loaded_plan = storage.load("plan_id")

# List all plans
plans = storage.list_all()
```

### PlanningAgent

Agent that creates implementation plans.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import PlanningAgent

planner = PlanningAgent(
    llm="gpt-4o-mini",
    
)

plan = planner.create_plan(
    task="Build a REST API with authentication",
    context="Using FastAPI framework"
)
```

### ApprovalCallback

Callback for plan approval flow.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import ApprovalCallback

def my_approval(plan):
    print(f"Plan: {plan.title}")
    for step in plan.steps:
        print(f"  - {step.title}")
    return input("Approve? (y/n): ").lower() == "y"

callback = ApprovalCallback(approval_func=my_approval)
```

## Tool Lists

### READ\_ONLY\_TOOLS

Tools allowed in planning mode (safe for research):

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import READ_ONLY_TOOLS

# Includes:
# - read_file, list_directory, search_codebase
# - search_files, grep_search, find_files
# - web_search, get_file_content, list_files
# - read_document, search_web, fetch_url, get_context
```

### RESTRICTED\_TOOLS

Tools blocked in planning mode:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import RESTRICTED_TOOLS

# Includes:
# - write_file, create_file, delete_file
# - execute_command, run_command, shell_command
# - modify_file, edit_file, remove_file
# - move_file, copy_file, mkdir, rmdir
# - git_commit, git_push, npm_install, pip_install
```

### RESEARCH\_TOOLS

Tools safe for planning research:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import RESEARCH_TOOLS

# Includes:
# - web_search, search_web, duckduckgo_search
# - tavily_search, brave_search, google_search
# - read_url, fetch_url, read_file
# - list_directory, search_codebase
# - grep_search, find_files
```

## Usage Examples

### Basic Planning Mode

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam

agent = Agent(
    name="Developer",
    role="Full Stack Developer",
    goal="Build web applications"
)

task = Task(
    description="Create a blog application with user authentication",
    expected_output="A working blog application",
    agent=agent
)

# Enable planning mode
agents = AgentTeam(
    agents=[agent],
    tasks=[task],
    planning=True
)

result = agents.start()
```

### Custom Planning LLM

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import AgentFlowPlanningConfig

agents = AgentTeam(
    agents=[agent],
    tasks=[task],
    planning=WorkflowPlanningConfig(enabled=True, llm="gpt-4o")
)
```

### Manual Plan Creation

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import Plan, PlanStep, PlanStorage

# Create a plan manually
plan = Plan(
    title="API Development",
    steps=[
        PlanStep(title="Design API schema", status="completed"),
        PlanStep(title="Implement endpoints", status="in_progress"),
        PlanStep(title="Write tests", status="pending"),
        PlanStep(title="Deploy", status="pending")
    ]
)

# Save to storage
storage = PlanStorage()
storage.save(plan)
```

### Plan with Approval

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.planning import PlanningAgent, ApprovalCallback

def approve_plan(plan):
    print("\n=== Plan Review ===")
    print(f"Title: {plan.title}")
    print("\nSteps:")
    for i, step in enumerate(plan.steps, 1):
        print(f"  {i}. {step.title}")
    
    response = input("\nApprove this plan? (y/n): ")
    return response.lower() == "y"

planner = PlanningAgent(
    approval_callback=ApprovalCallback(approval_func=approve_plan)
)
```

## Best Practices

1. **Use planning for complex tasks** - Simple tasks don't need planning
2. **Review plans before execution** - Use approval callbacks
3. **Break down large plans** - Keep steps manageable
4. **Track dependencies** - Define step dependencies for proper ordering
5. **Persist plans** - Save plans for review and resumption

## Related

* [Agent](/docs/sdk/praisonaiagents/agent/agent) - Agent configuration
* [Task](/docs/sdk/praisonaiagents/task/task) - Task definition
* [Agents](/docs/sdk/praisonaiagents/agents/agents) - Multi-agent orchestration