devcouncil 0.1.0

package/src/devcouncil/llm/provider.py

@@ -0,0 +1,125 @@
+from abc import ABC, abstractmethod
+import copy
+from typing import List, Dict, Any, Optional
+from pydantic import BaseModel
+import httpx
+import json
+from pathlib import Path
+
+class LLMResponse(BaseModel):
+    content: str
+    model: str
+    usage: Dict[str, int]
+    raw_response: Dict[str, Any]
+
+class Provider(ABC):
+    @abstractmethod
+    async def complete(
+        self, 
+        model: str, 
+        messages: List[Dict[str, str]], 
+        temperature: float = 0.0,
+        json_mode: bool = False
+    ) -> LLMResponse:
+        pass
+
+class OpenRouterProvider(Provider):
+    def __init__(self, api_key: str):
+        self.api_key = api_key
+        self.base_url = "https://openrouter.ai/api/v1"
+
+    async def complete(
+        self, 
+        model: str, 
+        messages: List[Dict[str, str]], 
+        temperature: float = 0.0,
+        json_mode: bool = False
+    ) -> LLMResponse:
+        # Deep-copy to avoid mutating the caller's messages list
+        msgs = copy.deepcopy(messages)
+
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://github.com/devcouncil/devcouncil", # Optional
+            "X-Title": "DevCouncil", # Optional
+        }
+        
+        payload = {
+            "model": model,
+            "messages": msgs,
+            "temperature": temperature,
+        }
+        
+        if json_mode:
+            payload["response_format"] = {"type": "json_object"}
+            # Ensure the user message mentions JSON
+            if msgs[-1]["role"] == "user":
+                msgs[-1]["content"] += "\n\nOutput must be a valid JSON object."
+
+        async with httpx.AsyncClient(timeout=180.0) as client:
+            response = await client.post(
+                f"{self.base_url}/chat/completions",
+                headers=headers,
+                json=payload
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            resp = LLMResponse(
+                content=data["choices"][0]["message"]["content"],
+                model=data["model"],
+                usage=data.get("usage", {}),
+                raw_response=data
+            )
+            
+            # Log the call
+            try:
+                from devcouncil.utils.redaction import redact_dict
+                log_dir = Path(".devcouncil/logs")
+                log_dir.mkdir(parents=True, exist_ok=True)
+                log_file = log_dir / "model_calls.jsonl"
+                
+                # Create a redacted copy of both request and response for logging
+                log_payload = {
+                    "request": redact_dict(payload),
+                    "response": redact_dict(data),
+                    "usage": resp.usage,
+                }
+                with open(log_file, "a", encoding="utf-8") as f:
+                    f.write(json.dumps(log_payload) + "\n")
+            except Exception as e:
+                import logging as _log
+                _log.getLogger(__name__).debug("Failed to log model call: %s", e)
+                
+            return resp
+
+class MockProvider(Provider):
+    """Mock provider for dry runs and testing."""
+    def __init__(self, responses: Optional[Dict[str, Any]] = None):
+        # responses can be a dict of model -> str OR model -> list of str
+        self.responses = responses or {}
+        self._counts: Dict[str, int] = {}
+
+    async def complete(
+        self, 
+        model: str, 
+        messages: List[Dict[str, str]], 
+        temperature: float = 0.0,
+        json_mode: bool = False
+    ) -> LLMResponse:
+        res = self.responses.get(model, '{"mock": "response"}')
+        
+        if isinstance(res, list):
+            count = self._counts.get(model, 0)
+            content = res[min(count, len(res)-1)]
+            self._counts[model] = count + 1
+        else:
+            content = res
+            
+        return LLMResponse(
+            content=content,
+            model=f"mock/{model}",
+            usage={"prompt_tokens": 10, "completion_tokens": 10, "total_tokens": 20},
+            raw_response={"choices": [{"message": {"content": content}}]}
+        )

package/src/devcouncil/llm/router.py

@@ -0,0 +1,125 @@
+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
+        response = cache.get(model, msgs, temp, True)
+        cache_hit = response is not None
+
+        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
+                    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]}...")

package/src/devcouncil/planning/__init__.py

@@ -0,0 +1 @@
+

package/src/devcouncil/planning/arbiter_service.py

@@ -0,0 +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
+        )

package/src/devcouncil/planning/critique_service.py

@@ -0,0 +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
+        )

package/src/devcouncil/planning/plan_service.py

@@ -0,0 +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
+        )

package/src/devcouncil/planning/repair_service.py

@@ -0,0 +1,39 @@
+from typing import List
+import json
+from pydantic import BaseModel
+from devcouncil.domain.gap import Gap
+from devcouncil.domain.task import Task
+from devcouncil.llm.router import ModelRouter
+
+class RepairOutput(BaseModel):
+    suggested_tasks: List[Task]
+
+class RepairService:
+    """Uses LLM to infer focused repair tasks from blocking gaps."""
+    
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def generate_repair_plan(self, gaps: List[Gap], project_context: str) -> RepairOutput:
+        prompt = f"""
+The following blocking gaps were detected during verification.
+Gaps:
+{json.dumps([g.model_dump() for g in gaps], indent=2)}
+
+Project Context:
+{project_context}
+
+Your task is to generate focused implementation tasks to fix these gaps.
+- Each task must have a clear description and recommended fix.
+- Specify 'planned_files' that need modification (infer from gap evidence).
+- Link each task to the relevant 'requirement_id' mentioned in the gap.
+
+Return a JSON object with 'suggested_tasks'.
+"""
+        messages = [{"role": "user", "content": prompt}]
+        
+        return await self.router.complete_structured(
+            role="planner_a",  # Pragmatic tech lead is best suited for repair task generation
+            messages=messages,
+            schema=RepairOutput
+        )

package/src/devcouncil/planning/spec_service.py

@@ -0,0 +1,44 @@
+from typing import List
+from pydantic import BaseModel
+from devcouncil.domain.requirement import Requirement
+from devcouncil.domain.assumption import Assumption
+from devcouncil.llm.router import ModelRouter
+
+class BlockingQuestion(BaseModel):
+    id: str
+    question: str
+    reason: str
+
+class SpecOutput(BaseModel):
+    requirements: List[Requirement]
+    assumptions: List[Assumption]
+    blocking_questions: List[BlockingQuestion]
+
+class SpecService:
+    def __init__(self, router: ModelRouter):
+        self.router = router
+
+    async def generate_spec(self, goal: str, repo_map_json: str) -> SpecOutput:
+        prompt = f"""
+Goal: {goal}
+
+Repository Map:
+{repo_map_json}
+
+Your task is to draft the initial software specification for this goal.
+1. Identify functional and non-functional requirements.
+2. Extract any assumptions you are making about the codebase or architecture.
+3. List any blocking questions that the user must answer before implementation can proceed.
+
+Each requirement MUST have clear acceptance criteria with verification methods.
+Each assumption MUST have a confidence and impact level.
+"""
+        messages = [
+            {"role": "user", "content": prompt}
+        ]
+        
+        return await self.router.complete_structured(
+            role="spec_writer",
+            messages=messages,
+            schema=SpecOutput
+        )

package/src/devcouncil/reporting/github_check.py

@@ -0,0 +1,32 @@
+from devcouncil.artifacts.graph import ArtifactGraph
+
+class GitHubCheckGenerator:
+    """Generates GitHub Checks API payloads."""
+    
+    @staticmethod
+    def generate(graph: ArtifactGraph) -> dict:
+        summary = graph.coverage_summary()
+        blocking_gaps = graph.blocking_gaps()
+        
+        status = "completed"
+        conclusion = "failure" if summary["blocking_gaps"] > 0 else "success"
+        
+        text = f"**Requirements**: {summary['total_requirements']} | "
+        text += f"**Tasks**: {summary['total_tasks']} | "
+        text += f"**Gaps**: {summary['blocking_gaps']} blocking\n\n"
+        
+        if blocking_gaps:
+            text += "### Blocking Gaps\n"
+            for gap in blocking_gaps:
+                text += f"- **{gap.id}**: {gap.description}\n"
+                
+        return {
+            "name": "DevCouncil Verification",
+            "status": status,
+            "conclusion": conclusion,
+            "output": {
+                "title": f"DevCouncil: {conclusion.capitalize()}",
+                "summary": f"Found {summary['blocking_gaps']} blocking gaps.",
+                "text": text
+            }
+        }

package/src/devcouncil/reporting/json_report.py

@@ -0,0 +1,17 @@
+import json
+from devcouncil.artifacts.graph import ArtifactGraph
+
+class JsonReportGenerator:
+    """Generates a JSON evidence report."""
+    
+    @staticmethod
+    def generate(graph: ArtifactGraph) -> str:
+        summary = graph.coverage_summary()
+        
+        report = {
+            "verdict": "blocked" if summary["blocking_gaps"] > 0 else "passed",
+            "coverage_summary": summary,
+            "blocking_gaps": [g.model_dump() for g in graph.blocking_gaps()]
+        }
+        
+        return json.dumps(report, indent=2)

package/src/devcouncil/reporting/markdown_report.py

@@ -0,0 +1,46 @@
+from devcouncil.artifacts.graph import ArtifactGraph
+
+class MarkdownReportGenerator:
+    """Generates a Markdown evidence report."""
+
+    MAX_INLINE_GAPS = 25
+    
+    @staticmethod
+    def generate(graph: ArtifactGraph) -> str:
+        summary = graph.coverage_summary()
+
+        md_output = "# DevCouncil Report\n\n"
+        md_output += "## Verdict\n"
+        if summary["blocking_gaps"] > 0:
+            md_output += f"**Blocked**: {summary['blocking_gaps']} high-severity gaps remain.\n\n"
+        else:
+            md_output += "**Passed**: Ready for release.\n\n"
+
+        md_output += "## Coverage Summary\n"
+        md_output += f"- **Requirements**: {summary['total_requirements']} ({summary['requirements_without_tasks']} unmapped)\n"
+        md_output += f"- **Tasks**: {summary['total_tasks']} ({summary['tasks_without_requirements']} orphaned)\n"
+        md_output += f"- **Evidence**: {summary['total_ac'] - summary['ac_without_evidence']}/{summary['total_ac']} AC verified\n\n"
+
+        md_output += "## Requirements Coverage Table\n"
+        md_output += "| Requirement | Task Mapping | Status |\n"
+        md_output += "|---|---|---|\n"
+        
+        for req in graph.requirements.values():
+            linked_tasks = [t for t in graph.tasks.values() if req.id in t.requirement_ids]
+            task_str = ", ".join([t.id for t in linked_tasks]) if linked_tasks else "*None*"
+            status_str = "Covered" if linked_tasks else "**Unmapped**"
+            md_output += f"| {req.id} {req.title} | {task_str} | {status_str} |\n"
+                    
+        md_output += "\n## Blocking Gaps\n"
+        blocking_gaps = graph.blocking_gaps()
+        if not blocking_gaps:
+            md_output += "None.\n"
+        else:
+            for gap in blocking_gaps[:MarkdownReportGenerator.MAX_INLINE_GAPS]:
+                md_output += f"### {gap.id}: {gap.description}\n"
+                md_output += f"**Recommended fix**: {gap.recommended_fix}\n\n"
+            if len(blocking_gaps) > MarkdownReportGenerator.MAX_INLINE_GAPS:
+                remaining = len(blocking_gaps) - MarkdownReportGenerator.MAX_INLINE_GAPS
+                md_output += f"_Omitted {remaining} additional blocking gap(s). Use JSON output for the full list._\n"
+                
+        return md_output

package/src/devcouncil/reporting/report_builder.py

@@ -0,0 +1,14 @@
+from devcouncil.artifacts.graph import ArtifactGraph
+from devcouncil.reporting.markdown_report import MarkdownReportGenerator
+from devcouncil.reporting.json_report import JsonReportGenerator
+
+class ReportBuilder:
+    """Builds reports in various formats from the artifact graph."""
+    
+    @staticmethod
+    def build_markdown(graph: ArtifactGraph) -> str:
+        return MarkdownReportGenerator.generate(graph)
+
+    @staticmethod
+    def build_json(graph: ArtifactGraph) -> str:
+        return JsonReportGenerator.generate(graph)