forgeoptimizer 0.1.0__py3-none-any.whl

forgecli/planner/__init__.py

@@ -0,0 +1,56 @@
+"""Planning and agentic execution strategies."""
+
+from forgecli.planner.agent import Agent
+from forgecli.planner.plan import Plan, Step, StepStatus
+from forgecli.planner.planner import Planner
+from forgecli.planner.render import print_plan, render_plan
+from forgecli.planner.serialize import plan_to_dict, plan_to_json, plan_to_markdown
+from forgecli.planner.software import (
+    Architecture,
+    Component,
+    ComponentKind,
+    DataFlow,
+    FolderNode,
+    FolderStructure,
+    Milestone,
+    PlannerOptions,
+    Priority,
+    PromptSequence,
+    PromptTurn,
+    Risk,
+    RiskSeverity,
+    SoftwarePlan,
+    Task,
+    TaskStatus,
+    build_software_plan,
+)
+
+__all__ = [
+    "Agent",
+    "Architecture",
+    "Component",
+    "ComponentKind",
+    "DataFlow",
+    "FolderNode",
+    "FolderStructure",
+    "Milestone",
+    "Plan",
+    "Planner",
+    "PlannerOptions",
+    "Priority",
+    "PromptSequence",
+    "PromptTurn",
+    "Risk",
+    "RiskSeverity",
+    "SoftwarePlan",
+    "Step",
+    "StepStatus",
+    "Task",
+    "TaskStatus",
+    "build_software_plan",
+    "plan_to_dict",
+    "plan_to_json",
+    "plan_to_markdown",
+    "print_plan",
+    "render_plan",
+]

forgecli/planner/agent.py

@@ -0,0 +1,61 @@
+"""Executes a :class:`Plan` step-by-step using registered tools."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from forgecli.core.service import Service
+from forgecli.planner.plan import Plan, Step
+from forgecli.planner.planner import Planner
+
+ToolFn = Callable[[Step], Awaitable[Any]]
+
+
+class Agent(Service):
+    """Drives a plan through a registry of tool callables.
+
+    Tools are registered as async callables taking a :class:`Step` and
+    returning an arbitrary result. This keeps the agent implementation
+    small and lets us add tools (read_file, edit_file, run_shell, ...)
+    without subclassing.
+    """
+
+    name = "planner.agent"
+
+    def __init__(self, planner: Planner) -> None:
+        super().__init__()
+        self._planner = planner
+        self._tools: dict[str, ToolFn] = {}
+
+    @property
+    def planner(self) -> Planner:
+        return self._planner
+
+    def register_tool(self, name: str, fn: ToolFn) -> None:
+        """Register ``fn`` as a callable for steps tagged with ``name``."""
+        self._tools[name] = fn
+
+    def tool_names(self) -> list[str]:
+        return sorted(self._tools)
+
+    async def run(self, goal: str, *, context: dict | None = None) -> Plan:
+        """Plan and execute ``goal``; returns the executed :class:`Plan`."""
+        plan = await self._planner.make_plan(goal, context=context)
+        for step in plan.steps:
+            await self._execute_step(step)
+        return plan
+
+    async def _execute_step(self, step: Step) -> None:
+        if step.tool is None:
+            step.mark_done()
+            return
+        tool = self._tools.get(step.tool)
+        if tool is None:
+            step.mark_done(error=f"Unknown tool: {step.tool}")
+            return
+        step.mark_running()
+        try:
+            step.mark_done(result=await tool(step))
+        except Exception as exc:
+            step.mark_done(error=str(exc))

forgecli/planner/plan.py

@@ -0,0 +1,65 @@
+"""Plan/Step value types for the planner."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+
+class StepStatus(str, Enum):
+    """Lifecycle status of a single :class:`Step`."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class Step:
+    """A unit of work in a :class:`Plan`."""
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    description: str = ""
+    tool: str | None = None
+    inputs: dict[str, Any] = field(default_factory=dict)
+    status: StepStatus = StepStatus.PENDING
+    result: Any = None
+    error: str | None = None
+    started_at: float | None = None
+    finished_at: float | None = None
+
+    def mark_running(self) -> None:
+        self.status = StepStatus.RUNNING
+        self.started_at = time.time()
+
+    def mark_done(self, *, result: Any = None, error: str | None = None) -> None:
+        self.finished_at = time.time()
+        if error is None:
+            self.status = StepStatus.SUCCEEDED
+        else:
+            self.status = StepStatus.FAILED
+            self.error = error
+        self.result = result
+
+
+@dataclass
+class Plan:
+    """An ordered, named collection of :class:`Step` objects."""
+
+    id: str = field(default_factory=lambda: str(uuid4()))
+    name: str = "plan"
+    goal: str = ""
+    steps: list[Step] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def add_step(self, step: Step) -> Step:
+        self.steps.append(step)
+        return step
+
+    def pending_steps(self) -> list[Step]:
+        return [s for s in self.steps if s.status is StepStatus.PENDING]

forgecli/planner/planner.py

@@ -0,0 +1,17 @@
+"""High-level planner interface."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from forgecli.planner.plan import Plan
+
+
+class Planner(ABC):
+    """Strategy interface for turning a goal into a :class:`Plan`."""
+
+    name: str = "abstract"
+
+    @abstractmethod
+    async def make_plan(self, goal: str, *, context: dict | None = None) -> Plan:
+        """Build a :class:`Plan` that aims to satisfy ``goal``."""

forgecli/planner/render.py

@@ -0,0 +1,267 @@
+"""Rich-based renderer for :class:`SoftwarePlan`.
+
+The renderer is pure: it accepts a :class:`SoftwarePlan` and a Rich
+:class:`Console` and emits the plan as a sequence of sections. Callers
+can override the console, choose a different layout, or post-process
+the output before display.
+"""
+
+from __future__ import annotations
+
+from rich.console import Console, Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.tree import Tree
+
+from forgecli.planner.software import (
+    FolderNode,
+    Priority,
+    RiskSeverity,
+    SoftwarePlan,
+)
+
+_PRIORITY_STYLE: dict[Priority, str] = {
+    Priority.P0: "bold red",
+    Priority.P1: "bold yellow",
+    Priority.P2: "cyan",
+    Priority.P3: "muted",
+}
+
+_RISK_STYLE: dict[RiskSeverity, str] = {
+    RiskSeverity.LOW: "green",
+    RiskSeverity.MEDIUM: "yellow",
+    RiskSeverity.HIGH: "bold red",
+}
+
+
+def print_plan(plan: SoftwarePlan, console: Console | None = None) -> None:
+    """Print a :class:`SoftwarePlan` using the given Rich console."""
+    console = console or Console()
+    for renderable in render_plan(plan):
+        console.print(renderable)
+
+
+def render_plan(plan: SoftwarePlan) -> list:
+    """Return a list of Rich renderables that visualize ``plan``."""
+    renderables: list = []
+    renderables.append(_render_header(plan))
+    renderables.append(_render_summary(plan))
+    renderables.append(_render_architecture(plan))
+    renderables.append(_render_folder_structure(plan))
+    renderables.append(_render_milestones(plan))
+    renderables.append(_render_tasks(plan))
+    renderables.append(_render_risks(plan))
+    renderables.extend(_render_prompt_sequences(plan))
+    if plan.notes:
+        renderables.append(_render_notes(plan))
+    return renderables
+
+
+# ---------------------------------------------------------------------------
+# Sections
+# ---------------------------------------------------------------------------
+
+
+def _render_header(plan: SoftwarePlan) -> Panel:
+    title = Text("Forge Plan", style="bold accent")
+    title.append("  —  ", style="muted")
+    title.append(plan.goal, style="bold")
+    return Panel(
+        title,
+        border_style="magenta",
+        title=Text("forge plan", style="bold magenta"),
+        title_align="left",
+        padding=(0, 1),
+    )
+
+
+def _render_summary(plan: SoftwarePlan) -> Panel:
+    body = Text(plan.summary, style="white")
+    stats = Table.grid(padding=(0, 2))
+    stats.add_column(style="bold")
+    stats.add_column()
+    stats.add_row("milestones", str(len(plan.milestones)))
+    stats.add_row("tasks", str(len(plan.tasks)))
+    stats.add_row("risks", str(len(plan.risks)))
+    stats.add_row("prompts", str(len(plan.prompt_sequences)))
+    layout = Group(
+        body,
+        Text(""),
+        stats,
+    )
+    return Panel(layout, title="Summary", border_style="cyan", padding=(0, 1))
+
+
+def _render_architecture(plan: SoftwarePlan) -> Panel:
+    table = Table(
+        title="Components",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    table.add_column("Name", style="bold")
+    table.add_column("Kind")
+    table.add_column("Purpose", overflow="fold")
+    table.add_column("Depends on", style="muted")
+    for component in plan.architecture.components:
+        table.add_row(
+            component.name,
+            component.kind.value,
+            component.purpose,
+            ", ".join(component.depends_on) or "—",
+        )
+    flows = Table(
+        title="Data flow",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    flows.add_column("Source", style="bold")
+    flows.add_column("Target", style="bold")
+    flows.add_column("Contract", overflow="fold")
+    for flow in plan.architecture.flows:
+        flows.add_row(flow.source, flow.target, flow.contract)
+    body: list = [
+        Text(plan.architecture.summary, style="white"),
+        Text(""),
+        table,
+        Text(""),
+        flows,
+    ]
+    return Panel(Group(*body), title="Architecture", border_style="cyan", padding=(0, 1))
+
+
+def _render_folder_structure(plan: SoftwarePlan) -> Panel:
+    root = plan.folder_structure.root
+    tree = Tree(Text(root, style="bold magenta"), guide_style="cyan")
+    _populate_tree(tree, plan.folder_structure.tree)
+    return Panel(tree, title=f"Folder structure ({root}/)", border_style="cyan", padding=(0, 1))
+
+
+def _populate_tree(parent: Tree, nodes: list[FolderNode]) -> None:
+    for node in nodes:
+        label = Text(node.path, style="bold")
+        if node.purpose:
+            label.append("  ")
+            label.append(Text(f"({node.purpose})", style="muted"))
+        branch = parent.add(label)
+        if node.children:
+            _populate_tree(branch, node.children)
+
+
+def _render_milestones(plan: SoftwarePlan) -> Panel:
+    table = Table(
+        title="Milestones",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=False,
+        expand=True,
+    )
+    table.add_column("ID", style="bold", no_wrap=True)
+    table.add_column("Priority", no_wrap=True)
+    table.add_column("Title", style="bold")
+    table.add_column("Description", overflow="fold")
+    table.add_column("Tasks", justify="right", style="muted")
+    for milestone in plan.milestones:
+        table.add_row(
+            milestone.id,
+            Text(milestone.priority.value, style=_PRIORITY_STYLE[milestone.priority]),
+            milestone.title,
+            milestone.description,
+            str(len(milestone.task_ids)),
+        )
+    return Panel(table, title="Roadmap", border_style="cyan", padding=(0, 1))
+
+
+def _render_tasks(plan: SoftwarePlan) -> Panel:
+    table = Table(
+        title="Tasks",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=True,
+        expand=True,
+    )
+    table.add_column("ID", style="bold", no_wrap=True)
+    table.add_column("M", no_wrap=True, style="muted")
+    table.add_column("Priority", no_wrap=True)
+    table.add_column("Size", no_wrap=True, justify="right")
+    table.add_column("Title", style="bold")
+    table.add_column("Acceptance", overflow="fold", style="muted")
+    for task in plan.tasks:
+        acceptance = "\n".join(f"• {c}" for c in task.acceptance) or "—"
+        table.add_row(
+            task.id,
+            task.milestone_id,
+            Text(task.priority.value, style=_PRIORITY_STYLE[task.priority]),
+            task.estimate,
+            task.title,
+            acceptance,
+        )
+    return Panel(table, title="Task list", border_style="cyan", padding=(0, 1))
+
+
+def _render_risks(plan: SoftwarePlan) -> Panel:
+    table = Table(
+        title="Risks",
+        title_style="bold cyan",
+        header_style="bold magenta",
+        show_lines=True,
+        expand=True,
+    )
+    table.add_column("ID", style="bold", no_wrap=True)
+    table.add_column("Severity", no_wrap=True)
+    table.add_column("Likelihood", no_wrap=True)
+    table.add_column("Description", overflow="fold")
+    table.add_column("Mitigation", overflow="fold", style="muted")
+    for risk in plan.risks:
+        table.add_row(
+            risk.id,
+            Text(risk.severity.value, style=_RISK_STYLE[risk.severity]),
+            Text(risk.likelihood.value, style=_RISK_STYLE[risk.likelihood]),
+            risk.description,
+            risk.mitigation or "—",
+        )
+    return Panel(table, title="Risk register", border_style="cyan", padding=(0, 1))
+
+
+def _render_prompt_sequences(plan: SoftwarePlan) -> list[Panel]:
+    panels: list[Panel] = []
+    for sequence in plan.prompt_sequences[:3]:
+        body = Text()
+        body.append("system: ", style="bold magenta")
+        body.append(sequence.system, style="white")
+        body.append("\n\n")
+        body.append("user: ", style="bold cyan")
+        body.append(sequence.user, style="white")
+        panels.append(
+            Panel(
+                body,
+                title=f"Prompt — task {sequence.task_id}",
+                border_style="magenta",
+                padding=(0, 1),
+            )
+        )
+    remaining = len(plan.prompt_sequences) - 3
+    if remaining > 0:
+        panels.append(
+            Panel(
+                Text(
+                    f"+ {remaining} more prompt sequences (use --json or --md to view all).",
+                    style="muted",
+                ),
+                border_style="magenta",
+                padding=(0, 1),
+            )
+        )
+    return panels
+
+
+def _render_notes(plan: SoftwarePlan) -> Panel:
+    body = Text("\n".join(f"• {note}" for note in plan.notes), style="muted")
+    return Panel(body, title="Notes", border_style="cyan", padding=(0, 1))
+
+
+__all__ = ["print_plan", "render_plan"]

forgecli/planner/serialize.py

@@ -0,0 +1,104 @@
+"""Serialize :class:`SoftwarePlan` to JSON or Markdown."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forgecli.planner.software import SoftwarePlan
+
+
+def plan_to_json(plan: SoftwarePlan, *, indent: int = 2) -> str:
+    """Return a JSON string representation of ``plan``."""
+    return plan.model_dump_json(indent=indent)
+
+
+def plan_to_dict(plan: SoftwarePlan) -> dict[str, Any]:
+    """Return the plan as a JSON-serializable dict."""
+    return plan.model_dump(mode="json")
+
+
+def plan_to_markdown(plan: SoftwarePlan) -> str:
+    """Return a Markdown rendering of ``plan``."""
+    parts: list[str] = []
+    parts.append(f"# Plan: {plan.goal}\n")
+    parts.append(f"_{plan.summary}_\n")
+
+    parts.append("## Architecture\n")
+    parts.append(plan.architecture.summary + "\n")
+    parts.append("### Components\n")
+    parts.append("| Name | Kind | Purpose | Depends on |")
+    parts.append("| --- | --- | --- | --- |")
+    for component in plan.architecture.components:
+        deps = ", ".join(component.depends_on) or "—"
+        parts.append(
+            f"| {component.name} | {component.kind.value} | {component.purpose} | {deps} |"
+        )
+    parts.append("\n### Data flow\n")
+    parts.append("| Source | Target | Contract |")
+    parts.append("| --- | --- | --- |")
+    for flow in plan.architecture.flows:
+        parts.append(f"| {flow.source} | {flow.target} | {flow.contract} |")
+
+    parts.append("\n## Folder structure\n")
+    parts.append(f"Root: `{plan.folder_structure.root}/`\n")
+    parts.append("```")
+    for line in _format_tree(plan.folder_structure.tree):
+        parts.append(line)
+    parts.append("```")
+
+    parts.append("\n## Roadmap\n")
+    for milestone in plan.milestones:
+        parts.append(f"### {milestone.id} — {milestone.title} ({milestone.priority.value})")
+        parts.append(milestone.description)
+        parts.append("\n**Deliverables:**")
+        for deliverable in milestone.deliverables:
+            parts.append(f"- {deliverable}")
+
+    parts.append("\n## Tasks\n")
+    parts.append("| ID | M | Priority | Size | Title | Owner |")
+    parts.append("| --- | --- | --- | --- | --- | --- |")
+    for task in plan.tasks:
+        parts.append(
+            f"| {task.id} | {task.milestone_id} | {task.priority.value} | "
+            f"{task.estimate} | {task.title} | {task.owner} |"
+        )
+
+    parts.append("\n## Risks\n")
+    parts.append("| ID | Severity | Likelihood | Description | Mitigation |")
+    parts.append("| --- | --- | --- | --- | --- |")
+    for risk in plan.risks:
+        parts.append(
+            f"| {risk.id} | {risk.severity.value} | {risk.likelihood.value} | "
+            f"{risk.description} | {risk.mitigation or '—'} |"
+        )
+
+    parts.append("\n## Prompt sequences\n")
+    for sequence in plan.prompt_sequences:
+        parts.append(f"### Task {sequence.task_id}\n")
+        parts.append("**System**\n")
+        parts.append(f"```\n{sequence.system}\n```\n")
+        parts.append("**User**\n")
+        parts.append(f"```\n{sequence.user}\n```\n")
+
+    if plan.notes:
+        parts.append("\n## Notes\n")
+        for note in plan.notes:
+            parts.append(f"- {note}")
+
+    return "\n".join(parts) + "\n"
+
+
+def _format_tree(nodes, prefix: str = "") -> list[str]:
+    lines: list[str] = []
+    for index, node in enumerate(nodes):
+        last = index == len(nodes) - 1
+        connector = "└── " if last else "├── "
+        annotation = f"  ({node.purpose})" if node.purpose else ""
+        lines.append(f"{prefix}{connector}{node.path}{annotation}")
+        if node.children:
+            extension = "    " if last else "│   "
+            lines.extend(_format_tree(node.children, prefix + extension))
+    return lines
+
+
+__all__ = ["plan_to_dict", "plan_to_json", "plan_to_markdown"]