claude-controller 0.1.2 → 0.3.0

package/cognitive/learning.py

@@ -0,0 +1,189 @@
+"""
+Learning Module — 자기 개선 엔진
+태스크 실행 결과를 분석하여 패턴을 추출하고,
+향후 계획·실행의 품질을 개선한다.
+
+학습 영역:
+  1. 프롬프트 최적화: 성공/실패 패턴 → 프롬프트 템플릿 개선
+  2. 시간/비용 추정: 과거 데이터 기반 정확도 향상
+  3. Worker 선택: 태스크 유형별 최적 Worker 매핑
+  4. 실패 패턴: 반복되는 실패 원인 축적 → 사전 회피
+"""
+
+import json
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+from memory.store import MemoryStore, MemoryType
+
+
+class LearningModule:
+    """태스크 실행 결과를 분석하여 시스템을 개선한다."""
+
+    def __init__(self, memory: MemoryStore, data_dir: str):
+        self.memory = memory
+        self.data_dir = Path(data_dir)
+        self.outcomes_dir = self.data_dir / "outcomes"
+        self.outcomes_dir.mkdir(parents=True, exist_ok=True)
+
+    def record_outcome(
+        self,
+        goal_id: str,
+        objective: str,
+        achieved: bool,
+        dag: dict,
+        cost_usd: float,
+        eval_report: dict,
+    ):
+        """목표 실행 결과를 기록한다."""
+        outcome = {
+            "goal_id": goal_id,
+            "objective": objective,
+            "achieved": achieved,
+            "cost_usd": cost_usd,
+            "task_count": len(dag.get("tasks", [])),
+            "eval_report": eval_report,
+            "timestamp": time.time(),
+            "tasks_summary": self._summarize_tasks(dag),
+        }
+
+        # 결과 파일 저장
+        path = self.outcomes_dir / f"{goal_id}.json"
+        with open(path, "w") as f:
+            json.dump(outcome, f, indent=2, ensure_ascii=False)
+
+        # 실패 패턴 → Memory에 축적
+        if not achieved:
+            self._learn_from_failure(outcome)
+
+        # 성공 패턴 → Memory에 축적
+        if achieved:
+            self._learn_from_success(outcome)
+
+    def get_cost_estimate(self, task_count: int) -> dict:
+        """과거 데이터 기반 비용/시간 추정."""
+        outcomes = self._load_recent_outcomes(limit=50)
+        if not outcomes:
+            return {
+                "estimated_cost_usd": task_count * 0.25,
+                "confidence": "low",
+                "basis": "기본 추정 (데이터 부족)",
+            }
+
+        # 태스크당 평균 비용 계산
+        total_cost = sum(o["cost_usd"] for o in outcomes)
+        total_tasks = sum(o["task_count"] for o in outcomes)
+
+        if total_tasks == 0:
+            cost_per_task = 0.25
+        else:
+            cost_per_task = total_cost / total_tasks
+
+        return {
+            "estimated_cost_usd": round(task_count * cost_per_task, 2),
+            "cost_per_task": round(cost_per_task, 3),
+            "confidence": "high" if len(outcomes) > 10 else "medium",
+            "basis": f"최근 {len(outcomes)}개 목표의 평균",
+        }
+
+    def get_success_rate(self) -> dict:
+        """전체 목표 성공률을 반환한다."""
+        outcomes = self._load_recent_outcomes(limit=100)
+        if not outcomes:
+            return {"rate": 0.0, "total": 0, "achieved": 0}
+
+        achieved = sum(1 for o in outcomes if o["achieved"])
+        return {
+            "rate": round(achieved / len(outcomes), 2),
+            "total": len(outcomes),
+            "achieved": achieved,
+        }
+
+    def get_failure_patterns(self, limit: int = 10) -> list[dict]:
+        """최근 실패 패턴을 반환한다."""
+        failures = self.memory.search(
+            query="",
+            memory_type=MemoryType.FAILURE,
+            limit=limit,
+        )
+        return failures
+
+    def _learn_from_failure(self, outcome: dict):
+        """실패로부터 패턴을 추출하여 Memory에 저장한다."""
+        failed_tasks = [
+            t for t in outcome.get("tasks_summary", [])
+            if t.get("status") == "failed"
+        ]
+
+        if not failed_tasks:
+            return
+
+        # 실패 태스크의 Worker 유형과 실패 원인 축적
+        for task in failed_tasks:
+            self.memory.add(
+                memory_type=MemoryType.FAILURE,
+                title=f"실패: {task.get('name', 'unknown')}",
+                content=(
+                    f"목표: {outcome['objective']}\n"
+                    f"태스크: {task.get('name')}\n"
+                    f"Worker: {task.get('worker_type')}\n"
+                    f"재시도: {task.get('retries', 0)}회\n"
+                    f"비용: ${task.get('cost_usd', 0)}"
+                ),
+                tags=[
+                    task.get("worker_type", "unknown"),
+                    "failure",
+                    outcome["goal_id"],
+                ],
+                goal_id=outcome["goal_id"],
+            )
+
+    def _learn_from_success(self, outcome: dict):
+        """성공으로부터 패턴을 추출한다."""
+        # 효율적인 DAG 구조 기록 (비용이 평균 이하인 경우)
+        avg_cost = self._get_avg_cost()
+        if avg_cost > 0 and outcome["cost_usd"] < avg_cost * 0.7:
+            self.memory.add(
+                memory_type=MemoryType.PATTERN,
+                title=f"효율적 패턴: {outcome['objective'][:50]}",
+                content=(
+                    f"목표: {outcome['objective']}\n"
+                    f"태스크 수: {outcome['task_count']}\n"
+                    f"비용: ${outcome['cost_usd']} (평균 ${avg_cost:.2f} 대비 절약)\n"
+                    f"DAG 구조: {len(outcome.get('tasks_summary', []))} 태스크"
+                ),
+                tags=["efficient", "cost_saving", outcome["goal_id"]],
+                goal_id=outcome["goal_id"],
+            )
+
+    def _summarize_tasks(self, dag: dict) -> list[dict]:
+        """DAG의 태스크들을 요약한다."""
+        return [
+            {
+                "id": t.get("id"),
+                "name": t.get("name"),
+                "worker_type": t.get("worker_type"),
+                "status": t.get("status"),
+                "cost_usd": t.get("cost_usd", 0),
+                "retries": t.get("retries", 0),
+            }
+            for t in dag.get("tasks", [])
+        ]
+
+    def _load_recent_outcomes(self, limit: int = 50) -> list[dict]:
+        """최근 실행 결과를 로드한다."""
+        outcomes = []
+        paths = sorted(self.outcomes_dir.glob("goal-*.json"), reverse=True)
+        for path in paths[:limit]:
+            with open(path) as f:
+                outcomes.append(json.load(f))
+        return outcomes
+
+    def _get_avg_cost(self) -> float:
+        """전체 평균 비용을 계산한다."""
+        outcomes = self._load_recent_outcomes(limit=50)
+        if not outcomes:
+            return 0.0
+        return sum(o["cost_usd"] for o in outcomes) / len(outcomes)

package/cognitive/orchestrator.py

@@ -0,0 +1,303 @@
+"""
+Orchestrator — 인지 루프의 두뇌
+Goal Engine, Planner, Dispatcher, Evaluator, Memory를 조율하여
+목표를 자율적으로 달성하는 전체 라이프사이클을 관리한다.
+
+인지 루프:
+  Goal → Plan → Execute → Evaluate → [Learn] → Done/Retry
+"""
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Optional
+
+from cognitive.goal_engine import GoalEngine, GoalStatus, ExecutionMode
+from cognitive.planner import Planner
+from cognitive.dispatcher import Dispatcher
+from cognitive.evaluator import Evaluator
+from cognitive.learning import LearningModule
+from memory.store import MemoryStore, MemoryType
+from dag.graph import TaskDAG
+
+logger = logging.getLogger("orchestrator")
+
+
+class Orchestrator:
+    """인지 루프를 구동하는 최상위 조율기.
+
+    사용법:
+        orch = Orchestrator(base_dir="/path/to/controller")
+        goal = orch.set_goal("API 응답 시간 50% 단축", cwd="/project")
+        orch.run(goal["id"])  # 자율 실행
+    """
+
+    def __init__(self, base_dir: str, claude_bin: str = "claude"):
+        self.base_dir = Path(base_dir)
+        self.claude_bin = claude_bin
+
+        # 핵심 컴포넌트 초기화
+        self.goal_engine = GoalEngine(str(self.base_dir / "data"))
+        self.memory = MemoryStore(str(self.base_dir / "memory"))
+        self.planner = Planner(claude_bin)
+        self.evaluator = None  # cwd 설정 후 초기화
+        self.learning = LearningModule(
+            memory=self.memory,
+            data_dir=str(self.base_dir / "data" / "learning"),
+        )
+
+        self._dispatcher = None
+
+    def set_goal(
+        self,
+        objective: str,
+        cwd: str,
+        mode: str = "gate",
+        budget_usd: float = 5.0,
+        max_tasks: int = 20,
+    ) -> dict:
+        """새 목표를 설정한다.
+
+        Returns:
+            생성된 목표 dict
+        """
+        exec_mode = ExecutionMode(mode)
+        context = {"cwd": cwd}
+
+        goal = self.goal_engine.create_goal(
+            objective=objective,
+            mode=exec_mode,
+            context=context,
+            budget_usd=budget_usd,
+            max_tasks=max_tasks,
+        )
+
+        logger.info(f"Goal created: {goal['id']} — {objective}")
+        return goal
+
+    def plan(self, goal_id: str) -> dict:
+        """목표에 대한 실행 계획(DAG)을 생성한다.
+
+        Returns:
+            DAG 정보가 포함된 업데이트된 목표 dict
+        """
+        goal = self.goal_engine.get_goal(goal_id)
+        if not goal:
+            raise ValueError(f"Goal not found: {goal_id}")
+
+        cwd = goal["context"].get("cwd", ".")
+        self.goal_engine.update_status(goal_id, GoalStatus.PLANNING)
+
+        # 관련 메모리 수집
+        memories = self.memory.get_relevant(
+            goal["objective"],
+            project=cwd,
+        )
+
+        # Planner 호출
+        dag, criteria = self.planner.create_plan(
+            objective=goal["objective"],
+            cwd=cwd,
+            memory_context=memories,
+            max_tasks=goal["max_tasks"],
+        )
+
+        # DAG를 Goal에 연결
+        goal = self.goal_engine.attach_dag(
+            goal_id,
+            dag=dag.to_dict(),
+            success_criteria=criteria,
+        )
+
+        logger.info(
+            f"Plan created for {goal_id}: "
+            f"{len(dag.nodes)} tasks, {len(criteria)} criteria"
+        )
+        return goal
+
+    def execute(self, goal_id: str) -> dict:
+        """계획된 DAG를 실행한다.
+
+        Returns:
+            실행 완료된 목표 dict
+        """
+        goal = self.goal_engine.get_goal(goal_id)
+        if not goal or not goal["dag"]:
+            raise ValueError(f"Goal not found or no plan: {goal_id}")
+
+        cwd = goal["context"].get("cwd", ".")
+        self.goal_engine.update_status(goal_id, GoalStatus.RUNNING)
+
+        # Dispatcher 초기화
+        dispatcher = Dispatcher(
+            claude_bin=self.claude_bin,
+            logs_dir=str(self.base_dir / "logs" / "goals"),
+            prompts_dir=str(self.base_dir / "cognitive" / "prompts"),
+            max_concurrent=5,
+            on_task_complete=lambda tid, cost: self.goal_engine.update_task_status(
+                goal_id, tid, "completed", cost
+            ),
+            on_task_fail=lambda tid, cost: self.goal_engine.update_task_status(
+                goal_id, tid, "failed", cost
+            ),
+        )
+
+        # DAG 실행
+        dag = TaskDAG.from_dict(goal["dag"])
+        completed_dag = dispatcher.run_dag(dag, cwd, goal_id)
+
+        # DAG 상태를 Goal에 반영
+        goal["dag"] = completed_dag.to_dict()
+        goal["updated_at"] = time.time()
+        self.goal_engine._save_goal(goal)
+
+        logger.info(f"Execution completed for {goal_id}")
+        return goal
+
+    def evaluate(self, goal_id: str) -> dict:
+        """실행 결과를 평가하고 목표 달성 여부를 판단한다.
+
+        Returns:
+            { "achieved": bool, "report": EvaluationReport, "goal": dict }
+        """
+        goal = self.goal_engine.get_goal(goal_id)
+        if not goal:
+            raise ValueError(f"Goal not found: {goal_id}")
+
+        cwd = goal["context"].get("cwd", ".")
+        self.goal_engine.update_status(goal_id, GoalStatus.EVALUATING)
+
+        evaluator = Evaluator(self.claude_bin, cwd)
+
+        # 성공 기준 검증
+        eval_report = evaluator.evaluate_goal(
+            goal_id=goal_id,
+            success_criteria=goal.get("success_criteria", []),
+        )
+
+        # 태스크 완료 상태 검증
+        completion = self.goal_engine.evaluate_completion(goal_id)
+
+        result = {
+            "achieved": completion["achieved"] and eval_report.overall_pass,
+            "report": eval_report.to_dict(),
+            "completion": completion,
+            "goal": self.goal_engine.get_goal(goal_id),
+        }
+
+        # 학습
+        self.learning.record_outcome(
+            goal_id=goal_id,
+            objective=goal["objective"],
+            achieved=result["achieved"],
+            dag=goal["dag"],
+            cost_usd=goal["progress"]["cost_usd"],
+            eval_report=eval_report.to_dict(),
+        )
+
+        return result
+
+    def run(self, goal_id: str) -> dict:
+        """인지 루프 전체를 실행한다: Plan → Execute → Evaluate.
+
+        Gate 모드에서는 각 단계 후 반환하여 사용자 승인을 기다린다.
+        Full Auto 모드에서는 끝까지 자율 실행한다.
+
+        Returns:
+            최종 평가 결과
+        """
+        goal = self.goal_engine.get_goal(goal_id)
+        if not goal:
+            raise ValueError(f"Goal not found: {goal_id}")
+
+        mode = goal.get("mode", "gate")
+
+        # Phase 1: Plan
+        goal = self.plan(goal_id)
+
+        if mode == ExecutionMode.GATE.value:
+            self.goal_engine.update_status(goal_id, GoalStatus.GATE_WAITING)
+            return {
+                "phase": "plan_complete",
+                "message": "계획이 생성되었습니다. 승인 후 실행을 시작합니다.",
+                "goal": goal,
+            }
+
+        # Phase 2: Execute
+        goal = self.execute(goal_id)
+
+        if mode == ExecutionMode.GATE.value:
+            self.goal_engine.update_status(goal_id, GoalStatus.GATE_WAITING)
+            return {
+                "phase": "execute_complete",
+                "message": "실행이 완료되었습니다. 평가를 시작하려면 승인하세요.",
+                "goal": goal,
+            }
+
+        # Phase 3: Evaluate
+        result = self.evaluate(goal_id)
+
+        return {
+            "phase": "done",
+            "message": "목표 달성" if result["achieved"] else "목표 미달성",
+            **result,
+        }
+
+    def approve_gate(self, goal_id: str) -> dict:
+        """Gate 모드에서 다음 단계를 승인한다."""
+        goal = self.goal_engine.get_goal(goal_id)
+        if not goal:
+            raise ValueError(f"Goal not found: {goal_id}")
+
+        if goal["status"] != GoalStatus.GATE_WAITING.value:
+            return {"error": "현재 승인 대기 상태가 아닙니다."}
+
+        # 현재 단계 판단
+        dag = goal.get("dag")
+        if dag is None:
+            # 계획이 아직 없음 → 오류
+            return {"error": "계획이 없습니다. plan을 먼저 실행하세요."}
+
+        tasks = dag.get("tasks", [])
+        any_running = any(t.get("status") == "running" for t in tasks)
+        all_done = all(t.get("status") in ("completed", "failed") for t in tasks)
+
+        if not any_running and not all_done:
+            # 계획 수립 완료 → 실행 단계로 진입
+            return self.execute(goal_id)
+        elif all_done:
+            # 실행 완료 → 평가 단계로 진입
+            return self.evaluate(goal_id)
+        else:
+            return {"error": "태스크가 아직 실행 중입니다."}
+
+    def get_status(self, goal_id: str) -> dict:
+        """목표의 현재 상태를 반환한다."""
+        goal = self.goal_engine.get_goal(goal_id)
+        if not goal:
+            return {"error": "Goal not found"}
+
+        dag_info = None
+        if goal["dag"]:
+            dag = TaskDAG.from_dict(goal["dag"])
+            dag_info = {
+                "total": len(dag.nodes),
+                "completed": sum(1 for n in dag.nodes.values() if n.status == "completed"),
+                "running": sum(1 for n in dag.nodes.values() if n.status == "running"),
+                "failed": sum(1 for n in dag.nodes.values() if n.status == "failed"),
+                "pending": sum(1 for n in dag.nodes.values() if n.status == "pending"),
+                "mermaid": dag.to_mermaid(),
+            }
+
+        return {
+            "goal": {
+                "id": goal["id"],
+                "objective": goal["objective"],
+                "status": goal["status"],
+                "mode": goal["mode"],
+                "progress": goal["progress"],
+                "created_at": goal["created_at"],
+            },
+            "dag": dag_info,
+        }

package/cognitive/planner.py

@@ -0,0 +1,207 @@
+"""
+Planner — 목표를 실행 가능한 태스크 DAG로 변환
+Claude를 사용하여 목표를 분석하고, 태스크를 분해하며, 의존성을 추론한다.
+
+동작 방식:
+  1. Goal + 코드베이스 맥락 + Memory를 수집
+  2. Claude -p에게 구조화된 프롬프트로 DAG 생성 요청
+  3. 응답 JSON을 파싱하여 TaskDAG 객체 생성
+  4. DAG 유효성 검증 후 Goal에 연결
+"""
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+from typing import Optional
+
+from dag.graph import TaskDAG, TaskNode
+
+
+PLANNER_SYSTEM_PROMPT = """당신은 소프트웨어 개발 프로젝트의 태스크 플래너입니다.
+
+주어진 목표(Goal)를 분석하여 실행 가능한 태스크들로 분해하고,
+각 태스크 간의 의존성을 DAG(방향성 비순환 그래프)로 구성합니다.
+
+## 규칙
+
+1. 각 태스크는 하나의 Claude headless 세션에서 완료 가능한 크기여야 한다
+2. 태스크 간 의존성을 명확히 정의한다 (같은 파일 수정 시 직렬화)
+3. 병렬 실행 가능한 태스크는 가능한 병렬로 구성한다
+4. Worker 유형을 적절히 배정한다: analyst, coder, tester, reviewer, writer
+5. 총 태스크 수는 {max_tasks}개 이하로 유지한다
+6. 각 태스크의 프롬프트는 구체적이고 실행 가능해야 한다
+
+## Worker 유형
+
+- **analyst**: 코드 분석, 구조 파악, 영향 범위 조사 (읽기 전용)
+- **coder**: 코드 작성/수정 (쓰기 작업)
+- **tester**: 테스트 작성 및 실행
+- **reviewer**: 코드 리뷰, 품질 검증
+- **writer**: 문서 작성
+
+## 출력 형식
+
+반드시 아래 JSON 형식으로만 응답하세요:
+
+```json
+{{
+  "success_criteria": ["기준1", "기준2"],
+  "tasks": [
+    {{
+      "id": "t1",
+      "name": "짧은 태스크 이름",
+      "worker_type": "analyst|coder|tester|reviewer|writer",
+      "prompt": "구체적인 실행 프롬프트",
+      "depends_on": []
+    }},
+    {{
+      "id": "t2",
+      "name": "다음 태스크",
+      "worker_type": "coder",
+      "prompt": "구체적인 프롬프트",
+      "depends_on": ["t1"]
+    }}
+  ]
+}}
+```
+"""
+
+
+class Planner:
+    """목표를 태스크 DAG로 변환하는 계획 엔진."""
+
+    def __init__(self, claude_bin: str, config: Optional[dict] = None):
+        self.claude_bin = claude_bin
+        self.config = config or {}
+        self.prompts_dir = Path(__file__).parent / "prompts"
+
+    def create_plan(
+        self,
+        objective: str,
+        cwd: str,
+        memory_context: list[dict] = None,
+        max_tasks: int = 20,
+    ) -> tuple[TaskDAG, list[str]]:
+        """목표로부터 태스크 DAG를 생성한다.
+
+        Args:
+            objective: 자연어 목표
+            cwd: 작업 디렉토리
+            memory_context: 관련 메모리 목록
+            max_tasks: 최대 태스크 수
+
+        Returns:
+            (TaskDAG, success_criteria)
+        """
+        prompt = self._build_prompt(objective, cwd, memory_context, max_tasks)
+        response = self._call_claude(prompt, cwd)
+        dag, criteria = self._parse_response(response)
+        return dag, criteria
+
+    def _build_prompt(
+        self,
+        objective: str,
+        cwd: str,
+        memory_context: Optional[list[dict]],
+        max_tasks: int,
+    ) -> str:
+        """Planner용 프롬프트를 조립한다."""
+        parts = [
+            f"# 목표\n{objective}\n",
+            f"# 작업 디렉토리\n{cwd}\n",
+        ]
+
+        if memory_context:
+            parts.append("# 관련 지식 (Memory)\n")
+            for mem in memory_context[:5]:
+                parts.append(
+                    f"- [{mem['type']}] {mem['title']}: {mem['content'][:200]}\n"
+                )
+
+        parts.append(
+            f"\n위 목표를 달성하기 위한 태스크 DAG를 생성하세요. "
+            f"최대 {max_tasks}개 태스크로 제한합니다."
+        )
+
+        return "\n".join(parts)
+
+    def _call_claude(self, prompt: str, cwd: str) -> str:
+        """Claude headless를 호출하여 계획을 생성한다."""
+        system_prompt = PLANNER_SYSTEM_PROMPT.format(
+            max_tasks=self.config.get("max_tasks", 20)
+        )
+
+        cmd = [
+            self.claude_bin,
+            "-p", prompt,
+            "--output-format", "json",
+            "--allowedTools", "Read,Glob,Grep,Bash",
+        ]
+
+        if system_prompt:
+            cmd.extend(["--append-system-prompt", system_prompt])
+
+        env = os.environ.copy()
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            env=env,
+            timeout=300,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Planner claude call failed: {result.stderr[:500]}")
+
+        return result.stdout
+
+    def _parse_response(self, response: str) -> tuple[TaskDAG, list[str]]:
+        """Claude 응답에서 DAG를 파싱한다."""
+        # JSON 블록 추출 (```json ... ``` 또는 순수 JSON)
+        text = response.strip()
+
+        # output-format json일 경우 최상위 JSON 파싱
+        try:
+            outer = json.loads(text)
+            if "result" in outer:
+                text = outer["result"]
+            elif "content" in outer:
+                # content 배열에서 텍스트 추출
+                for block in outer.get("content", []):
+                    if block.get("type") == "text":
+                        text = block["text"]
+                        break
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+        # ```json``` 블록 추출
+        if "```json" in text:
+            start = text.index("```json") + 7
+            end = text.index("```", start)
+            text = text[start:end].strip()
+        elif "```" in text:
+            start = text.index("```") + 3
+            end = text.index("```", start)
+            text = text[start:end].strip()
+
+        data = json.loads(text)
+        criteria = data.get("success_criteria", [])
+
+        dag = TaskDAG()
+        for td in data.get("tasks", []):
+            dag.add_task(TaskNode(
+                task_id=td["id"],
+                name=td["name"],
+                worker_type=td["worker_type"],
+                prompt=td["prompt"],
+                depends_on=td.get("depends_on", []),
+            ))
+
+        valid, msg = dag.validate()
+        if not valid:
+            raise ValueError(f"Invalid DAG: {msg}")
+
+        return dag, criteria