llmcode-cli 1.0.0__py3-none-any.whl

llm_code/runtime/memory_lint.py

@@ -0,0 +1,252 @@
+"""Memory lint — validate project memory for stale refs, gaps, orphans, and age."""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from typing import Any
+
+from llm_code.api.types import Message, MessageRequest, TextBlock
+
+logger = logging.getLogger(__name__)
+
+_FILE_PATH_RE = re.compile(r"(?:^|\s)([\w./]+\.(?:py|ts|js|go|rs|md|toml|json|yaml|yml))\b")
+_MAX_AGE_DAYS = 30
+
+_SKIP_DIRS = frozenset({
+    ".git", "__pycache__", "node_modules", ".venv", "venv",
+    "dist", "build", ".egg-info", ".tox", ".mypy_cache", ".llm-code",
+})
+
+_CONTRADICTION_SYSTEM_PROMPT = """\
+You are a memory consistency checker. Given a list of project memory entries, \
+identify any pairs that contradict each other.
+
+Return a JSON array of objects with keys: "key_a", "key_b", "description".
+If no contradictions found, return an empty array: []
+
+Only flag clear factual contradictions, not differences in detail level.
+"""
+
+
+@dataclass(frozen=True)
+class StaleReference:
+    key: str
+    reference: str
+    line: int = 0
+
+
+@dataclass(frozen=True)
+class Contradiction:
+    key_a: str
+    key_b: str
+    description: str
+
+
+@dataclass(frozen=True)
+class MemoryLintResult:
+    stale: tuple[StaleReference, ...]
+    contradictions: tuple[Contradiction, ...]
+    coverage_gaps: tuple[str, ...]
+    orphans: tuple[str, ...]
+    old: tuple[str, ...]
+
+    def format_summary(self) -> str:
+        parts = []
+        if self.stale:
+            parts.append(f"{len(self.stale)} stale")
+        if self.coverage_gaps:
+            parts.append(f"{len(self.coverage_gaps)} coverage gaps")
+        if self.orphans:
+            parts.append(f"{len(self.orphans)} orphans")
+        if self.old:
+            parts.append(f"{len(self.old)} old")
+        if self.contradictions:
+            parts.append(f"{len(self.contradictions)} contradictions")
+        return f"Summary: {', '.join(parts)}" if parts else "Summary: no issues found"
+
+    def format_report(self) -> str:
+        lines = ["## Memory Health Check\n"]
+        for s in self.stale:
+            lines.append(f"  STALE   {s.key}:{s.line}  References \"{s.reference}\" — not found")
+        for gap in self.coverage_gaps:
+            lines.append(f"  GAP     {gap}  No memory coverage")
+        for orphan in self.orphans:
+            lines.append(f"  ORPHAN  {orphan}  References nothing in codebase")
+        for old_key in self.old:
+            lines.append(f"  OLD     {old_key}  Last updated >30 days ago")
+        for c in self.contradictions:
+            lines.append(f"  CONTRA  {c.key_a} vs {c.key_b}: {c.description}")
+        lines.append(f"\n{self.format_summary()}")
+        return "\n".join(lines)
+
+
+def lint_memory(
+    memory_dir: Path,
+    cwd: Path,
+    llm_provider: Any | None = None,
+) -> MemoryLintResult:
+    """Run fast computational memory health checks."""
+    entries = _load_entries(memory_dir)
+    stale = _check_stale(entries, cwd)
+    coverage_gaps = _check_coverage_gaps(entries, cwd)
+    old = _check_old(entries)
+
+    return MemoryLintResult(
+        stale=tuple(stale),
+        contradictions=(),
+        coverage_gaps=tuple(coverage_gaps),
+        orphans=(),
+        old=tuple(old),
+    )
+
+
+async def lint_memory_deep(
+    memory_dir: Path,
+    cwd: Path,
+    llm_provider: Any | None = None,
+) -> MemoryLintResult:
+    """Run all checks including LLM contradiction detection."""
+    base = lint_memory(memory_dir=memory_dir, cwd=cwd)
+
+    if llm_provider is None:
+        return base
+
+    entries = _load_entries(memory_dir)
+    contradictions = await _check_contradictions(entries, llm_provider)
+
+    return MemoryLintResult(
+        stale=base.stale,
+        contradictions=tuple(contradictions),
+        coverage_gaps=base.coverage_gaps,
+        orphans=base.orphans,
+        old=base.old,
+    )
+
+
+def _load_entries(memory_dir: Path) -> dict[str, dict]:
+    """Load memory.json entries, excluding internal keys."""
+    memory_file = memory_dir / "memory.json"
+    if not memory_file.exists():
+        return {}
+    try:
+        data = json.loads(memory_file.read_text(encoding="utf-8"))
+        return {k: v for k, v in data.items() if not k.startswith("_")}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _check_stale(entries: dict[str, dict], cwd: Path) -> list[StaleReference]:
+    """Find memory entries that reference files that no longer exist."""
+    stale: list[StaleReference] = []
+    for key, entry in entries.items():
+        value = entry.get("value", "")
+        for line_no, line in enumerate(value.splitlines(), 1):
+            for match in _FILE_PATH_RE.finditer(line):
+                ref = match.group(1)
+                if "/" in ref and not (cwd / ref).exists():
+                    stale.append(StaleReference(key=key, reference=ref, line=line_no))
+    return stale
+
+
+def _is_python_package(path: Path) -> bool:
+    """Return True if the directory looks like a Python package or source dir."""
+    return (path / "__init__.py").exists() or any(path.glob("*.py"))
+
+
+def _check_coverage_gaps(entries: dict[str, dict], cwd: Path) -> list[str]:
+    """Find source directories with no mention in any memory entry."""
+    source_dirs: set[str] = set()
+    for child in sorted(cwd.iterdir()):
+        if not child.is_dir() or child.name in _SKIP_DIRS or child.name.startswith("."):
+            continue
+        # Qualify top-level dir: has own Python files OR contains Python subdirs
+        has_python = _is_python_package(child)
+        has_python_subs = any(
+            sub.is_dir() and _is_python_package(sub)
+            for sub in child.iterdir()
+            if sub.name not in _SKIP_DIRS and not sub.name.startswith("_")
+        )
+        if has_python or has_python_subs:
+            for sub in child.iterdir():
+                if sub.is_dir() and sub.name not in _SKIP_DIRS and not sub.name.startswith("_"):
+                    if _is_python_package(sub):
+                        source_dirs.add(f"{child.name}/{sub.name}")
+
+    if not source_dirs:
+        return []
+
+    all_values = " ".join(entry.get("value", "") for entry in entries.values())
+    gaps: list[str] = []
+    for dir_path in sorted(source_dirs):
+        dir_name = dir_path.split("/")[-1]
+        if dir_name not in all_values and dir_path not in all_values:
+            gaps.append(f"{dir_path}/")
+    return gaps
+
+
+def _check_old(entries: dict[str, dict], max_age_days: int = _MAX_AGE_DAYS) -> list[str]:
+    """Find entries not updated within max_age_days."""
+    old: list[str] = []
+    cutoff = datetime.now(timezone.utc) - timedelta(days=max_age_days)
+    for key, entry in entries.items():
+        updated = entry.get("updated_at", "")
+        if not updated:
+            continue
+        try:
+            dt = datetime.fromisoformat(updated)
+            if dt < cutoff:
+                old.append(key)
+        except (ValueError, TypeError):
+            pass
+    return old
+
+
+async def _check_contradictions(
+    entries: dict[str, dict],
+    llm_provider: Any,
+) -> list[Contradiction]:
+    """Use LLM to detect contradictory memory entries."""
+    if len(entries) < 2:
+        return []
+
+    entries_text = "\n".join(
+        f"- [{key}]: {entry.get('value', '')[:200]}"
+        for key, entry in entries.items()
+    )
+
+    request = MessageRequest(
+        model="",
+        messages=(Message(role="user", content=(TextBlock(text=f"Memory entries:\n{entries_text}"),)),),
+        system=_CONTRADICTION_SYSTEM_PROMPT,
+        tools=(),
+        max_tokens=512,
+        temperature=0.2,
+    )
+
+    try:
+        response = await llm_provider.send_message(request)
+        text = ""
+        for block in response.content:
+            if hasattr(block, "text"):
+                text += block.text
+
+        parsed = json.loads(text)
+        if not isinstance(parsed, list):
+            return []
+
+        return [
+            Contradiction(
+                key_a=item.get("key_a", ""),
+                key_b=item.get("key_b", ""),
+                description=item.get("description", ""),
+            )
+            for item in parsed
+            if isinstance(item, dict)
+        ]
+    except Exception:
+        logger.debug("Contradiction check failed", exc_info=True)
+        return []

llm_code/runtime/model_aliases.py

@@ -0,0 +1,37 @@
+"""Model alias resolution."""
+from __future__ import annotations
+
+# Built-in aliases
+BUILTIN_ALIASES: dict[str, str] = {
+    # Short names
+    "gpt4o": "gpt-4o",
+    "gpt4": "gpt-4o",
+    "gpt-mini": "gpt-4o-mini",
+    "4o": "gpt-4o",
+    "4o-mini": "gpt-4o-mini",
+    "o3": "o3",
+    "o4-mini": "o4-mini",
+    # Anthropic
+    "opus": "claude-opus-4-6",
+    "sonnet": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5",
+    "claude": "claude-sonnet-4-6",
+    # Qwen shortcuts
+    "qwen": "qwen3.5",
+    "qwen-large": "Qwen3.5-122B-A10B",
+    # Ollama convenience aliases
+    "qwen-small": "qwen3:1.7b",
+    "qwen-medium": "qwen3.5:4b",
+}
+
+
+def resolve_model(model: str, custom_aliases: dict[str, str] | None = None) -> str:
+    """Resolve a model alias to its full name.
+
+    Priority: custom_aliases (from config) > BUILTIN_ALIASES > return as-is
+    """
+    if custom_aliases and model in custom_aliases:
+        return custom_aliases[model]
+    if model in BUILTIN_ALIASES:
+        return BUILTIN_ALIASES[model]
+    return model

llm_code/runtime/ollama.py

@@ -0,0 +1,93 @@
+"""Ollama API client for probe, model listing, and selection helpers."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(frozen=True)
+class OllamaModel:
+    """Represents a locally available Ollama model."""
+
+    name: str
+    size_gb: float
+    parameter_size: str
+    quantization: str
+
+    @property
+    def estimated_vram_gb(self) -> float:
+        """Estimated runtime VRAM: disk size * 1.2 for KV cache + buffers."""
+        return self.size_gb * 1.2
+
+    def fits_in_vram(self, available_gb: float) -> bool:
+        return self.estimated_vram_gb <= available_gb
+
+    def is_recommended(self, available_gb: float) -> bool:
+        """Fits within 90% of available VRAM."""
+        return self.estimated_vram_gb <= available_gb * 0.9
+
+
+class OllamaClient:
+    """Thin async client for Ollama's native API."""
+
+    def __init__(self, base_url: str = "http://localhost:11434") -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(timeout=httpx.Timeout(2.0))
+
+    async def probe(self) -> bool:
+        """Check if Ollama is reachable."""
+        try:
+            resp = await self._client.get(f"{self._base_url}/api/tags")
+            return resp.status_code == 200
+        except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout, OSError):
+            return False
+
+    async def list_models(self) -> list[OllamaModel]:
+        """Fetch locally available models from Ollama."""
+        try:
+            resp = await self._client.get(f"{self._base_url}/api/tags")
+            if resp.status_code != 200:
+                return []
+            data = resp.json()
+        except (httpx.ConnectError, httpx.ReadTimeout, httpx.WriteTimeout, OSError, ValueError):
+            return []
+
+        models: list[OllamaModel] = []
+        for entry in data.get("models", []):
+            details = entry.get("details", {})
+            size_bytes = entry.get("size", 0)
+            models.append(
+                OllamaModel(
+                    name=entry.get("name", ""),
+                    size_gb=size_bytes / (1024**3),
+                    parameter_size=details.get("parameter_size", ""),
+                    quantization=details.get("quantization_level", ""),
+                )
+            )
+        return models
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+def sort_models_for_selection(
+    models: list[OllamaModel],
+    vram_gb: float | None,
+) -> list[OllamaModel]:
+    """Sort models for the interactive selector.
+
+    With VRAM info: models that fit sorted descending (biggest first),
+    then models that don't fit sorted ascending (smallest overshoot first).
+    Without VRAM info: sorted ascending by size.
+    """
+    if vram_gb is None:
+        return sorted(models, key=lambda m: m.size_gb)
+
+    fits = [m for m in models if m.fits_in_vram(vram_gb)]
+    exceeds = [m for m in models if not m.fits_in_vram(vram_gb)]
+
+    fits.sort(key=lambda m: m.size_gb, reverse=True)
+    exceeds.sort(key=lambda m: m.size_gb)
+
+    return fits + exceeds

llm_code/runtime/overlay.py

@@ -0,0 +1,124 @@
+"""Copy-on-Write overlay filesystem for speculative tool execution."""
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+
+
+class OverlayFS:
+    """A lightweight Copy-on-Write overlay that mirrors writes to a tmpdir.
+
+    Reads check the overlay first, falling back to the real filesystem.
+    ``commit()`` copies all pending overlay files to their real paths.
+    ``discard()`` deletes the tmpdir without touching the real filesystem.
+    """
+
+    def __init__(self, base_dir: Path, session_id: str) -> None:
+        self._base_dir = base_dir
+        self._session_id = session_id
+        self._tmp_root = Path(tempfile.gettempdir()) / "llm-code-overlay"
+        self._tmp_root.mkdir(parents=True, exist_ok=True)
+        self.overlay_dir: Path = self._tmp_root / session_id
+        self.overlay_dir.mkdir(parents=True, exist_ok=True)
+        # Tracks real-path → overlay-mirror-path mappings
+        self._pending: dict[Path, Path] = {}
+
+    # ------------------------------------------------------------------
+    # Core API
+    # ------------------------------------------------------------------
+
+    def write(self, path: Path, content: str) -> None:
+        """Write *content* to the overlay mirror of *path*.
+
+        The real filesystem is not touched.
+
+        Parameters
+        ----------
+        path:
+            Absolute path on the real filesystem (write destination after commit).
+        content:
+            UTF-8 text content to stage in the overlay.
+
+        Raises
+        ------
+        ValueError
+            If *path* is not absolute.
+        """
+        if not path.is_absolute():
+            raise ValueError(f"path must be absolute, got: {path!r}")
+        mirror = self._mirror_path(path)
+        mirror.parent.mkdir(parents=True, exist_ok=True)
+        mirror.write_text(content, encoding="utf-8")
+        self._pending[path.resolve()] = mirror
+
+    def read(self, path: Path) -> str:
+        """Read content, checking the overlay first then the real filesystem.
+
+        Parameters
+        ----------
+        path:
+            Absolute path to read.
+
+        Returns
+        -------
+        str
+            UTF-8 text content.
+
+        Raises
+        ------
+        FileNotFoundError
+            If *path* is absent from both overlay and real filesystem.
+        """
+        resolved = path.resolve()
+        if resolved in self._pending:
+            return self._pending[resolved].read_text(encoding="utf-8")
+        if path.exists():
+            return path.read_text(encoding="utf-8")
+        raise FileNotFoundError(f"File not found in overlay or real FS: {path}")
+
+    def commit(self) -> None:
+        """Copy all pending overlay files to their real-filesystem paths.
+
+        Parent directories are created as needed. The overlay tmpdir is
+        *not* removed by this call; call ``discard()`` afterwards if desired.
+        """
+        for real_path, mirror_path in self._pending.items():
+            real_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(mirror_path, real_path)
+
+    def discard(self) -> None:
+        """Delete the overlay tmpdir without writing to the real filesystem."""
+        if self.overlay_dir.exists():
+            shutil.rmtree(self.overlay_dir, ignore_errors=True)
+        self._pending.clear()
+
+    def list_pending(self) -> list[Path]:
+        """Return the list of real paths that have been staged in the overlay."""
+        return list(self._pending.keys())
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "OverlayFS":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        if exc_type is not None:
+            self.discard()
+        return False  # never suppress exceptions
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _mirror_path(self, real_path: Path) -> Path:
+        """Translate a real absolute path to its overlay mirror path."""
+        # Strip the leading separator so we can join with overlay_dir
+        try:
+            rel = real_path.resolve().relative_to("/")
+        except ValueError:
+            # On Windows paths like C:\...; use str-based stripping
+            rel = Path(str(real_path.resolve()).lstrip("/\\"))
+        return self.overlay_dir / rel