caudate-cli 0.1.0__py3-none-any.whl

planning/planner.py

@@ -0,0 +1,451 @@
+"""Planner — decomposes goals into executable task graphs using LLM reasoning."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from config import MAX_PLAN_DEPTH, MAX_REPLAN_ATTEMPTS
+from core.schemas import Goal, Plan, Task, Reflection, Perception
+from llm.provider import LLMProvider
+from planning.task_graph import TaskGraph
+
+logger = logging.getLogger(__name__)
+
+
+class TaskOutput(BaseModel):
+    """One task in a plan, as emitted by the LLM."""
+    description: str
+    tool_name: str | None = None
+    tool_args: dict[str, Any] = Field(default_factory=dict)
+    dependencies: list[int] = Field(default_factory=list)
+
+
+class PlanOutput(BaseModel):
+    """LLM-emitted plan structure."""
+    reasoning: str
+    tasks: list[TaskOutput] = Field(default_factory=list)
+
+PLAN_SYSTEM_PROMPT = """You are a planning module in a cognitive architecture.
+Your job is to decompose a goal into concrete, executable tasks.
+
+Each task should specify:
+- description: what to do
+- tool_name: which tool to use (or null if it's a reasoning step)
+- tool_args: arguments for the tool (MUST provide all required args)
+- dependencies: list of task indices (0-based) this task depends on
+
+IMPORTANT RULES:
+- The "Respond" tool REQUIRES a "message" argument. Results from prior tasks are automatically available, so write a helpful message that answers the user's goal. You can reference prior results — they will be appended.
+- Always end your plan with a "Respond" task to present results to the user.
+- For tool_args, provide concrete values. Don't leave required args empty.
+- Results from completed tasks automatically flow to dependent tasks.
+
+Available tools: {tools}
+
+Respond with JSON:
+{{
+  "reasoning": "your reasoning about how to achieve the goal",
+  "tasks": [
+    {{
+      "description": "step description",
+      "tool_name": "tool_name or null",
+      "tool_args": {{}},
+      "dependencies": []
+    }}
+  ]
+}}"""
+
+REPLAN_SYSTEM_PROMPT = """You are a planning module re-evaluating a failed plan.
+
+Original goal: {goal}
+Original plan reasoning: {reasoning}
+What failed: {failure}
+Reflection: {reflection}
+
+Create a revised plan that addresses the failure. You may reuse successful steps.
+Respond with the same JSON format as before."""
+
+
+class Planner:
+    """Decomposes goals into task DAGs, with re-planning on failure."""
+
+    def __init__(self, llm: LLMProvider):
+        self.llm = llm
+
+    def reset(self) -> None:
+        """Reset state for a new goal."""
+        pass
+
+    async def create_plan(
+        self,
+        goal: Goal,
+        perception: Perception,
+        available_tools: list[str],
+    ) -> Plan:
+        """Decompose a goal into a plan (task DAG)."""
+        context_parts = []
+        if perception.working_memory:
+            context_parts.append(f"Current context: {json.dumps(perception.working_memory)}")
+        if perception.relevant_episodes:
+            eps = [e.action for e in perception.relevant_episodes[:3]]
+            context_parts.append(f"Relevant past actions: {eps}")
+        if perception.active_strategies:
+            strats = [f"{s.name}: {s.actions}" for s in perception.active_strategies]
+            context_parts.append(f"Applicable strategies: {strats}")
+        if perception.relevant_knowledge:
+            context_parts.append(f"Relevant knowledge: {perception.relevant_knowledge[:3]}")
+
+        context_str = "\n".join(context_parts) if context_parts else "No prior context."
+
+        prompt = f"""Goal: {goal.description}
+Success criteria: {goal.success_criteria}
+
+Context:
+{context_str}
+
+Decompose this goal into executable tasks."""
+
+        system = PLAN_SYSTEM_PROMPT.format(tools=", ".join(available_tools))
+
+        try:
+            result = await self.llm.structured_output(
+                prompt=prompt, system=system, response_model=PlanOutput,
+                caller="planning",
+            )
+            tasks = self._build_tasks(result, goal.id)
+            plan = Plan(
+                goal_id=goal.id,
+                tasks=tasks,
+                reasoning=result.reasoning,
+            )
+            logger.info(f"Created plan with {len(tasks)} tasks for goal: {goal.description}")
+            return plan
+        except Exception as e:
+            logger.error(f"Planning failed: {e}")
+            # Fallback: single reasoning task
+            return Plan(
+                goal_id=goal.id,
+                tasks=[Task(
+                    goal_id=goal.id,
+                    description=f"Attempt to achieve: {goal.description}",
+                )],
+                reasoning=f"Planning failed ({e}), falling back to direct attempt.",
+            )
+
+    async def replan(
+        self,
+        goal: Goal,
+        current_plan: Plan,
+        reflection: Reflection,
+        available_tools: list[str],
+    ) -> Plan | None:
+        """Create a revised plan based on reflection of failure."""
+        # Replan limit is managed by the cognitive loop, not here
+
+        failure_desc = reflection.what_failed or "Unknown failure"
+        system = REPLAN_SYSTEM_PROMPT.format(
+            goal=goal.description,
+            reasoning=current_plan.reasoning,
+            failure=failure_desc,
+            reflection=reflection.lesson,
+        )
+        prompt = f"Available tools: {', '.join(available_tools)}\nCreate a revised plan."
+
+        try:
+            result = await self.llm.structured_output(
+                prompt=prompt, system=system, response_model=PlanOutput,
+                caller="planning",
+            )
+            tasks = self._build_tasks(result, goal.id)
+            plan = Plan(
+                goal_id=goal.id,
+                tasks=tasks,
+                reasoning=result.reasoning,
+                version=current_plan.version + 1,
+            )
+            logger.info(f"Re-planned (v{plan.version}) with {len(tasks)} tasks")
+            return plan
+        except Exception as e:
+            logger.error(f"Re-planning failed: {e}")
+            return None
+
+    def _build_tasks(self, output: PlanOutput, goal_id: str) -> list[Task]:
+        """Convert PlanOutput into Task objects with proper dependency IDs."""
+        tasks: list[Task] = [
+            Task(
+                goal_id=goal_id,
+                description=t.description,
+                tool_name=t.tool_name,
+                tool_args=t.tool_args,
+            )
+            for t in output.tasks
+        ]
+        for i, raw in enumerate(output.tasks):
+            for idx in raw.dependencies:
+                if 0 <= idx < len(tasks):
+                    tasks[i].dependencies.append(tasks[idx].id)
+        return tasks
+
+    # ───────────────────── Forge bootstrapper ─────────────────────────
+    # Decomposes a project description into a buildable feature backlog.
+    # Different output shape from `create_plan`: features carry detailed
+    # descriptions + acceptance criteria + a verify_command suggestion,
+    # not tool calls. The orchestrator (planning/orchestrator.py) is the
+    # one that turns features into actual subagent runs.
+
+    async def decompose_to_features(
+        self,
+        goal: str,
+        stack_hints: list[str] | None = None,
+        max_features: int = 15,
+    ) -> "list[FeatureOutput]":
+        """Decompose a project description into a feature backlog.
+
+        Returns a list of `FeatureOutput` ready to write to the
+        `forge_features` table. The caller (forge bootstrap CLI) is
+        responsible for inserting into the DB and wiring dependencies
+        by index.
+
+        `stack_hints` should be tags like ["python", "fastapi"] or
+        ["nextjs", "react"] — they steer the verify_command suggestion
+        and the level of UI detail. Empty list = generic.
+        """
+        stack_str = (
+            ", ".join(stack_hints)
+            if stack_hints
+            else "(none specified — pick what fits the goal)"
+        )
+        system = FORGE_BOOTSTRAP_SYSTEM_PROMPT.format(
+            max_features=max_features,
+            stack=stack_str,
+        )
+        prompt = f"Project goal: {goal}\n\nProduce the feature backlog."
+        try:
+            # 15 features × full description + acceptance criteria can
+            # easily exceed the 4 k default and truncate the JSON
+            # response mid-string. Give the bootstrapper plenty of
+            # headroom; salvage handles overruns but avoiding them is
+            # cheaper.
+            result = await self.llm.structured_output(
+                prompt=prompt,
+                system=system,
+                response_model=FeatureBacklogOutput,
+                caller="bootstrapper",
+                max_tokens=16384,
+            )
+            logger.info(
+                f"Bootstrapper produced {len(result.features)} features "
+                f"for goal: {goal[:80]!r}"
+            )
+            return result.features
+        except Exception as e:
+            logger.error(f"Bootstrapper LLM call failed: {e}")
+            raise
+
+    async def revise_feature(
+        self,
+        failed_feature: dict[str, Any],
+        failure_logs: str,
+        project_goal: str | None = None,
+        stack_hints: list[str] | None = None,
+    ) -> list["FeatureOutput"]:
+        """ADR 0003: ask the bootstrapper to re-decompose a feature
+        that hit the 3-failure cap. Returns one or more new features
+        that together replace the original.
+
+        The output is the same FeatureBacklogOutput shape as the main
+        bootstrapper, so the orchestrator can splice the replacements
+        into the existing backlog with deps inherited from the
+        original feature.
+        """
+        stack_str = (
+            ", ".join(stack_hints) if stack_hints else "(unspecified)"
+        )
+        goal_block = (
+            f"\n\nProject goal: {project_goal}" if project_goal else ""
+        )
+        system = FORGE_REVISE_SYSTEM_PROMPT.format(stack=stack_str)
+        prompt = (
+            f"# Feature that failed 3 times\n\n"
+            f"Title: {failed_feature.get('title', '')}\n\n"
+            f"Description:\n{failed_feature.get('description', '') or '(none)'}\n\n"
+            f"Acceptance criteria:\n"
+            f"{failed_feature.get('acceptance_criteria', '') or '(none)'}\n\n"
+            f"Verify command: {failed_feature.get('verify_command') or '(none)'}\n\n"
+            f"# Failure logs (truncated)\n\n```\n{failure_logs[-4000:]}\n```"
+            f"{goal_block}\n\n"
+            f"Re-decompose this feature. Output the same JSON schema "
+            f"as a normal backlog bootstrap, with 1-5 features."
+        )
+        try:
+            result = await self.llm.structured_output(
+                prompt=prompt,
+                system=system,
+                response_model=FeatureBacklogOutput,
+                caller="revise",
+                max_tokens=8192,
+            )
+            logger.info(
+                f"revise_feature produced {len(result.features)} "
+                f"replacement(s) for {failed_feature.get('title', '?')[:60]!r}"
+            )
+            return result.features
+        except Exception as e:
+            logger.error(f"revise_feature LLM call failed: {e}")
+            raise
+
+
+class FeatureOutput(BaseModel):
+    """One feature in a forge backlog, as emitted by the bootstrapper."""
+    title: str
+    description: str
+    # Stored in the DB as a single string; LLMs frequently emit a list
+    # of bullet strings (the natural shape for a checklist). The
+    # validator coerces list -> "- item\n- item" so the DB writer
+    # doesn't have to branch.
+    acceptance_criteria: str = ""
+    priority: int = 0
+    category: str = "functional"   # functional | style
+    # Indices into the surrounding features list — same dependency
+    # idiom as PlanOutput, resolved to feature ids at insert time.
+    depends_on: list[int] = Field(default_factory=list)
+    # Suggested shell command that must exit 0 to mark the feature done.
+    # Bootstrapper picks one based on stack_hints; runner executes it
+    # post-implementation. May be empty if no good default fits.
+    verify_command: str | None = None
+
+    # Pydantic v2 validator: lift list[str] -> bullet-formatted string.
+    @classmethod
+    def _coerce_str_field(cls, v: Any) -> str:
+        if isinstance(v, list):
+            return "\n".join(
+                f"- {str(item).strip()}" for item in v if str(item).strip()
+            )
+        if v is None:
+            return ""
+        return str(v)
+
+    # Apply to fields that LLMs sometimes emit as lists.
+    from pydantic import field_validator as _fv
+
+    _coerce_ac = _fv("acceptance_criteria", mode="before")(  # type: ignore[arg-type]
+        _coerce_str_field
+    )
+    _coerce_desc = _fv("description", mode="before")(  # type: ignore[arg-type]
+        _coerce_str_field
+    )
+    _coerce_verify = _fv("verify_command", mode="before")(  # type: ignore[arg-type]
+        lambda cls, v: None if v in (None, "", []) else
+                       (v if isinstance(v, str) else
+                        " && ".join(str(x) for x in v))
+    )
+
+
+class FeatureBacklogOutput(BaseModel):
+    """Top-level structure the bootstrapper emits."""
+    reasoning: str
+    features: list[FeatureOutput] = Field(default_factory=list)
+
+
+FORGE_BOOTSTRAP_SYSTEM_PROMPT = """You are the Cognos Forge bootstrapper.
+
+Your job: decompose a project description into a buildable backlog of
+{max_features} or fewer features. A weaker local coding agent will
+implement these one at a time, so each feature must be detailed,
+self-contained, and unambiguous.
+
+Stack hints from the user: {stack}
+
+For each feature, produce:
+- title: short imperative (under 100 chars). Start with a verb.
+  Good: "Build user registration form with email + password validation"
+  Bad:  "User auth"
+- description: 150-500 words. Cover UI specifics (components, layout),
+  data details (field names, types, validation), behavior on user
+  actions, edge cases (empty/loading/error states), and explicit
+  scope boundaries (what is NOT in this feature).
+- acceptance_criteria: bulleted checklist of independently testable
+  criteria. 5-15 bullets. Each one a coding agent or human tester can
+  unambiguously verify.
+- priority: integer, lower = built first. Use this to express order
+  even when there's no hard dependency.
+- category: "functional" (default) or "style" (purely visual).
+- depends_on: list of *indices* (0-based, into your own features list)
+  this feature genuinely needs before it can be built. Don't over-chain.
+- verify_command: a shell command that must exit 0 to count this
+  feature as passing. Pick based on stack:
+    * Python: "pytest -q" or "python3 -m mypy ." (use `python3`,
+      NOT bare `python` — most Linux hosts don't symlink it)
+    * Node/web: "npx playwright test" or "npx tsc --noEmit"
+    * Rust: "cargo test"
+    * Go: "go test ./..."
+    * No good default: leave null.
+
+Order features dependency-first:
+  Foundation -> data layer -> UI/behavior -> polish.
+
+Return JSON:
+{{
+  "reasoning": "why this breakdown",
+  "features": [
+    {{
+      "title": "...",
+      "description": "...",
+      "acceptance_criteria": "...",
+      "priority": 0,
+      "category": "functional",
+      "depends_on": [],
+      "verify_command": "pytest -q"
+    }}
+  ]
+}}"""
+
+
+FORGE_REVISE_SYSTEM_PROMPT = """You are the Cognos Forge feature reviser.
+
+A feature in an autonomous coding pipeline has failed 3 times in a
+row. Your job is to look at the original feature and the failure
+logs, then output 1-5 NEW features that together accomplish the
+same goal but are more likely to succeed.
+
+Stack: {stack}
+
+Strategies:
+- If the original feature is too BIG, split it into smaller steps
+  (each step should be ~10-30 min of agent work, not 2 hours).
+- If the original feature's verify_command was the cause (wrong
+  binary, no tests yet, wrong path), rewrite the verify_command.
+  Prefer `python3` over `python`. Prefer narrow file checks
+  (`python3 -c "from app.main import app"`) over broad ones
+  (`pytest -q`) for foundation features.
+- If the original feature's description was ambiguous, rewrite it
+  to spell out the exact files and APIs expected.
+- If the failure logs show an environment issue (missing tool,
+  permission), DON'T retry the same way. Either change the
+  verify_command, change the description, or split out a
+  "set up environment X" preceding feature.
+
+Output the same JSON schema as a normal forge bootstrap:
+{{
+  "reasoning": "what you changed and why, 1-2 sentences",
+  "features": [
+    {{
+      "title": "short imperative",
+      "description": "what 'done' looks like, 1 paragraph",
+      "acceptance_criteria": "bullets",
+      "priority": 0,
+      "category": "functional",
+      "depends_on": [],
+      "verify_command": "shell command that exits 0 on success or null"
+    }}
+  ]
+}}
+
+Hard rule: produce 1-5 features. Use `python3` not `python`.
+If you really cannot improve the feature, output exactly one
+feature identical to the input — the orchestrator will park it.
+"""

planning/task_graph.py

@@ -0,0 +1,61 @@
+"""Task Graph — DAG-based task dependency management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.schemas import Task, TaskStatus
+
+
+class TaskGraph:
+    """Directed Acyclic Graph of tasks with dependency tracking."""
+
+    def __init__(self, tasks: list[Task] | None = None):
+        self._tasks: dict[str, Task] = {}
+        if tasks:
+            for task in tasks:
+                self._tasks[task.id] = task
+
+    def add_task(self, task: Task) -> None:
+        self._tasks[task.id] = task
+
+    def get_task(self, task_id: str) -> Task | None:
+        return self._tasks.get(task_id)
+
+    def get_ready_tasks(self) -> list[Task]:
+        """Return tasks whose dependencies are all completed."""
+        completed = {tid for tid, t in self._tasks.items() if t.status == TaskStatus.COMPLETED}
+        return [
+            t for t in self._tasks.values()
+            if t.status == TaskStatus.PENDING
+            and all(dep in completed for dep in t.dependencies)
+        ]
+
+    def mark_completed(self, task_id: str, result: Any = None) -> None:
+        if task_id in self._tasks:
+            self._tasks[task_id].status = TaskStatus.COMPLETED
+            self._tasks[task_id].result = result
+
+    def mark_failed(self, task_id: str, error: str) -> None:
+        if task_id in self._tasks:
+            self._tasks[task_id].status = TaskStatus.FAILED
+            self._tasks[task_id].error = error
+
+    def is_complete(self) -> bool:
+        return all(t.status == TaskStatus.COMPLETED for t in self._tasks.values())
+
+    def has_failed(self) -> bool:
+        return any(t.status == TaskStatus.FAILED for t in self._tasks.values())
+
+    def failed_tasks(self) -> list[Task]:
+        return [t for t in self._tasks.values() if t.status == TaskStatus.FAILED]
+
+    def all_tasks(self) -> list[Task]:
+        return list(self._tasks.values())
+
+    def summary(self) -> str:
+        lines = []
+        for t in self._tasks.values():
+            deps = f" (deps: {t.dependencies})" if t.dependencies else ""
+            lines.append(f"  [{t.status.value}] {t.description}{deps}")
+        return "\n".join(lines)

reflection/meta_learner.py

@@ -0,0 +1,156 @@
+"""Meta-Learner — adapts strategies based on reflection history (self-improvement)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from config import STRATEGY_UPDATE_INTERVAL
+from core.schemas import Reflection, Strategy
+from llm.provider import LLMProvider
+from memory.procedural import ProceduralMemory
+
+logger = logging.getLogger(__name__)
+
+
+class NewStrategyOutput(BaseModel):
+    name: str
+    description: str
+    conditions: str
+    actions: str
+    confidence: float = Field(default=0.5, ge=0.0, le=1.0)
+
+
+class StrategyUpdateOutput(BaseModel):
+    id: str
+    confidence_delta: float = Field(default=0.0, ge=-1.0, le=1.0)
+    reason: str = ""
+
+
+class StrategyOutput(BaseModel):
+    """LLM-emitted strategy extraction result."""
+    new_strategies: list[NewStrategyOutput] = Field(default_factory=list)
+    strategy_updates: list[StrategyUpdateOutput] = Field(default_factory=list)
+
+STRATEGY_PROMPT = """You are the meta-learning module of a cognitive architecture.
+Analyze recent performance and extract or update strategies.
+
+Recent reflections:
+{reflections}
+
+Existing strategies:
+{strategies}
+
+Based on the patterns in these reflections, suggest new strategies or updates.
+Each strategy should capture a reusable heuristic.
+
+Respond with JSON:
+{{
+  "new_strategies": [
+    {{
+      "name": "short name",
+      "description": "what this strategy does",
+      "conditions": "when to apply it",
+      "actions": "what to do",
+      "confidence": 0.0 to 1.0
+    }}
+  ],
+  "strategy_updates": [
+    {{
+      "id": "existing strategy id",
+      "confidence_delta": -0.1 to 0.1,
+      "reason": "why update"
+    }}
+  ]
+}}"""
+
+
+class MetaLearner:
+    """Learns from reflection history to adapt agent strategies over time."""
+
+    def __init__(self, llm: LLMProvider, procedural_memory: ProceduralMemory):
+        self.llm = llm
+        self.procedural = procedural_memory
+        self._reflection_buffer: list[Reflection] = []
+
+    def add_reflection(self, reflection: Reflection) -> None:
+        """Buffer a reflection for periodic strategy updates."""
+        self._reflection_buffer.append(reflection)
+
+    async def maybe_update_strategies(self) -> list[Strategy]:
+        """Update strategies if enough reflections have accumulated."""
+        if len(self._reflection_buffer) < STRATEGY_UPDATE_INTERVAL:
+            return []
+
+        new_strategies = await self._extract_strategies()
+        self._reflection_buffer.clear()
+        return new_strategies
+
+    async def force_update(self) -> list[Strategy]:
+        """Force a strategy update regardless of buffer size."""
+        if not self._reflection_buffer:
+            return []
+        new_strategies = await self._extract_strategies()
+        self._reflection_buffer.clear()
+        return new_strategies
+
+    async def _extract_strategies(self) -> list[Strategy]:
+        """Use LLM to extract strategies from reflection buffer."""
+        reflections_text = "\n".join(
+            f"- Score: {r.score}, Lesson: {r.lesson}, Worked: {r.what_worked}, Failed: {r.what_failed}"
+            for r in self._reflection_buffer
+        )
+
+        existing = self.procedural.get_strategies()
+        strategies_text = "\n".join(
+            f"- [{s.id}] {s.name} (confidence: {s.confidence:.2f}): {s.description}"
+            for s in existing
+        ) or "No existing strategies."
+
+        prompt = STRATEGY_PROMPT.format(
+            reflections=reflections_text,
+            strategies=strategies_text,
+        )
+
+        try:
+            data = await self.llm.structured_output(
+                prompt=prompt, response_model=StrategyOutput,
+                caller="meta",
+            )
+
+            new_strategies = []
+            for raw in data.new_strategies:
+                strategy = Strategy(
+                    name=raw.name,
+                    description=raw.description,
+                    conditions=raw.conditions,
+                    actions=raw.actions,
+                    confidence=raw.confidence,
+                )
+                self.procedural.store_strategy(strategy)
+                new_strategies.append(strategy)
+                logger.info(f"Learned new strategy: {strategy.name}")
+
+            # Apply updates to existing strategies
+            for update in data.strategy_updates:
+                for s in existing:
+                    if s.id == update.id:
+                        s.confidence = max(0.0, min(1.0, s.confidence + update.confidence_delta))
+                        self.procedural.store_strategy(s)
+                        logger.info(f"Updated strategy {s.name}: confidence {s.confidence:.2f}")
+
+            return new_strategies
+
+        except Exception as e:
+            logger.error(f"Meta-learning failed: {e}")
+            return []
+
+    def get_applicable_strategies(self, context: str) -> list[Strategy]:
+        """Get strategies that might apply to the current context.
+
+        For now, returns all strategies above minimum confidence.
+        Future: use embedding similarity on conditions.
+        """
+        return self.procedural.get_strategies(min_confidence=0.3)