devcouncil 0.1.0 → 0.1.1

package/src/devcouncil/llm/router.py

@@ -1,58 +1,58 @@
-from typing import List, Dict, Any, Type, Optional
-import copy
-import json
-import logging
-import asyncio
-from pathlib import Path
-
-from pydantic import BaseModel
-from devcouncil.llm.provider import Provider
-from devcouncil.llm.cache import LLMCache
-from devcouncil.telemetry.tracker import TelemetryTracker
-
-logger = logging.getLogger(__name__)
-
-class ModelRouter:
-    def __init__(self, provider: Provider, role_config: Dict[str, Dict[str, Any]]):
-        self.provider = provider
-        self.role_config = role_config
-
-    async def complete_structured(
-        self,
-        role: str,
-        messages: List[Dict[str, str]],
-        schema: Type[BaseModel],
-        temperature: Optional[float] = None,
-        run_id: Optional[str] = None,
-    ) -> BaseModel:
-        config = self.role_config.get(role)
-        if not config:
-            raise ValueError(f"No config found for role: {role}")
-        
-        model = config["model"]
-        temp = temperature if temperature is not None else config.get("temperature", 0.0)
-        
-        # Deep-copy to avoid mutating the caller's messages list
-        msgs = copy.deepcopy(messages)
-        
-        # Add schema instructions to system or user message
-        schema_json = json.dumps(schema.model_json_schema(), indent=2)
-        instruction = f"\n\nYou MUST output a JSON object matching this schema:\n{schema_json}"
-        
-        found_system = False
-        for msg in msgs:
-            if msg["role"] == "system":
-                msg["content"] += instruction
-                found_system = True
-                break
-        
-        if not found_system:
-            msgs.insert(0, {"role": "system", "content": f"You are a helpful assistant.{instruction}"})
-
-        logger.info("LLM call: role=%s model=%s run_id=%s", role, model, run_id)
-
-        project_root = Path(".")
-        cache = LLMCache(project_root)
+from typing import List, Dict, Any, Type, Optional
+import copy
+import json
+import logging
+import asyncio
+from pathlib import Path
+
+from pydantic import BaseModel
+from devcouncil.llm.provider import Provider
+from devcouncil.llm.cache import LLMCache
+from devcouncil.telemetry.tracker import TelemetryTracker
+
+logger = logging.getLogger(__name__)
+
+class ModelRouter:
+    def __init__(self, provider: Provider, role_config: Dict[str, Dict[str, Any]]):
+        self.provider = provider
+        self.role_config = role_config
+
+    async def complete_structured(
+        self,
+        role: str,
+        messages: List[Dict[str, str]],
+        schema: Type[BaseModel],
+        temperature: Optional[float] = None,
+        run_id: Optional[str] = None,
+    ) -> BaseModel:
+        config = self.role_config.get(role)
+        if not config:
+            raise ValueError(f"No config found for role: {role}")
+        
+        model = config["model"]
+        temp = temperature if temperature is not None else config.get("temperature", 0.0)
+        
+        # Deep-copy to avoid mutating the caller's messages list
+        msgs = copy.deepcopy(messages)
+        
+        # Add schema instructions to system or user message
+        schema_json = json.dumps(schema.model_json_schema(), indent=2)
+        instruction = f"\n\nYou MUST output a JSON object matching this schema:\n{schema_json}"
+        
+        found_system = False
+        for msg in msgs:
+            if msg["role"] == "system":
+                msg["content"] += instruction
+                found_system = True
+                break
+        
+        if not found_system:
+            msgs.insert(0, {"role": "system", "content": f"You are a helpful assistant.{instruction}"})
+
+        logger.info("LLM call: role=%s model=%s run_id=%s", role, model, run_id)
+
+        project_root = Path(".")
+        cache = LLMCache(project_root)
         tracker = TelemetryTracker(project_root)
 
         # Check cache first
@@ -62,64 +62,64 @@ class ModelRouter:
         if not response:
             for attempt in range(3):
                 try:
-                    response = await self.provider.complete(
-                        model=model,
-                        messages=msgs,
-                        temperature=temp,
-                        json_mode=True
-                    )
-                    cache.set(model, msgs, temp, True, response)
-                    break
-                except Exception as e:
-                    if attempt == 2:
-                        raise
+                    response = await self.provider.complete(
+                        model=model,
+                        messages=msgs,
+                        temperature=temp,
+                        json_mode=True
+                    )
+                    cache.set(model, msgs, temp, True, response)
+                    break
+                except Exception as e:
+                    if attempt == 2:
+                        raise
                     logger.warning(f"LLM request failed (attempt {attempt+1}): {e}. Retrying...")
                     await asyncio.sleep(2 ** attempt)
 
         if not cache_hit:
             tracker.log_usage(model, response.usage)
-
-        logger.info(
-            "LLM response: role=%s model=%s tokens=%s",
-            role, response.model, response.usage,
-        )
-        
-        try:
-            # Attempt to find JSON block if it's wrapped in markdown
-            content = response.content.strip()
-            if "```json" in content:
-                content = content.split("```json")[1].split("```")[0].strip()
-            elif "```" in content:
-                content = content.split("```")[1].split("```")[0].strip()
-                
-            data = json.loads(content)
-            return schema.model_validate(data)
-        except Exception as e:
-            logger.warning(f"Initial parse failed for {role}, attempting healing: {e}")
-            
-            # Healing attempt: Ask the model to fix its own JSON
-            healing_prompt = f"""
-The following JSON was returned but failed to parse or validate against the schema.
-Error: {str(e)}
-Content:
-{response.content}
-
-Please return the corrected JSON object only. No prose.
-"""
-            # We use a lower temperature for healing
-            healed_response = await self.provider.complete(
-                model=model,
-                messages=[{"role": "user", "content": healing_prompt}],
-                temperature=0.0,
-                json_mode=True
-            )
-            
-            try:
-                healed_content = healed_response.content.strip()
-                if "```json" in healed_content:
-                    healed_content = healed_content.split("```json")[1].split("```")[0].strip()
-                data = json.loads(healed_content)
-                return schema.model_validate(data)
-            except Exception as final_e:
-                logger.error(f"Healing failed for {role}: {final_e}")
-                raise ValueError(f"Failed to parse or validate LLM response after healing: {final_e}\nContent (truncated): {response.content[:200]}...")
+
+        logger.info(
+            "LLM response: role=%s model=%s tokens=%s",
+            role, response.model, response.usage,
+        )
+        
+        try:
+            # Attempt to find JSON block if it's wrapped in markdown
+            content = response.content.strip()
+            if "```json" in content:
+                content = content.split("```json")[1].split("```")[0].strip()
+            elif "```" in content:
+                content = content.split("```")[1].split("```")[0].strip()
+                
+            data = json.loads(content)
+            return schema.model_validate(data)
+        except Exception as e:
+            logger.warning(f"Initial parse failed for {role}, attempting healing: {e}")
+            
+            # Healing attempt: Ask the model to fix its own JSON
+            healing_prompt = f"""
+The following JSON was returned but failed to parse or validate against the schema.
+Error: {str(e)}
+Content:
+{response.content}
+
+Please return the corrected JSON object only. No prose.
+"""
+            # We use a lower temperature for healing
+            healed_response = await self.provider.complete(
+                model=model,
+                messages=[{"role": "user", "content": healing_prompt}],
+                temperature=0.0,
+                json_mode=True
+            )
+            
+            try:
+                healed_content = healed_response.content.strip()
+                if "```json" in healed_content:
+                    healed_content = healed_content.split("```json")[1].split("```")[0].strip()
+                data = json.loads(healed_content)
+                return schema.model_validate(data)
+            except Exception as final_e:
+                logger.error(f"Healing failed for {role}: {final_e}")
+                raise ValueError(f"Failed to parse or validate LLM response after healing: {final_e}\nContent (truncated): {response.content[:200]}...")

package/src/devcouncil/planning/__init__.py

@@ -1 +1 @@
-
+

package/src/devcouncil/planning/arbiter_service.py

@@ -1,57 +1,57 @@
-from typing import List, Dict
-from pydantic import BaseModel
-from devcouncil.domain.requirement import Requirement
-from devcouncil.domain.task import Task
-from devcouncil.llm.router import ModelRouter
-
-class ArbiterDecision(BaseModel):
-    accepted_finding_ids: List[str]
-    rejected_finding_ids: List[Dict[str, str]] # id, reason
-    final_requirements: List[Requirement]
-    final_tasks: List[Task]
-
-class ArbiterService:
-    def __init__(self, router: ModelRouter):
-        self.router = router
-
-    async def arbitrate(
-        self, 
-        goal: str, 
-        requirements_json: str, 
-        plan_a_json: str, 
-        plan_b_json: str, 
-        critique_a_json: str, 
-        critique_b_json: str,
-        rebuttal_a_json: str,
-        rebuttal_b_json: str
-    ) -> ArbiterDecision:
-        prompt = f"""
-Goal: {goal}
-
-Initial Requirements:
-{requirements_json}
-
-Plan A: {plan_a_json}
-Plan B: {plan_b_json}
-
-Critique of Plan B by Critic A: {critique_a_json}
-Critique of Plan A by Critic B: {critique_b_json}
-
-Rebuttal of Critic B by Planner A: {rebuttal_a_json}
-Rebuttal of Critic A by Planner B: {rebuttal_b_json}
-
-You are the arbiter engineering manager. Your goal is to produce the final, definitive set of requirements and tasks.
-- You do not decide by vibes.
-- High-severity unrefuted findings from critics must be incorporated into the final requirements or tasks.
-- If a planner successfully rebutted a finding, you may skip it.
-- Produce a single, coherent task graph.
-"""
-        messages = [
-            {"role": "user", "content": prompt}
-        ]
-        
-        return await self.router.complete_structured(
-            role="arbiter",
-            messages=messages,
-            schema=ArbiterDecision
-        )
+from typing import List, Dict
+from pydantic import BaseModel
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.task import Task
+from devcouncil.llm.router import ModelRouter
+
+class ArbiterDecision(BaseModel):
+    accepted_finding_ids: List[str]
+    rejected_finding_ids: List[Dict[str, str]] # id, reason
+    final_requirements: List[Requirement]
+    final_tasks: List[Task]
+
+class ArbiterService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def arbitrate(
+        self, 
+        goal: str, 
+        requirements_json: str, 
+        plan_a_json: str, 
+        plan_b_json: str, 
+        critique_a_json: str, 
+        critique_b_json: str,
+        rebuttal_a_json: str,
+        rebuttal_b_json: str
+    ) -> ArbiterDecision:
+        prompt = f"""
+Goal: {goal}
+
+Initial Requirements:
+{requirements_json}
+
+Plan A: {plan_a_json}
+Plan B: {plan_b_json}
+
+Critique of Plan B by Critic A: {critique_a_json}
+Critique of Plan A by Critic B: {critique_b_json}
+
+Rebuttal of Critic B by Planner A: {rebuttal_a_json}
+Rebuttal of Critic A by Planner B: {rebuttal_b_json}
+
+You are the arbiter engineering manager. Your goal is to produce the final, definitive set of requirements and tasks.
+- You do not decide by vibes.
+- High-severity unrefuted findings from critics must be incorporated into the final requirements or tasks.
+- If a planner successfully rebutted a finding, you may skip it.
+- Produce a single, coherent task graph.
+"""
+        messages = [
+            {"role": "user", "content": prompt}
+        ]
+        
+        return await self.router.complete_structured(
+            role="arbiter",
+            messages=messages,
+            schema=ArbiterDecision
+        )

package/src/devcouncil/planning/critique_service.py

@@ -1,66 +1,66 @@
-from typing import List
-from pydantic import BaseModel
-from devcouncil.domain.critique import CritiqueFinding
-from devcouncil.llm.router import ModelRouter
-
-class CritiqueOutput(BaseModel):
-    findings: List[CritiqueFinding]
-
-class RebuttalItem(BaseModel):
-    finding_id: str
-    decision: str # "accepted", "rejected"
-    reason: str
-    suggested_change: str | None = None
-
-class RebuttalOutput(BaseModel):
-    rebuttals: List[RebuttalItem]
-
-class CritiqueService:
-    def __init__(self, router: ModelRouter):
-        self.router = router
-
-    async def generate_critique(self, role: str, target_plan_json: str, requirements_json: str) -> CritiqueOutput:
-        prompt = f"""
-Requirements:
-{requirements_json}
-
-Target Plan:
-{target_plan_json}
-
-You are a hostile staff engineer reviewing another team's implementation plan.
-Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
-Do not praise. Do not rewrite the plan.
-Every finding must include a falsifiable_check.
-"""
-        messages = [
-            {"role": "user", "content": prompt}
-        ]
-        
-        return await self.router.complete_structured(
-            role=role,
-            messages=messages,
-            schema=CritiqueOutput
-        )
-
-    async def generate_rebuttal(self, role: str, original_plan_json: str, findings_json: str) -> RebuttalOutput:
-        prompt = f"""
-Original Plan:
-{original_plan_json}
-
-Critique Findings:
-{findings_json}
-
-You are the planner who created the original plan. Review the critique findings.
-- A finding can be rejected only with artifact evidence or strong justification.
-- A finding can be accepted and converted into a requirement/task/test.
-- No hand-wavy rebuttals.
-"""
-        messages = [
-            {"role": "user", "content": prompt}
-        ]
-        
-        return await self.router.complete_structured(
-            role=role,
-            messages=messages,
-            schema=RebuttalOutput
-        )
+from typing import List
+from pydantic import BaseModel
+from devcouncil.domain.critique import CritiqueFinding
+from devcouncil.llm.router import ModelRouter
+
+class CritiqueOutput(BaseModel):
+    findings: List[CritiqueFinding]
+
+class RebuttalItem(BaseModel):
+    finding_id: str
+    decision: str # "accepted", "rejected"
+    reason: str
+    suggested_change: str | None = None
+
+class RebuttalOutput(BaseModel):
+    rebuttals: List[RebuttalItem]
+
+class CritiqueService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def generate_critique(self, role: str, target_plan_json: str, requirements_json: str) -> CritiqueOutput:
+        prompt = f"""
+Requirements:
+{requirements_json}
+
+Target Plan:
+{target_plan_json}
+
+You are a hostile staff engineer reviewing another team's implementation plan.
+Find missing requirements, bad assumptions, missing tests, security risks, migration risks, and unverifiable claims.
+Do not praise. Do not rewrite the plan.
+Every finding must include a falsifiable_check.
+"""
+        messages = [
+            {"role": "user", "content": prompt}
+        ]
+        
+        return await self.router.complete_structured(
+            role=role,
+            messages=messages,
+            schema=CritiqueOutput
+        )
+
+    async def generate_rebuttal(self, role: str, original_plan_json: str, findings_json: str) -> RebuttalOutput:
+        prompt = f"""
+Original Plan:
+{original_plan_json}
+
+Critique Findings:
+{findings_json}
+
+You are the planner who created the original plan. Review the critique findings.
+- A finding can be rejected only with artifact evidence or strong justification.
+- A finding can be accepted and converted into a requirement/task/test.
+- No hand-wavy rebuttals.
+"""
+        messages = [
+            {"role": "user", "content": prompt}
+        ]
+        
+        return await self.router.complete_structured(
+            role=role,
+            messages=messages,
+            schema=RebuttalOutput
+        )

package/src/devcouncil/planning/plan_service.py

@@ -1,46 +1,46 @@
-from typing import List
-from pydantic import BaseModel
-from devcouncil.domain.task import Task
-from devcouncil.llm.router import ModelRouter
-
-class PlanOutput(BaseModel):
-    id: str
-    rationale: str
-    tasks: List[Task]
-
-class PlanService:
-    def __init__(self, router: ModelRouter):
-        self.router = router
-
-    async def generate_plan(self, role: str, goal: str, requirements_json: str, repo_map_json: str) -> PlanOutput:
-        prompt = f"""
-Goal: {goal}
-
-Requirements:
-{requirements_json}
-
-Repository Map:
-{repo_map_json}
-
-Your task is to create a detailed implementation plan.
-- Break down the requirements into atomic implementation tasks.
-- For each task, specify which files will be created or modified.
-- Specify which tests are expected to verify the task.
-- Ensure each task maps back to at least one requirement.
-
-Role-specific instructions:
-"""
-        if role == "planner_a":
-            prompt += "You are the pragmatic tech lead. Optimize for simplicity and minimal dependencies."
-        else:
-            prompt += "You are the production-readiness architect. Optimize for security, performance, and edge cases."
-
-        messages = [
-            {"role": "user", "content": prompt}
-        ]
-        
-        return await self.router.complete_structured(
-            role=role,
-            messages=messages,
-            schema=PlanOutput
-        )
+from typing import List
+from pydantic import BaseModel
+from devcouncil.domain.task import Task
+from devcouncil.llm.router import ModelRouter
+
+class PlanOutput(BaseModel):
+    id: str
+    rationale: str
+    tasks: List[Task]
+
+class PlanService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def generate_plan(self, role: str, goal: str, requirements_json: str, repo_map_json: str) -> PlanOutput:
+        prompt = f"""
+Goal: {goal}
+
+Requirements:
+{requirements_json}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to create a detailed implementation plan.
+- Break down the requirements into atomic implementation tasks.
+- For each task, specify which files will be created or modified.
+- Specify which tests are expected to verify the task.
+- Ensure each task maps back to at least one requirement.
+
+Role-specific instructions:
+"""
+        if role == "planner_a":
+            prompt += "You are the pragmatic tech lead. Optimize for simplicity and minimal dependencies."
+        else:
+            prompt += "You are the production-readiness architect. Optimize for security, performance, and edge cases."
+
+        messages = [
+            {"role": "user", "content": prompt}
+        ]
+        
+        return await self.router.complete_structured(
+            role=role,
+            messages=messages,
+            schema=PlanOutput
+        )

package/src/devcouncil/planning/prompt_enhancer_service.py

@@ -0,0 +1,86 @@
+from pydantic import BaseModel, Field
+
+from devcouncil.llm.router import ModelRouter
+
+
+class PromptEnhancement(BaseModel):
+    original_goal: str
+    enhanced_goal: str
+    codebase_context: list[str] = Field(default_factory=list)
+    debate_focus: list[str] = Field(default_factory=list)
+    constraints: list[str] = Field(default_factory=list)
+
+    def normalized(self, original_goal: str) -> "PromptEnhancement":
+        enhanced_goal = self.enhanced_goal.strip() or original_goal
+        return self.model_copy(
+            update={
+                "original_goal": original_goal,
+                "enhanced_goal": enhanced_goal,
+                "codebase_context": _clean_items(self.codebase_context),
+                "debate_focus": _clean_items(self.debate_focus),
+                "constraints": _clean_items(self.constraints),
+            }
+        )
+
+    def debate_prompt(self) -> str:
+        sections = [
+            "# Enhanced Planning Prompt",
+            "",
+            "## Original user goal",
+            self.original_goal,
+            "",
+            "## Codebase-specific goal",
+            self.enhanced_goal,
+        ]
+        if self.codebase_context:
+            sections.extend(["", "## Relevant codebase context"])
+            sections.extend(f"- {item}" for item in self.codebase_context)
+        if self.constraints:
+            sections.extend(["", "## Constraints to preserve"])
+            sections.extend(f"- {item}" for item in self.constraints)
+        if self.debate_focus:
+            sections.extend(["", "## Debate focus"])
+            sections.extend(f"- {item}" for item in self.debate_focus)
+        return "\n".join(sections)
+
+
+class PromptEnhancerService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def enhance_prompt(
+        self,
+        goal: str,
+        repo_map_json: str,
+        graph_context_json: str | None = None,
+    ) -> PromptEnhancement:
+        prompt = f"""
+Original user goal:
+{goal}
+
+Repository map:
+{repo_map_json}
+
+Code review graph context:
+{graph_context_json or "{}"}
+
+You are DevCouncil's codebase-specific prompt enhancer.
+Rewrite the user goal into a better planning prompt before it is sent to the council debate.
+
+Requirements:
+- Preserve the user's intent exactly; do not add unrelated features.
+- Make the goal specific to the mapped repository architecture, languages, tests, and likely ownership boundaries.
+- Identify constraints the planners and critics must preserve.
+- Identify debate focus areas that should force useful disagreement between pragmatic and production-readiness plans.
+- Keep the enhanced_goal concise enough to be used as the goal for spec, planning, critique, and arbitration.
+"""
+        enhancement = await self.router.complete_structured(
+            role="prompt_enhancer",
+            messages=[{"role": "user", "content": prompt}],
+            schema=PromptEnhancement,
+        )
+        return enhancement.normalized(goal)
+
+
+def _clean_items(items: list[str]) -> list[str]:
+    return [item.strip() for item in items if item.strip()]