devcouncil 0.1.0 → 0.2.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/__init__.py

@@ -1 +1 @@
-
+

package/src/devcouncil/indexing/ast_matcher.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import ast
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class AstMatch:
+    path: str
+    language: str
+    kind: str
+    name: str
+    line: int
+    text: str
+    engine: str
+
+    def model_dump(self) -> dict[str, object]:
+        return {
+            "path": self.path,
+            "language": self.language,
+            "kind": self.kind,
+            "name": self.name,
+            "line": self.line,
+            "text": self.text,
+            "engine": self.engine,
+        }
+
+
+class AstMatcher:
+    """Tree-sitter-style structural search with optional tree_sitter and deterministic fallbacks."""
+
+    _EXT_LANGUAGE = {
+        ".py": "python",
+        ".ts": "typescript",
+        ".tsx": "typescript",
+        ".js": "javascript",
+        ".jsx": "javascript",
+        ".go": "go",
+        ".rs": "rust",
+    }
+
+    _SYMBOL_PATTERNS: dict[str, re.Pattern[str]] = {
+        "typescript": re.compile(
+            r"^\s*(?:export\s+)?(?:(?:async\s+)?(?:function|class|interface|type)\s+|const\s+)([A-Za-z_$][\w$]*)"
+        ),
+        "javascript": re.compile(
+            r"^\s*(?:export\s+)?(?:(?:async\s+)?(?:function|class)\s+|const\s+)([A-Za-z_$][\w$]*)"
+        ),
+        "go": re.compile(r"^\s*func\s+(?:\([^)]+\)\s*)?([A-Za-z_]\w*)\s*\("),
+        "rust": re.compile(r"^\s*(?:pub\s+)?(?:async\s+)?(?:fn|struct|enum|trait)\s+([A-Za-z_]\w*)"),
+    }
+    _IGNORED_DIRS = {".git", ".devcouncil", "__pycache__", ".venv", "node_modules", "dist", "build", "target", "vendor"}
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.tree_sitter_available = self._has_tree_sitter()
+
+    def _has_tree_sitter(self) -> bool:
+        try:
+            import tree_sitter  # type: ignore[import-not-found]  # noqa: F401
+        except Exception:
+            return False
+        return True
+
+    def match(
+        self,
+        *,
+        query: str = "",
+        language: str | None = None,
+        kind: str | None = None,
+        limit: int = 100,
+    ) -> 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):
+            try:
+                text = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            rel = path.relative_to(self.project_root).as_posix()
+            file_language = self._EXT_LANGUAGE.get(path.suffix.lower(), path.suffix.lower().lstrip("."))
+            matches.extend(self._match_file(rel, file_language, text, query=query, kind=kind))
+            if len(matches) >= limit:
+                return matches[:limit]
+        return matches[:limit]
+
+    def _candidate_files(self, language: str | 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] = []
+        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)
+        except OSError:
+            return files
+        return sorted(files)
+
+    def _match_file(self, rel: str, language: str, text: str, *, query: str, kind: str | None) -> list[AstMatch]:
+        if language == "python":
+            return self._match_python(rel, text, query=query, kind=kind)
+        pattern = self._SYMBOL_PATTERNS.get(language)
+        if not pattern:
+            return []
+        results: list[AstMatch] = []
+        for lineno, line in enumerate(text.splitlines(), start=1):
+            match = pattern.match(line)
+            if not match:
+                continue
+            symbol_name = match.group(1)
+            symbol_kind = self._line_kind(line)
+            if kind and kind != symbol_kind:
+                continue
+            if query and query.lower() not in symbol_name.lower() and query.lower() not in line.lower():
+                continue
+            results.append(AstMatch(rel, language, symbol_kind, symbol_name, lineno, line.strip(), self._engine()))
+        return results
+
+    def _match_python(self, rel: str, text: str, *, query: str, kind: str | None) -> list[AstMatch]:
+        try:
+            tree = ast.parse(text)
+        except SyntaxError:
+            return []
+        lines = text.splitlines()
+        results: list[AstMatch] = []
+        for node in ast.walk(tree):
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                symbol_kind = "function"
+            elif isinstance(node, ast.ClassDef):
+                symbol_kind = "class"
+            else:
+                continue
+            symbol_name = node.name
+            source = lines[node.lineno - 1].strip() if 0 < node.lineno <= len(lines) else symbol_name
+            if kind and kind != symbol_kind:
+                continue
+            if query and query.lower() not in symbol_name.lower() and query.lower() not in source.lower():
+                continue
+            results.append(AstMatch(rel, "python", symbol_kind, symbol_name, node.lineno, source, self._engine()))
+        return sorted(results, key=lambda item: (item.path, item.line))
+
+    def _line_kind(self, line: str) -> str:
+        stripped = line.strip()
+        if "class " in stripped:
+            return "class"
+        if stripped.startswith(("type ", "export type ")):
+            return "type"
+        if stripped.startswith(("interface ", "export interface ")):
+            return "interface"
+        if stripped.startswith(("struct ", "pub struct ")):
+            return "struct"
+        if stripped.startswith(("enum ", "pub enum ")):
+            return "enum"
+        if stripped.startswith(("trait ", "pub trait ")):
+            return "trait"
+        return "function"
+
+    def _engine(self) -> str:
+        return "tree-sitter-optional" if self.tree_sitter_available else "fallback-ast"

package/src/devcouncil/indexing/graph_index.py

@@ -1,48 +1,48 @@
-from typing import List, Dict, Any, Set
-from pydantic import BaseModel, Field
-from pathlib import Path
-
-class GraphNode(BaseModel):
-    id: str
-    type: str # "file", "symbol", "requirement", "task"
-    metadata: Dict[str, Any] = Field(default_factory=dict)
-
-class GraphEdge(BaseModel):
-    source: str
-    target: str
-    relation: str # "imports", "implements", "validates", "contains"
-
-class KnowledgeGraph(BaseModel):
-    nodes: List[GraphNode] = []
-    edges: List[GraphEdge] = []
-
-class GraphIndex:
-    def __init__(self, project_root: Path):
-        self.project_root = project_root
-        self.graph = KnowledgeGraph()
-
-    def build_initial_graph(self, files: List[str]):
-        """
-        Bootstrap the graph from file list.
-        """
-        for f in files:
-            self.graph.nodes.append(GraphNode(
-                id=f,
-                type="file",
-                metadata={"extension": Path(f).suffix}
-            ))
-
-    def add_relation(self, source: str, target: str, relation: str):
-        self.graph.edges.append(GraphEdge(source=source, target=target, relation=relation))
-
-    def get_context_for_file(self, file_path: str) -> Set[str]:
-        """
-        Retrieve related paths for a given file.
-        """
-        related = {file_path}
-        for edge in self.graph.edges:
-            if edge.source == file_path:
-                related.add(edge.target)
-            if edge.target == file_path:
-                related.add(edge.source)
-        return related
+from typing import List, Dict, Any, Set
+from pydantic import BaseModel, Field
+from pathlib import Path
+
+class GraphNode(BaseModel):
+    id: str
+    type: str # "file", "symbol", "requirement", "task"
+    metadata: Dict[str, Any] = Field(default_factory=dict)
+
+class GraphEdge(BaseModel):
+    source: str
+    target: str
+    relation: str # "imports", "implements", "validates", "contains"
+
+class KnowledgeGraph(BaseModel):
+    nodes: List[GraphNode] = []
+    edges: List[GraphEdge] = []
+
+class GraphIndex:
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+        self.graph = KnowledgeGraph()
+
+    def build_initial_graph(self, files: List[str]):
+        """
+        Bootstrap the graph from file list.
+        """
+        for f in files:
+            self.graph.nodes.append(GraphNode(
+                id=f,
+                type="file",
+                metadata={"extension": Path(f).suffix}
+            ))
+
+    def add_relation(self, source: str, target: str, relation: str):
+        self.graph.edges.append(GraphEdge(source=source, target=target, relation=relation))
+
+    def get_context_for_file(self, file_path: str) -> Set[str]:
+        """
+        Retrieve related paths for a given file.
+        """
+        related = {file_path}
+        for edge in self.graph.edges:
+            if edge.source == file_path:
+                related.add(edge.target)
+            if edge.target == file_path:
+                related.add(edge.source)
+        return related

package/src/devcouncil/indexing/lsp.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class LspServerCandidate:
+    language: str
+    command: list[str]
+    available: bool
+    reason: str
+
+
+class LspInspector:
+    """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"]],
+        "typescript": [["typescript-language-server", "--stdio"]],
+        "javascript": [["typescript-language-server", "--stdio"]],
+        "go": [["gopls"]],
+        "rust": [["rust-analyzer"]],
+    }
+
+    _EXTENSIONS: dict[str, str] = {
+        ".py": "python",
+        ".ts": "typescript",
+        ".tsx": "typescript",
+        ".js": "javascript",
+        ".jsx": "javascript",
+        ".go": "go",
+        ".rs": "rust",
+    }
+    _IGNORED_DIRS = {".git", ".devcouncil", "__pycache__", ".venv", "node_modules", "dist", "build", "target", "vendor"}
+
+    def __init__(self, project_root: Path):
+        self.project_root = project_root
+
+    def _is_ignored_path(self, file: str) -> bool:
+        return any(part in self._IGNORED_DIRS for part in Path(file).parts)
+
+    def detect_languages(self, files: list[str] | None = None) -> list[str]:
+        if files is None:
+            try:
+                discovered: list[str] = []
+                for path in self.project_root.rglob("*"):
+                    if path.is_file() and not any(part in self._IGNORED_DIRS for part in path.parts):
+                        discovered.append(str(path.relative_to(self.project_root)))
+                files = discovered
+            except OSError:
+                files = []
+        languages = {
+            self._EXTENSIONS[Path(file).suffix.lower()]
+            for file in files
+            if Path(file).suffix.lower() in self._EXTENSIONS and not self._is_ignored_path(file)
+        }
+        return sorted(languages)
+
+    def server_candidates(self, files: list[str] | None = None) -> list[LspServerCandidate]:
+        candidates: list[LspServerCandidate] = []
+        for language in self.detect_languages(files):
+            for command in self._LANGUAGE_SERVERS.get(language, []):
+                executable = command[0]
+                available = shutil.which(executable) is not None
+                candidates.append(
+                    LspServerCandidate(
+                        language=language,
+                        command=command,
+                        available=available,
+                        reason="found on PATH" if available else "not found on PATH",
+                    )
+                )
+        return candidates
+
+    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,
+            "method": "initialize",
+            "params": {
+                "processId": None,
+                "rootUri": self.project_root.resolve().as_uri(),
+                "capabilities": {
+                    "textDocument": {
+                        "publishDiagnostics": {"relatedInformation": True},
+                        "definition": {"linkSupport": True},
+                        "references": {},
+                        "documentSymbol": {"hierarchicalDocumentSymbolSupport": True},
+                    },
+                    "workspace": {"symbol": {}},
+                },
+                "initializationOptions": {"language": language},
+            },
+        }
+
+    # 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,
+                    "command": candidate.command,
+                    "available": candidate.available,
+                    "reason": candidate.reason,
+                }
+                for candidate in candidates
+            ],
+            "initialize_requests": {
+                "_note": self._STARTER_PAYLOAD_NOTE,
+                **{
+                    language: self.starter_initialize_payload(language)
+                    for language in sorted({candidate.language for candidate in candidates})
+                },
+            },
+        }
+
+    def summary_json(self, files: list[str] | None = None) -> str:
+        return json.dumps(self.summary(files), indent=2)