llmcode-cli 1.0.0__py3-none-any.whl

llm_code/harness/config.py

@@ -0,0 +1,33 @@
+"""Harness configuration types."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class HarnessControl:
+    """A single harness control (guide or sensor)."""
+
+    name: str
+    category: str  # "guide" | "sensor"
+    kind: str  # "computational" | "inferential"
+    enabled: bool = True
+    trigger: str = "post_tool"  # "pre_tool" | "post_tool" | "pre_turn" | "post_turn" | "on_demand"
+
+
+@dataclass(frozen=True)
+class HarnessFinding:
+    """A finding reported by a sensor after tool execution."""
+
+    sensor: str
+    message: str
+    file_path: str = ""
+    severity: str = "info"  # "error" | "warning" | "info"
+
+
+@dataclass(frozen=True)
+class HarnessConfig:
+    """Configuration for the Harness Engine."""
+
+    template: str = "auto"
+    controls: tuple[HarnessControl, ...] = ()

llm_code/harness/engine.py

@@ -0,0 +1,129 @@
+"""HarnessEngine — orchestrates guides (feedforward) and sensors (feedback)."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from llm_code.harness.config import HarnessConfig, HarnessControl, HarnessFinding
+from llm_code.harness.guides import (
+    analysis_context_guide,
+    plan_mode_denied_tools,
+    repo_map_guide,
+)
+from llm_code.harness.sensors import (
+    auto_commit_sensor,
+    code_rules_sensor,
+    lsp_diagnose_sensor,
+)
+
+_WRITE_TOOLS = frozenset({"write_file", "edit_file"})
+
+
+class HarnessEngine:
+    """Central orchestrator for all quality controls."""
+
+    def __init__(self, config: HarnessConfig, cwd: Path) -> None:
+        self._config = config
+        self._cwd = cwd
+        self._overrides: dict[str, bool] = {}
+        self.plan_mode: bool = False
+        self.analysis_context: str | None = None
+        self.lsp_manager: Any | None = None
+
+    @property
+    def config(self) -> HarnessConfig:
+        return self._config
+
+    def _is_enabled(self, ctrl: HarnessControl) -> bool:
+        if ctrl.name in self._overrides:
+            return self._overrides[ctrl.name]
+        return ctrl.enabled
+
+    def _controls_by(self, category: str, trigger: str) -> list[HarnessControl]:
+        return [
+            c for c in self._config.controls
+            if c.category == category and c.trigger == trigger and self._is_enabled(c)
+        ]
+
+    def pre_turn(self) -> list[str]:
+        """Run pre_turn guides. Returns strings to inject into system prompt."""
+        injections: list[str] = []
+        for ctrl in self._controls_by("guide", "pre_turn"):
+            text = self._run_guide(ctrl)
+            if text:
+                injections.append(text)
+        return injections
+
+    def check_pre_tool(self, tool_name: str) -> str | None:
+        """Check pre_tool guides (plan mode). Returns denial message or None."""
+        for ctrl in self._controls_by("guide", "pre_tool"):
+            if ctrl.name == "plan_mode":
+                denied = plan_mode_denied_tools(self.plan_mode)
+                if tool_name in denied:
+                    return f"Plan mode: read-only. Tool '{tool_name}' denied. Use /plan to switch to Act mode."
+        return None
+
+    def _run_guide(self, ctrl: HarnessControl) -> str:
+        if ctrl.name == "repo_map":
+            return repo_map_guide(cwd=self._cwd)
+        if ctrl.name == "analysis_context":
+            return analysis_context_guide(context=self.analysis_context)
+        if ctrl.name == "architecture_doc":
+            doc_path = self._cwd / ".llm-code" / "architecture.md"
+            if doc_path.exists():
+                try:
+                    return doc_path.read_text(encoding="utf-8")
+                except OSError:
+                    return ""
+            return ""
+        if ctrl.name == "knowledge":
+            from llm_code.harness.guides import knowledge_guide
+            return knowledge_guide(cwd=self._cwd)
+        return ""
+
+    async def post_tool(
+        self, tool_name: str, file_path: str, is_error: bool,
+    ) -> list[HarnessFinding]:
+        """Run post_tool sensors. Returns findings for agent context."""
+        if is_error or tool_name not in _WRITE_TOOLS:
+            return []
+
+        findings: list[HarnessFinding] = []
+        for ctrl in self._controls_by("sensor", "post_tool"):
+            new_findings = await self._run_sensor(ctrl, tool_name, file_path)
+            findings.extend(new_findings)
+        return findings
+
+    async def _run_sensor(
+        self, ctrl: HarnessControl, tool_name: str, file_path: str
+    ) -> list[HarnessFinding]:
+        if ctrl.name == "lsp_diagnose":
+            return await lsp_diagnose_sensor(lsp_manager=self.lsp_manager, file_path=file_path)
+        if ctrl.name == "code_rules":
+            return code_rules_sensor(cwd=self._cwd, file_path=file_path)
+        if ctrl.name == "auto_commit":
+            finding = auto_commit_sensor(file_path=Path(file_path), tool_name=tool_name)
+            return [finding] if finding else []
+        return []
+
+    def enable(self, name: str) -> None:
+        self._overrides[name] = True
+
+    def disable(self, name: str) -> None:
+        self._overrides[name] = False
+
+    def status(self) -> dict:
+        guides = []
+        sensors = []
+        for ctrl in self._config.controls:
+            entry = {
+                "name": ctrl.name,
+                "trigger": ctrl.trigger,
+                "kind": ctrl.kind,
+                "enabled": self._is_enabled(ctrl),
+            }
+            if ctrl.category == "guide":
+                guides.append(entry)
+            else:
+                sensors.append(entry)
+        return {"template": self._config.template, "guides": guides, "sensors": sensors}

llm_code/harness/guides.py

@@ -0,0 +1,41 @@
+"""Guide implementations — feedforward controls that inject context before turns."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from llm_code.runtime.knowledge_compiler import KnowledgeCompiler
+from llm_code.runtime.repo_map import build_repo_map
+
+PLAN_DENIED_TOOLS: frozenset[str] = frozenset({
+    "write_file", "edit_file", "bash", "git_commit", "git_push", "notebook_edit",
+})
+
+
+def repo_map_guide(cwd: Path, max_tokens: int = 2000) -> str:
+    """Build a compact repo map string. Returns empty on failure."""
+    try:
+        rmap = build_repo_map(cwd)
+        return rmap.to_compact(max_tokens=max_tokens)
+    except Exception:
+        return ""
+
+
+def analysis_context_guide(context: str | None) -> str:
+    """Return stored analysis context, or empty string."""
+    return context or ""
+
+
+def plan_mode_denied_tools(active: bool) -> frozenset[str]:
+    """Return the set of tools denied in plan mode. Empty when inactive."""
+    if active:
+        return PLAN_DENIED_TOOLS
+    return frozenset()
+
+
+def knowledge_guide(cwd: Path, max_tokens: int = 3000) -> str:
+    """Return compiled project knowledge for system prompt injection."""
+    try:
+        compiler = KnowledgeCompiler(cwd=cwd, llm_provider=None)
+        return compiler.query(max_tokens=max_tokens)
+    except Exception:
+        return ""

llm_code/harness/sensors.py

@@ -0,0 +1,68 @@
+"""Sensor implementations — feedback controls that run after tool execution."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from llm_code.harness.config import HarnessFinding
+from llm_code.runtime.auto_commit import auto_commit_file
+from llm_code.runtime.auto_diagnose import auto_diagnose
+from llm_code.analysis.engine import run_analysis
+
+
+async def lsp_diagnose_sensor(
+    lsp_manager: Any | None,
+    file_path: str,
+) -> list[HarnessFinding]:
+    """Run LSP diagnostics on a file. Returns findings or empty list."""
+    if lsp_manager is None:
+        return []
+    try:
+        diag_errors = await auto_diagnose(lsp_manager, file_path)
+        return [
+            HarnessFinding(
+                sensor="lsp_diagnose",
+                message=msg,
+                file_path=file_path,
+                severity="error",
+            )
+            for msg in diag_errors
+        ]
+    except Exception:
+        return []
+
+
+def code_rules_sensor(cwd: Path, file_path: str) -> list[HarnessFinding]:
+    """Run code analysis rules and return findings for the given file."""
+    try:
+        result = run_analysis(cwd)
+        return [
+            HarnessFinding(
+                sensor="code_rules",
+                message=f"{v.rule_key}: {v.message}",
+                file_path=v.file_path,
+                severity=v.severity,
+            )
+            for v in result.violations
+            if v.file_path == file_path
+            or file_path.endswith(v.file_path)
+            or v.file_path.endswith(file_path)
+        ]
+    except Exception:
+        return []
+
+
+def auto_commit_sensor(file_path: Path, tool_name: str) -> HarnessFinding | None:
+    """Attempt auto-commit checkpoint. Returns finding on success, None on failure."""
+    try:
+        ok = auto_commit_file(file_path, tool_name)
+        if ok:
+            return HarnessFinding(
+                sensor="auto_commit",
+                message=f"checkpoint: {tool_name} {file_path.name}",
+                file_path=str(file_path),
+                severity="info",
+            )
+        return None
+    except Exception:
+        return None

llm_code/harness/templates.py

@@ -0,0 +1,84 @@
+"""Project-type detection and default harness templates."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from llm_code.harness.config import HarnessControl
+
+_WEB_FRAMEWORKS = ("fastapi", "flask", "django", "starlette", "sanic")
+
+
+def detect_template(cwd: Path) -> str:
+    """Auto-detect project type from files in *cwd*."""
+    if (cwd / "pnpm-workspace.yaml").exists() or (cwd / "turbo.json").exists():
+        return "monorepo"
+
+    if (cwd / "manage.py").exists():
+        return "python-web"
+
+    has_pyproject = (cwd / "pyproject.toml").exists()
+    has_requirements = (cwd / "requirements.txt").exists()
+
+    if has_pyproject or has_requirements:
+        if _has_web_dep(cwd):
+            return "python-web"
+        return "python-cli"
+
+    if (cwd / "package.json").exists():
+        return "node-app"
+
+    return "generic"
+
+
+def _has_web_dep(cwd: Path) -> bool:
+    for fname in ("pyproject.toml", "requirements.txt", "setup.cfg"):
+        fpath = cwd / fname
+        if fpath.exists():
+            try:
+                content = fpath.read_text(encoding="utf-8").lower()
+                if any(fw in content for fw in _WEB_FRAMEWORKS):
+                    return True
+            except OSError:
+                pass
+    return False
+
+
+def default_controls(template: str) -> tuple[HarnessControl, ...]:
+    _TEMPLATES: dict[str, tuple[HarnessControl, ...]] = {
+        "python-cli": (
+            HarnessControl(name="repo_map", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="analysis_context", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="knowledge", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="plan_mode", category="guide", kind="computational", trigger="pre_tool"),
+            HarnessControl(name="lsp_diagnose", category="sensor", kind="computational", trigger="post_tool"),
+            HarnessControl(name="code_rules", category="sensor", kind="computational", trigger="post_tool"),
+            HarnessControl(name="auto_commit", category="sensor", kind="computational", trigger="post_tool"),
+        ),
+        "python-web": (
+            HarnessControl(name="repo_map", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="architecture_doc", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="analysis_context", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="knowledge", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="plan_mode", category="guide", kind="computational", trigger="pre_tool"),
+            HarnessControl(name="lsp_diagnose", category="sensor", kind="computational", trigger="post_tool"),
+            HarnessControl(name="code_rules", category="sensor", kind="computational", trigger="post_tool"),
+            HarnessControl(name="auto_commit", category="sensor", kind="computational", trigger="post_tool"),
+        ),
+        "node-app": (
+            HarnessControl(name="repo_map", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="plan_mode", category="guide", kind="computational", trigger="pre_tool"),
+            HarnessControl(name="code_rules", category="sensor", kind="computational", trigger="post_tool"),
+        ),
+        "monorepo": (
+            HarnessControl(name="repo_map", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="architecture_doc", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="plan_mode", category="guide", kind="computational", trigger="pre_tool"),
+            HarnessControl(name="code_rules", category="sensor", kind="computational", trigger="post_tool"),
+        ),
+        "generic": (
+            HarnessControl(name="repo_map", category="guide", kind="computational", trigger="pre_turn"),
+            HarnessControl(name="plan_mode", category="guide", kind="computational", trigger="pre_tool"),
+            HarnessControl(name="code_rules", category="sensor", kind="computational", trigger="post_tool"),
+        ),
+    }
+    return _TEMPLATES.get(template, _TEMPLATES["generic"])

llm_code/hida/__init__.py

@@ -0,0 +1 @@
+"""HIDA: Hierarchical Intent-Driven Architecture for dynamic context loading."""

llm_code/hida/classifier.py

@@ -0,0 +1,187 @@
+"""2-layer task classifier: keyword matching first, LLM fallback second."""
+from __future__ import annotations
+
+import re
+from dataclasses import replace
+from typing import TYPE_CHECKING, Any
+
+from llm_code.hida.types import TaskProfile, TaskType
+
+if TYPE_CHECKING:
+    pass
+
+# Keyword patterns per task type — order matters (first match wins within a type)
+# IMPORTANT: More specific types are listed first. CODING is a low-priority fallback.
+# Patterns use exclusive keywords that are unambiguous for each type.
+_KEYWORD_PATTERNS: dict[TaskType, list[re.Pattern[str]]] = {
+    TaskType.DEBUGGING: [
+        re.compile(r"\b(fix|bug|crash|traceback|exception|debug|broken|fails?|failing)\b", re.I),
+    ],
+    TaskType.TESTING: [
+        re.compile(r"\b(tests?|unittest|pytest|coverage|spec|assert)\b", re.I),
+    ],
+    TaskType.REVIEWING: [
+        re.compile(r"\b(review|code.?review|pull.?request|pr|diff|audit)\b", re.I),
+    ],
+    TaskType.REFACTORING: [
+        re.compile(r"\b(refactor|restructure|reorganize|clean.?up|simplify|extract)\b", re.I),
+    ],
+    TaskType.PLANNING: [
+        re.compile(r"\b(plan|roadmap|proposal|rfc)\b", re.I),
+    ],
+    TaskType.DEPLOYMENT: [
+        re.compile(r"\b(deploy|release|ci/?cd|docker|kubernetes|k8s|production|staging)\b", re.I),
+    ],
+    TaskType.DOCUMENTATION: [
+        re.compile(r"\b(document(?:ation)?|readme|docstring|jsdoc|api.?doc)\b", re.I),
+    ],
+    TaskType.RESEARCH: [
+        re.compile(r"\b(research|investigate|explore|compare|evaluate|benchmark)\b", re.I),
+    ],
+    # CODING is a low-priority generic fallback — only unique code-creation keywords
+    TaskType.CODING: [
+        re.compile(r"\b(implement|build|function|class|endpoint)\b", re.I),
+    ],
+}
+
+# Priority ordering: when scores are tied, higher-priority type wins.
+# Specific types beat CODING (low priority) and CONVERSATION (lowest).
+_TYPE_PRIORITY: dict[TaskType, int] = {
+    TaskType.DEBUGGING: 10,
+    TaskType.TESTING: 10,
+    TaskType.REVIEWING: 10,
+    TaskType.REFACTORING: 10,
+    TaskType.PLANNING: 10,
+    TaskType.DEPLOYMENT: 10,
+    TaskType.DOCUMENTATION: 10,
+    TaskType.RESEARCH: 10,
+    TaskType.CODING: 5,
+    TaskType.CONVERSATION: 1,
+}
+
+# Classification confidence for keyword matches
+_KEYWORD_CONFIDENCE = 0.85
+
+# LLM classification prompt
+_CLASSIFY_PROMPT = """\
+Classify the following user message into exactly one task type.
+Respond with ONLY the task type name, nothing else.
+
+Valid types: coding, debugging, reviewing, planning, testing, refactoring, research, deployment, documentation, conversation
+
+User message: {message}
+
+Task type:"""
+
+
+_FULL_LOAD_PROFILE = TaskProfile(
+    task_type=TaskType.CONVERSATION,
+    confidence=0.0,
+    tools=frozenset(),
+    memory_keys=frozenset(),
+    governance_categories=frozenset(),
+    load_full_prompt=True,
+)
+
+
+class TaskClassifier:
+    """Classifies user messages into task types using a 2-layer approach."""
+
+    def __init__(
+        self,
+        profiles: dict[TaskType, TaskProfile],
+        custom_patterns: dict[TaskType, list[re.Pattern[str]]] | None = None,
+    ) -> None:
+        self._profiles = profiles
+        self._patterns = custom_patterns if custom_patterns is not None else _KEYWORD_PATTERNS
+
+    def classify_by_keywords(self, message: str) -> TaskProfile | None:
+        """Layer 1: Fast keyword-based classification.
+
+        Returns a TaskProfile with keyword confidence, or None if ambiguous.
+        """
+        scores: dict[TaskType, int] = {}
+        for task_type, patterns in self._patterns.items():
+            for pattern in patterns:
+                matches = pattern.findall(message)
+                if matches:
+                    scores[task_type] = scores.get(task_type, 0) + len(matches)
+
+        if not scores:
+            return None
+
+        # Pick highest scoring type; if tie, use priority to break it.
+        # If tied AND same priority, return None (ambiguous).
+        sorted_scores = sorted(
+            scores.items(),
+            key=lambda x: (x[1], _TYPE_PRIORITY.get(x[0], 0)),
+            reverse=True,
+        )
+        if len(sorted_scores) > 1:
+            top_score, top_priority = sorted_scores[0][1], _TYPE_PRIORITY.get(sorted_scores[0][0], 0)
+            second_score, second_priority = sorted_scores[1][1], _TYPE_PRIORITY.get(sorted_scores[1][0], 0)
+            if top_score == second_score and top_priority == second_priority:
+                return None
+
+        best_type = sorted_scores[0][0]
+        base_profile = self._profiles.get(best_type)
+        if base_profile is None:
+            return None
+
+        return replace(base_profile, confidence=_KEYWORD_CONFIDENCE)
+
+    async def classify_by_llm(
+        self, message: str, provider: Any
+    ) -> TaskProfile | None:
+        """Layer 2: LLM-based classification for ambiguous inputs.
+
+        Args:
+            message: The user message to classify.
+            provider: An LLM provider with a `complete(prompt)` async method.
+
+        Returns:
+            A TaskProfile if classification succeeds, None otherwise.
+        """
+        try:
+            prompt = _CLASSIFY_PROMPT.format(message=message[:500])
+            response = await provider.complete(prompt)
+            task_name = response.strip().lower()
+
+            # Try to match response to a TaskType
+            try:
+                task_type = TaskType(task_name)
+            except ValueError:
+                return None
+
+            base_profile = self._profiles.get(task_type)
+            if base_profile is None:
+                return None
+
+            return replace(base_profile, confidence=0.7)
+        except Exception:
+            return None
+
+    async def classify(
+        self,
+        message: str,
+        provider: Any | None = None,
+        confidence_threshold: float = 0.6,
+    ) -> TaskProfile:
+        """Full 2-layer classification: keywords first, LLM fallback.
+
+        Always returns a TaskProfile. Falls back to full-load profile
+        when confidence is below threshold or classification fails.
+        """
+        # Layer 1: keyword matching
+        result = self.classify_by_keywords(message)
+        if result is not None and result.confidence >= confidence_threshold:
+            return result
+
+        # Layer 2: LLM fallback (only if provider available)
+        if provider is not None:
+            llm_result = await self.classify_by_llm(message, provider)
+            if llm_result is not None and llm_result.confidence >= confidence_threshold:
+                return llm_result
+
+        # Fallback: full context load
+        return _FULL_LOAD_PROFILE

llm_code/hida/engine.py

@@ -0,0 +1,49 @@
+"""HIDA engine: filters tools, memory, and prompt sections based on TaskProfile."""
+from __future__ import annotations
+
+from llm_code.hida.types import TaskProfile
+
+
+class HidaEngine:
+    """Applies a TaskProfile to filter context before prompt building."""
+
+    def filter_tools(
+        self, profile: TaskProfile, available_tools: set[str]
+    ) -> set[str]:
+        """Return the subset of tools allowed by the profile.
+
+        If load_full_prompt is True, returns all available tools.
+        """
+        if profile.load_full_prompt:
+            return set(available_tools)
+        return profile.tools & available_tools
+
+    def filter_memory(
+        self, profile: TaskProfile, all_memory: dict[str, str]
+    ) -> dict[str, str]:
+        """Return the subset of memory entries relevant to the profile.
+
+        If load_full_prompt is True, returns all memory entries.
+        """
+        if profile.load_full_prompt:
+            return dict(all_memory)
+        return {k: v for k, v in all_memory.items() if k in profile.memory_keys}
+
+    def build_summary(self, profile: TaskProfile) -> str:
+        """Build a human-readable summary of the current classification.
+
+        Used by the /hida slash command.
+        """
+        if profile.load_full_prompt:
+            return (
+                f"Task: {profile.task_type.value} | "
+                f"Confidence: {profile.confidence:.2f} | "
+                f"Mode: full context load"
+            )
+        return (
+            f"Task: {profile.task_type.value} | "
+            f"Confidence: {profile.confidence:.2f} | "
+            f"Tools: {len(profile.tools)} | "
+            f"Memory keys: {len(profile.memory_keys)} | "
+            f"Categories: {', '.join(sorted(profile.governance_categories)) or 'none'}"
+        )