code-finder 0.1.0__py3-none-any.whl

claude_context/synthesis/logic_explainer.py

@@ -0,0 +1,235 @@
+"""LogicExplainer subagent
+
+Produces rationale-rich summaries for code units so downstream documentation can
+capture the _why_ along with the _what_. The explainer consumes semantic chunks
+generated during indexing and, optionally, decision/context notes. Results feed
+into the structured evidence pipeline (`rationale` tier).
+
+Two-pass workflow note: the forthcoming editor agent will consume the
+`LogicSummary` payloads directly to audit the synthesized sections.  Treat the
+outputs as canonical evidence blocks so the editor can compare its rewrites
+against the underlying rationale rather than re-querying the repository.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional
+
+from ..context_manager import ContextItem
+from .providers import TextGenerator, create_generator
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LogicSummary:
+    """Structured output for a single code unit summary."""
+
+    unit_id: str
+    file_path: str
+    chunk_type: str
+    summary_text: str
+    rationale: str
+    trade_offs: List[str]
+    side_effects: List[str]
+    dependencies: List[str]
+    citations: List[str]
+    confidence: float
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "unit_id": self.unit_id,
+            "file_path": self.file_path,
+            "chunk_type": self.chunk_type,
+            "summary": self.summary_text,
+            "rationale": self.rationale,
+            "trade_offs": self.trade_offs,
+            "side_effects": self.side_effects,
+            "dependencies": self.dependencies,
+            "citations": self.citations,
+            "confidence": self.confidence,
+        }
+
+
+class LogicExplainer:
+    """LLM-based summarizer that captures design intent for code units.
+
+    Downstream editor passes should treat the returned dictionaries as
+    immutable evidence objects: each field provides the structured context the
+    editor needs to justify rewrites and preserve citations.
+    """
+
+    def __init__(
+        self,
+        generator: Optional[TextGenerator] = None,
+        *,
+        max_units: int = 12,
+        max_tokens: int = 600,
+        temperature: float = 0.15,
+    ) -> None:
+        self.generator = generator or create_generator()
+        self.max_units = max_units
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+    def summarize_chunks(
+        self,
+        chunks: Iterable[Dict[str, Any]],
+        decision_notes: Optional[Iterable[ContextItem]] = None,
+    ) -> List[Dict[str, Any]]:
+        """Generate structured rationale summaries for selected code chunks."""
+
+        selected_chunks = [c for c in chunks if c.get("content")][: self.max_units]
+        if not selected_chunks:
+            return []
+
+        decision_context = self._format_decision_context(decision_notes)
+        summaries: List[Dict[str, Any]] = []
+
+        for chunk in selected_chunks:
+            try:
+                summary = self._summarize_chunk(chunk, decision_context)
+                if summary:
+                    summaries.append(summary)
+            except Exception as exc:  # pylint: disable=broad-except
+                logger.warning(
+                    "LogicExplainer failed for %s:%s - %s",
+                    chunk.get("file_path"),
+                    chunk.get("chunk_name") or chunk.get("chunk_type"),
+                    exc,
+                )
+
+        return summaries
+
+    def _summarize_chunk(
+        self,
+        chunk: Dict[str, Any],
+        decision_context: str,
+    ) -> Optional[Dict[str, Any]]:
+        system_prompt = (
+            "You are a senior software architect documenting code. "
+            "Explain what a unit does, why it exists, and notable trade-offs. "
+            "Respond strictly in JSON using the provided schema."
+        )
+
+        unit_label = self._make_unit_id(chunk)
+        user_prompt = self._build_user_prompt(chunk, decision_context, unit_label)
+
+        response = self.generator.generate(
+            system_prompt=system_prompt,
+            user_prompt=user_prompt,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens,
+        )
+
+        parsed = self._parse_response(response)
+        if not parsed:
+            return None
+
+        logic_summary = LogicSummary(
+            unit_id=unit_label,
+            file_path=str(chunk.get("file_path", "")),
+            chunk_type=str(chunk.get("chunk_type", "unknown")),
+            summary_text=parsed.get("summary_text", ""),
+            rationale=parsed.get("why", ""),
+            trade_offs=self._ensure_list(parsed.get("trade_offs")),
+            side_effects=self._ensure_list(parsed.get("side_effects")),
+            dependencies=self._ensure_list(parsed.get("dependencies")),
+            citations=self._ensure_list(parsed.get("citations")),
+            confidence=self._safe_float(parsed.get("confidence", 0.6)),
+        )
+
+        return logic_summary.to_dict()
+
+    def _build_user_prompt(
+        self,
+        chunk: Dict[str, Any],
+        decision_context: str,
+        unit_label: str,
+    ) -> str:
+        snippet = (chunk.get("content") or "").strip()
+        header = f"### CODE UNIT\nLabel: {unit_label}\nType: {chunk.get('chunk_type', 'unknown')}"
+
+        if chunk.get("chunk_name"):
+            header += f"\nSymbol: {chunk['chunk_name']}"
+
+        header += f"\nFile: {chunk.get('file_path')} ({chunk.get('start_line')}-{chunk.get('end_line')})"
+
+        prompt = [
+            header,
+            "\n### SOURCE CODE\n```python\n" + snippet[:1500] + "\n```",
+        ]
+
+        if decision_context:
+            prompt.append("\n### KNOWN DECISIONS\n" + decision_context)
+
+        prompt.append(
+            "\n### REQUIRED JSON SCHEMA\n"
+            '{"summary_text": "str", "why": "str", '
+            '"trade_offs": ["str"], "side_effects": ["str"], '
+            '"dependencies": ["str"], "citations": ["str"], '
+            '"confidence": "float"}'
+        )
+
+        return "\n".join(prompt)
+
+    def _format_decision_context(
+        self, decision_notes: Optional[Iterable[ContextItem]]
+    ) -> str:
+        if not decision_notes:
+            return ""
+
+        lines: List[str] = []
+        for note in decision_notes:
+            try:
+                summary = note.get_summary()
+            except Exception:  # fallback if summary fails
+                summary = (note.content or "").split("\n", maxsplit=1)[0][:200]
+            lines.append(f"- {note.type.upper()}: {summary} (source: {note.source or 'unknown'})")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _parse_response(response: str) -> Optional[Dict[str, Any]]:
+        if not response:
+            return None
+
+        cleaned = response.strip()
+        if cleaned.startswith("```"):
+            cleaned = cleaned.split("\n", 1)[1]
+            if cleaned.endswith("```"):
+                cleaned = cleaned.rsplit("\n", 1)[0]
+
+        try:
+            parsed = json.loads(cleaned)
+            if isinstance(parsed, dict):
+                return parsed
+        except json.JSONDecodeError:
+            logger.debug("LogicExplainer JSON parse failed: %s", cleaned)
+        return None
+
+    @staticmethod
+    def _make_unit_id(chunk: Dict[str, Any]) -> str:
+        name = chunk.get("chunk_name") or chunk.get("chunk_type") or "unit"
+        path = chunk.get("file_path", "unknown")
+        start = chunk.get("start_line", 0)
+        return f"{path}:{start}:{name}"
+
+    @staticmethod
+    def _ensure_list(value: Any) -> List[str]:
+        if isinstance(value, list):
+            return [str(v) for v in value if v]
+        if isinstance(value, str) and value:
+            return [value]
+        return []
+
+    @staticmethod
+    def _safe_float(value: Any, default: float = 0.6) -> float:
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return default
+
+