PlannerAI

Goal decomposition and planning engine — a Python library that breaks complex goals into sub-tasks, creates dependency graphs, and generates execution plans.

How It Works

graph LR
    A[Goal] --> B[Decompose]
    B --> C[Task Graph]
    C --> D[Topological Sort]
    D --> E[Execution Plan]
    C --> F[Critical Path]
    F --> G[Time Estimate]
    C --> H[Export]
    H --> I[JSON / YAML / DOT]

Loading

Quickstart

Installation

pip install -e .

Basic Usage

from plannerai import PlannerAI, Task

planner = PlannerAI()

# Create a plan
plan = planner.create_plan("Launch MVP")

# Add tasks
design = planner.add_task(plan, Task(name="Design UI", estimated_duration=8))
backend = planner.add_task(plan, Task(name="Build API", estimated_duration=12))
tests = planner.add_task(plan, Task(name="Write tests", estimated_duration=4))
deploy = planner.add_task(plan, Task(name="Deploy", estimated_duration=2))

# Define dependencies
planner.add_dependency(plan, tests, design)
planner.add_dependency(plan, tests, backend)
planner.add_dependency(plan, deploy, tests)

# Get execution order (topological sort)
order = planner.get_execution_order(plan)
for task in order:
    print(f"  {task.name}")

# Analyse
path, duration = planner.get_critical_path(plan)
print(f"Critical path: {' -> '.join(t.name for t in path)} ({duration}h)")

# Visualise
print(planner.visualize(plan))

# Export
print(planner.export(plan, "json"))

Auto-Decomposition

plan = planner.decompose("Build and ship a SaaS product", depth=2)
print(planner.visualize(plan))

Features

• Goal decomposition — break high-level objectives into phased sub-tasks
• Dependency graphs — define prerequisite relationships with cycle detection
• Topological sorting — compute a valid execution order
• Critical path analysis — find the longest dependency chain and bottleneck
• Parallel layers — group tasks that can run concurrently
• Time estimation — parallel-aware or sequential duration calculation
• Multiple export formats — JSON, YAML, and Graphviz DOT
• Pydantic models — fully typed, validated data structures
• Zero external dependencies beyond Pydantic

Configuration

Copy .env.example to .env and customise:

PLANNERAI_MAX_DEPTH=5
PLANNERAI_TIME_UNIT=hours
PLANNERAI_LOG_LEVEL=INFO
PLANNERAI_EXPORT_FORMAT=json

Or configure in code:

from plannerai import PlannerAI, PlannerConfig, TimeUnit

config = PlannerConfig(
    max_depth=3,
    time_unit=TimeUnit.DAYS,
    parallel_execution=True,
)
planner = PlannerAI(config=config)

Development

make dev        # Install dev dependencies
make test       # Run tests
make lint       # Lint with ruff
make typecheck  # Type check with mypy
make fmt        # Auto-format
make all        # Run everything

Project Structure

PlannerAI/
├── src/plannerai/
│   ├── __init__.py     # Public API
│   ├── core.py         # PlannerAI engine, Task, Plan models
│   ├── config.py       # Configuration (PlannerConfig)
│   └── utils.py        # Graph algorithms, topological sort
├── tests/
│   └── test_core.py    # Test suite
├── docs/
│   └── ARCHITECTURE.md # Architecture documentation
├── pyproject.toml      # Package metadata
├── Makefile            # Dev commands
└── README.md

Inspired by

AI planning and goal decomposition trends.

---

Built by Officethree Technologies | Made with love and AI