devcouncil 0.1.1 → 0.3.0

package/src/devcouncil/hardware.py

@@ -0,0 +1,184 @@
+"""Host hardware detection used to size local (Ollama) models.
+
+DevCouncil runs the council roles against whatever LLM provider is configured.
+For the local ``ollama`` provider the model has to fit in host memory. On Apple
+Silicon Macs that memory is *unified* (shared by CPU/GPU/OS), so total RAM is the
+ceiling. On a host with a discrete GPU (NVIDIA), Ollama offloads to VRAM, so the
+*VRAM* is the practical ceiling instead — a 64 GB box with an 8 GB GPU should not be
+told to run a model that only fits in system RAM. This module exposes small, pure
+helpers so ``dev doctor`` and ``dev setup`` can recommend a model that will actually
+run instead of a one-size-fits-all default, on macOS, Linux and Windows.
+
+Everything here is best-effort and stdlib-only: detection failures return
+``None`` rather than raising, so callers degrade to the static default.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import shutil
+import subprocess
+from dataclasses import dataclass
+
+# Recommended Ollama context window for DevCouncil's large planning prompts.
+# Kept in sync with the value surfaced by `dev doctor`.
+RECOMMENDED_NUM_CTX = 16384
+
+# Fallback model when the host is unknown or has little memory. Matches the
+# static defaults in ``llm/model_defaults.yaml``.
+DEFAULT_OLLAMA_MODEL = "qwen2.5-coder:7b"
+
+# RAM (GiB) -> recommended qwen2.5-coder size. Highest matching tier wins.
+# Sizes are chosen so the quantized weights plus a 16k context comfortably fit
+# alongside the OS in Apple Silicon unified memory.
+_OLLAMA_MODEL_TIERS: tuple[tuple[float, str], ...] = (
+    (48.0, "qwen2.5-coder:32b"),
+    (24.0, "qwen2.5-coder:14b"),
+    (0.0, "qwen2.5-coder:7b"),
+)
+
+
+def is_macos() -> bool:
+    return platform.system() == "Darwin"
+
+
+def is_apple_silicon() -> bool:
+    """True on Apple-Silicon (arm64) Macs."""
+    return is_macos() and platform.machine() == "arm64"
+
+
+def mac_chip_brand() -> str | None:
+    """Marketing CPU string on macOS (e.g. ``Apple M3 Pro``), else None."""
+    if not is_macos():
+        return None
+    try:
+        out = subprocess.check_output(
+            ["sysctl", "-n", "machdep.cpu.brand_string"],
+            text=True,
+            timeout=5,
+        ).strip()
+        return out or None
+    except Exception:
+        return None
+
+
+def total_ram_gb() -> float | None:
+    """Total physical RAM in GiB, or None if it cannot be determined."""
+    try:
+        if is_macos():
+            out = subprocess.check_output(
+                ["sysctl", "-n", "hw.memsize"], text=True, timeout=5
+            ).strip()
+            return int(out) / (1024**3)
+        # POSIX (Linux): pages * page size.
+        pages = os.sysconf("SC_PHYS_PAGES")
+        page_size = os.sysconf("SC_PAGE_SIZE")
+        return (pages * page_size) / (1024**3)
+    except (OSError, ValueError, AttributeError, subprocess.SubprocessError):
+        return None
+
+
+def nvidia_vram_gb() -> float | None:
+    """Total VRAM (GiB) of the largest NVIDIA GPU via ``nvidia-smi``, else ``None``.
+
+    On hosts with a discrete NVIDIA GPU this is the real ceiling for Ollama, since the
+    model is offloaded to VRAM. Returns ``None`` when ``nvidia-smi`` is absent (no GPU,
+    Apple Silicon, or an unsupported vendor), so callers fall back to total RAM."""
+    if not shutil.which("nvidia-smi"):
+        return None
+    try:
+        out = subprocess.check_output(
+            ["nvidia-smi", "--query-gpu=memory.total", "--format=csv,noheader,nounits"],
+            text=True,
+            timeout=5,
+            stderr=subprocess.DEVNULL,
+        ).strip()
+    except (OSError, subprocess.SubprocessError):
+        return None
+    sizes_mib: list[float] = []
+    for line in out.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            sizes_mib.append(float(line))
+        except ValueError:
+            continue
+    if not sizes_mib:
+        return None
+    return max(sizes_mib) / 1024.0  # MiB -> GiB
+
+
+def recommend_ollama_model(ram_gb: float | None = None, vram_gb: float | None = None) -> str:
+    """Largest qwen2.5-coder size expected to run on the host.
+
+    When a discrete GPU's ``vram_gb`` is known it is the ceiling (Ollama offloads to
+    VRAM); otherwise total system RAM is used (correct for unified-memory Macs and
+    CPU-only hosts)."""
+    if ram_gb is None:
+        ram_gb = total_ram_gb()
+    effective = vram_gb if vram_gb is not None else ram_gb
+    if effective is None:
+        return DEFAULT_OLLAMA_MODEL
+    for floor, model in _OLLAMA_MODEL_TIERS:
+        if effective >= floor:
+            return model
+    return DEFAULT_OLLAMA_MODEL
+
+
+@dataclass(frozen=True)
+class HostSummary:
+    """A snapshot of the host relevant to local-model sizing."""
+
+    is_macos: bool
+    is_apple_silicon: bool
+    chip: str | None
+    ram_gb: float | None
+    recommended_ollama_model: str
+    vram_gb: float | None = None
+
+    @property
+    def ram_label(self) -> str:
+        return f"{self.ram_gb:.0f} GB" if self.ram_gb is not None else "unknown RAM"
+
+    @property
+    def vram_label(self) -> str | None:
+        return f"{self.vram_gb:.0f} GB VRAM" if self.vram_gb is not None else None
+
+    @property
+    def chip_label(self) -> str:
+        if self.chip:
+            return self.chip
+        if self.is_apple_silicon:
+            return "Apple Silicon"
+        if self.vram_gb is not None:
+            return "discrete GPU host"
+        return "this host"
+
+    @property
+    def platform_label(self) -> str:
+        """Human label for the sizing row across OSes."""
+        if self.is_macos:
+            return "Apple Silicon" if self.is_apple_silicon else "Mac (Intel)"
+        system = platform.system()
+        return system or "Host"
+
+    @property
+    def memory_label(self) -> str:
+        """Memory ceiling used for the recommendation (VRAM if discrete GPU, else RAM)."""
+        vram = self.vram_label
+        return f"{vram} (GPU)" if vram else self.ram_label
+
+
+def describe_host() -> HostSummary:
+    ram = total_ram_gb()
+    vram = nvidia_vram_gb()
+    return HostSummary(
+        is_macos=is_macos(),
+        is_apple_silicon=is_apple_silicon(),
+        chip=mac_chip_brand(),
+        ram_gb=ram,
+        vram_gb=vram,
+        recommended_ollama_model=recommend_ollama_model(ram, vram),
+    )

package/src/devcouncil/indexing/ast_matcher.py

@@ -59,7 +59,7 @@ class AstMatcher:
 
     def _has_tree_sitter(self) -> bool:
         try:
-            import tree_sitter  # noqa: F401
+            import tree_sitter  # type: ignore[import-not-found]  # noqa: F401
         except Exception:
             return False
         return True
@@ -71,12 +71,13 @@ class AstMatcher:
         language: str | None = None,
         kind: str | None = None,
         limit: int = 100,
+        files: list[Path] | None = None,
     ) -> list[AstMatch]:
         language = language.lower() if language else None
         kind = kind.lower() if kind else None
         limit = max(1, limit)
         matches: list[AstMatch] = []
-        for path in self._candidate_files(language):
+        for path in self._candidate_files(language, files):
             try:
                 text = path.read_text(encoding="utf-8")
             except (OSError, UnicodeDecodeError):
@@ -88,22 +89,31 @@ class AstMatcher:
                 return matches[:limit]
         return matches[:limit]
 
-    def _candidate_files(self, language: str | None) -> list[Path]:
+    def _candidate_files(self, language: str | None, files: list[Path] | None = None) -> list[Path]:
         allowed_exts = {
             ext for ext, ext_language in self._EXT_LANGUAGE.items()
             if language is None or ext_language == language
         }
-        files: list[Path] = []
+        # When the caller already walked the tree (e.g. SemanticIndex.create_snapshot
+        # shares one traversal across all collectors), filter that list in memory
+        # instead of re-globbing. The filter is identical to the rglob path below.
+        if files is not None:
+            return sorted(
+                path for path in files
+                if path.is_file() and path.suffix.lower() in allowed_exts
+                and not any(part in self._IGNORED_DIRS for part in path.parts)
+            )
+        candidates: list[Path] = []
         try:
             for path in self.project_root.rglob("*"):
                 if not path.is_file() or path.suffix.lower() not in allowed_exts:
                     continue
                 if any(part in self._IGNORED_DIRS for part in path.parts):
                     continue
-                files.append(path)
+                candidates.append(path)
         except OSError:
-            return files
-        return sorted(files)
+            return candidates
+        return sorted(candidates)
 
     def _match_file(self, rel: str, language: str, text: str, *, query: str, kind: str | None) -> list[AstMatch]:
         if language == "python":

package/src/devcouncil/indexing/lsp.py

@@ -16,7 +16,16 @@ class LspServerCandidate:
 
 
 class LspInspector:
-    """Starter LSP integration focused on discovery and safe initialize payloads."""
+    """Language-server *detection* only — DevCouncil does not run an LSP client.
+
+    This inspector exists to answer one honest question: which language servers
+    for the repo's languages are installed on PATH? It does NOT spawn a server,
+    does NOT speak the LSP wire protocol, and does NOT send the ``initialize``
+    handshake. ``starter_initialize_payload`` builds the JSON-RPC ``initialize``
+    request a *future* client would send, but it is never transmitted — it is
+    surfaced purely as a reference/starter payload, clearly labelled as such, so
+    no consumer mistakes detection for a live LSP capability.
+    """
 
     _LANGUAGE_SERVERS: dict[str, list[list[str]]] = {
         "python": [["pyright-langserver", "--stdio"], ["pylsp"]],
@@ -76,7 +85,14 @@ class LspInspector:
                 )
         return candidates
 
-    def initialize_request(self, language: str) -> dict[str, Any]:
+    def starter_initialize_payload(self, language: str) -> dict[str, Any]:
+        """Build the JSON-RPC ``initialize`` request a future LSP client *would* send.
+
+        This payload is NEVER sent — DevCouncil has no LSP client. It is provided
+        only as a reference/starter for anyone wiring up real LSP support. See the
+        ``initialize_requests`` block in :meth:`summary`, which carries the same
+        non-sent payloads under an explicit ``"_note"`` disclaimer.
+        """
         return {
             "jsonrpc": "2.0",
             "id": 1,
@@ -97,10 +113,32 @@ class LspInspector:
             },
         }
 
+    # Made explicit in every summary so no consumer reads this as a live LSP feature.
+    _DETECTION_ONLY_NOTE = (
+        "Detection only: DevCouncil checks which language servers are installed on "
+        "PATH; it does not run an LSP client or send any requests."
+    )
+    _STARTER_PAYLOAD_NOTE = (
+        "Starter payloads only — these initialize requests are NEVER sent. They are "
+        "a reference for wiring up a real LSP client later."
+    )
+
     def summary(self, files: list[str] | None = None) -> dict[str, Any]:
         candidates = self.server_candidates(files)
         return {
+            "mode": "detection-only",
+            "note": self._DETECTION_ONLY_NOTE,
             "languages": self.detect_languages(files),
+            "detected_servers": [
+                {
+                    "language": candidate.language,
+                    "command": candidate.command,
+                    "available": candidate.available,
+                    "reason": candidate.reason,
+                }
+                for candidate in candidates
+            ],
+            # Back-compat alias for "detected_servers" (older consumers/tests).
             "servers": [
                 {
                     "language": candidate.language,
@@ -111,8 +149,11 @@ class LspInspector:
                 for candidate in candidates
             ],
             "initialize_requests": {
-                language: self.initialize_request(language)
-                for language in sorted({candidate.language for candidate in candidates})
+                "_note": self._STARTER_PAYLOAD_NOTE,
+                **{
+                    language: self.starter_initialize_payload(language)
+                    for language in sorted({candidate.language for candidate in candidates})
+                },
             },
         }