minder-cli 0.2.0__py3-none-any.whl

minder/graph/nodes/planning.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from minder.graph.state import GraphState
+
+
+class PlanningNode:
+    def run(self, state: GraphState) -> GraphState:
+        query = state.query.lower()
+        intent = "explain"
+        if any(word in query for word in ("fix", "implement", "write", "generate")):
+            intent = "code_gen"
+        elif any(word in query for word in ("debug", "bug", "trace", "error")):
+            intent = "debug"
+        elif "refactor" in query:
+            intent = "refactor"
+        elif any(word in query for word in ("search", "find", "look up")):
+            intent = "search"
+
+        retrieval_strategy = "hybrid"
+        if intent == "search":
+            retrieval_strategy = "lexical"
+        complexity = "high" if len(query.split()) > 12 else "medium"
+
+        state.plan = {
+            "intent": intent,
+            "knowledge_layer": "repository",
+            "retrieval_strategy": retrieval_strategy,
+            "complexity": complexity,
+        }
+        return state

minder/graph/nodes/reasoning.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+
+from minder.graph.state import GraphState
+from minder.prompts import PromptRegistry
+from minder.tools.registry import tool_capability_manifest, tool_data_access_policy
+
+
+class ReasoningNode:
+    def run(self, state: GraphState) -> GraphState:
+        sources = [
+            {"path": doc["path"], "title": doc["title"], "score": doc["score"]}
+            for doc in state.reranked_docs
+        ]
+        snippets = []
+        for doc in state.reranked_docs[:3]:
+            content = str(doc["content"]).strip()
+            snippets.append(f"Source: {doc['path']}\n{content[:240]}")
+
+        guidance = state.workflow_context.get("guidance", "")
+        instruction_envelope = state.workflow_context.get("instruction_envelope", {})
+        continuity_brief = state.workflow_context.get("continuity_brief", {})
+        retry_reason = str(state.metadata.get("retry_reason", "") or "").strip()
+        continuity_packet = continuity_brief or {}
+        prompt_template = str(
+            state.metadata.get("query_prompt_template")
+            or (PromptRegistry.get_builtin_definition("query_reasoning") or {}).get(
+                "content_template", ""
+            )
+        )
+        prompt_defaults = dict(state.metadata.get("query_prompt_defaults", {}) or {})
+        prompt = PromptRegistry.render_content_template(
+            prompt_template,
+            {
+                "workflow_instruction": guidance,
+                "instruction_envelope": (
+                    json.dumps(
+                        instruction_envelope,
+                        indent=2,
+                        sort_keys=True,
+                    )
+                    if instruction_envelope
+                    else "{}"
+                ),
+                "continuity_brief": (
+                    json.dumps(
+                        continuity_brief,
+                        indent=2,
+                        sort_keys=True,
+                    )
+                    if continuity_brief
+                    else "{}"
+                ),
+                "continuity_packet": (
+                    json.dumps(
+                        continuity_packet,
+                        indent=2,
+                        sort_keys=True,
+                    )
+                    if continuity_packet
+                    else "{}"
+                ),
+                "tool_capabilities": tool_capability_manifest(),
+                "data_access_policy": tool_data_access_policy(),
+                "repository_context_note": (
+                    "Repository context is available for repo-scoped reasoning."
+                    if state.repo_path
+                    else "No repository is currently selected. Minder can still describe its built-in tools and internal data capabilities, but repo-scoped code and graph inspection tools need repository context first."
+                ),
+                "user_query": state.query,
+                "retrieved_context": (
+                    "\n\n".join(snippets)
+                    if snippets
+                    else "No repository context found."
+                ),
+                "correction_required": retry_reason,
+            },
+            defaults=prompt_defaults,
+        )
+        state.reasoning_output = {
+            "prompt": prompt,
+            "sources": sources,
+            "workflow_instruction": guidance,
+            "prompt_name": state.metadata.get("query_prompt_name", "query_reasoning"),
+        }
+        return state

minder/graph/nodes/reranker.py

@@ -0,0 +1,141 @@
+"""
+RerankerNode — re-ranks state.retrieved_docs into state.reranked_docs.
+
+Runtime strategy (tried in order):
+  1. ``sentence_transformers.CrossEncoder`` — if the package is installed and
+     the model loads successfully.
+  2. MMR with document embeddings — if an ``embedding_provider`` is supplied.
+  3. Passthrough — sort by existing score, no re-scoring.
+
+The node always writes ``state.reranked_docs`` and records
+``state.metadata["reranker_runtime"]`` with the strategy used.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from minder.embedding.base import EmbeddingProvider
+from minder.graph.state import GraphState
+from minder.retrieval.mmr import mmr_rerank
+from minder.runtime import load_attr, module_available
+
+
+class RerankerNode:
+    """
+    Args:
+        top_k: maximum number of documents to keep after re-ranking.
+        lambda_mult: MMR trade-off (0 = max diversity, 1 = max relevance).
+        cross_encoder_model: HuggingFace model id used when
+            ``sentence_transformers`` is available.
+        embedding_provider: optional embedder used for MMR fallback.
+    """
+
+    def __init__(
+        self,
+        *,
+        top_k: int = 5,
+        lambda_mult: float = 0.5,
+        cross_encoder_model: str = "cross-encoder/ms-marco-MiniLM-L-6-v2",
+        embedding_provider: EmbeddingProvider | None = None,
+    ) -> None:
+        self._top_k = top_k
+        self._lambda_mult = lambda_mult
+        self._cross_encoder_model = cross_encoder_model
+        self._embedding_provider = embedding_provider
+        self._cross_encoder: Any | None = None
+
+    # ------------------------------------------------------------------
+    # Runtime detection
+    # ------------------------------------------------------------------
+
+    @property
+    def runtime(self) -> str:
+        if module_available("sentence_transformers"):
+            return "cross_encoder"
+        if self._embedding_provider is not None:
+            return "mmr"
+        return "passthrough"
+
+    def _load_cross_encoder(self) -> Any | None:
+        if self._cross_encoder is not None:
+            return self._cross_encoder
+        ce_cls = load_attr("sentence_transformers", "CrossEncoder")
+        if ce_cls is None:
+            return None
+        try:
+            self._cross_encoder = ce_cls(self._cross_encoder_model)
+        except Exception:  # noqa: BLE001
+            return None
+        return self._cross_encoder
+
+    # ------------------------------------------------------------------
+    # Main entry point
+    # ------------------------------------------------------------------
+
+    async def run(self, state: GraphState) -> GraphState:
+        docs = list(state.retrieved_docs)
+        if not docs:
+            state.reranked_docs = []
+            state.metadata["reranker_runtime"] = "passthrough"
+            return state
+
+        # ---- Strategy 1: cross-encoder ----
+        ce = self._load_cross_encoder()
+        if ce is not None:
+            reranked = self._run_cross_encoder(ce, state.query, docs)
+            if reranked is not None:
+                state.reranked_docs = reranked
+                state.metadata["reranker_runtime"] = "cross_encoder"
+                return state
+
+        # ---- Strategy 2: MMR with embeddings ----
+        if self._embedding_provider is not None:
+            state.reranked_docs = self._run_mmr(state.query, docs)
+            state.metadata["reranker_runtime"] = "mmr"
+            return state
+
+        # ---- Strategy 3: passthrough (score sort) ----
+        state.reranked_docs = sorted(
+            docs, key=lambda d: float(d.get("score", 0.0)), reverse=True
+        )[: self._top_k]
+        state.metadata["reranker_runtime"] = "passthrough"
+        return state
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _run_cross_encoder(
+        self, ce: Any, query: str, docs: list[dict[str, Any]]
+    ) -> list[dict[str, Any]] | None:
+        try:
+            pairs = [[query, str(doc.get("content", ""))] for doc in docs]
+            scores = ce.predict(pairs)
+            scored = [
+                {**doc, "score": float(score)}
+                for doc, score in zip(docs, scores, strict=False)
+            ]
+            scored.sort(key=lambda d: float(d["score"]), reverse=True)
+            return scored[: self._top_k]
+        except Exception:  # noqa: BLE001
+            return None
+
+    def _run_mmr(self, query: str, docs: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        assert self._embedding_provider is not None  # guarded by caller
+        query_emb = self._embedding_provider.embed(query)
+        enriched: list[dict[str, Any]] = []
+        for doc in docs:
+            d = dict(doc)
+            if not isinstance(d.get("embedding"), list):
+                # Embed truncated content to stay within model context
+                d["embedding"] = self._embedding_provider.embed(
+                    str(d.get("content", ""))[:512]
+                )
+            enriched.append(d)
+        return mmr_rerank(
+            query_emb,
+            enriched,
+            top_k=self._top_k,
+            lambda_mult=self._lambda_mult,
+        )

minder/graph/nodes/retriever.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from typing import cast
+
+from minder.embedding.base import EmbeddingProvider
+from minder.graph.state import GraphState
+from minder.store.interfaces import IVectorStore
+
+
+class RetrieverNode:
+    def __init__(
+        self,
+        top_k: int = 5,
+        *,
+        embedding_provider: EmbeddingProvider | None = None,
+        vector_store: IVectorStore | None = None,
+        score_threshold: float = 0.0,
+    ) -> None:
+        self._top_k = top_k
+        self._embedding_provider = embedding_provider
+        self._vector_store = vector_store
+        self._score_threshold = score_threshold
+
+    async def run(self, state: GraphState) -> GraphState:
+        project = state.metadata.get("project_name")
+        if state.repo_path is None and not isinstance(project, str):
+            state.retrieved_docs = []
+            state.reranked_docs = []
+            state.metadata["retrieval_mode"] = "none"
+            return state
+
+        if self._embedding_provider is not None and self._vector_store is not None:
+            embedded = self._embedding_provider.embed(state.query)
+            semantic_hits = await self._vector_store.search_documents(
+                embedded,
+                project=str(project) if isinstance(project, str) else None,
+                limit=self._top_k,
+                score_threshold=self._score_threshold,
+            )
+            if semantic_hits:
+                state.retrieved_docs = semantic_hits
+                state.reranked_docs = list(semantic_hits)
+                state.metadata["retrieval_mode"] = "vector"
+                return state
+
+        repo_path = Path(state.repo_path or ".")
+        query_terms = {term for term in state.query.lower().split() if len(term) > 2}
+        candidates: list[dict[str, Any]] = []
+        if repo_path.exists():
+            for path in repo_path.rglob("*"):
+                if not path.is_file():
+                    continue
+                if any(
+                    part.startswith(".") and part != ".minder" for part in path.parts
+                ):
+                    continue
+                if path.suffix not in {".py", ".md", ".txt", ".json"}:
+                    continue
+                try:
+                    content = path.read_text(encoding="utf-8")
+                except UnicodeDecodeError:
+                    continue
+                lowered = content.lower()
+                score = sum(lowered.count(term) for term in query_terms)
+                if score == 0 and query_terms:
+                    continue
+                candidates.append(
+                    {
+                        "title": path.name,
+                        "path": str(path),
+                        "content": content,
+                        "score": float(score),
+                        "doc_type": "code" if path.suffix == ".py" else "markdown",
+                    }
+                )
+        ranked = sorted(
+            candidates,
+            key=lambda item: cast(float, item["score"]),
+            reverse=True,
+        )
+        state.retrieved_docs = ranked[: self._top_k]
+        state.reranked_docs = list(state.retrieved_docs)
+        state.metadata["retrieval_mode"] = "lexical"
+        return state

minder/graph/nodes/verification.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+from typing import Protocol
+
+from minder.graph.state import GraphState
+
+
+class VerificationRunner(Protocol):
+    def run_python(self, code: str, timeout_seconds: int, repo_path: str | None) -> dict[str, object]:
+        ...
+
+
+class SubprocessVerificationRunner:
+    def run_python(
+        self,
+        code: str,
+        timeout_seconds: int,
+        repo_path: str | None,
+    ) -> dict[str, object]:
+        cwd = repo_path or "."
+        try:
+            with tempfile.TemporaryDirectory() as temp_dir:
+                script_path = Path(temp_dir) / "snippet.py"
+                script_path.write_text(code, encoding="utf-8")
+                completed = subprocess.run(
+                    [sys.executable, str(script_path)],
+                    capture_output=True,
+                    text=True,
+                    cwd=cwd,
+                    timeout=timeout_seconds,
+                    check=False,
+                )
+        except subprocess.TimeoutExpired as exc:
+            return {
+                "passed": False,
+                "returncode": 124,
+                "stdout": exc.stdout or "",
+                "stderr": exc.stderr or "subprocess verification timed out",
+                "runner": "subprocess",
+                "timeout_seconds": timeout_seconds,
+                "failure_kind": "timeout",
+                "retryable": False,
+            }
+        return {
+            "passed": completed.returncode == 0,
+            "returncode": completed.returncode,
+            "stdout": completed.stdout,
+            "stderr": completed.stderr,
+            "runner": "subprocess",
+            "timeout_seconds": timeout_seconds,
+            "failure_kind": "runtime_error" if completed.returncode != 0 else None,
+            "retryable": False,
+        }
+
+
+class DockerSandboxRunner:
+    def __init__(self, image: str = "minder-sandbox:latest") -> None:
+        self._image = image
+
+    def run_python(
+        self,
+        code: str,
+        timeout_seconds: int,
+        repo_path: str | None,
+    ) -> dict[str, object]:
+        docker_binary = shutil.which("docker")
+        if docker_binary is None:
+            return {
+                "passed": False,
+                "returncode": 127,
+                "stdout": "",
+                "stderr": "docker binary not available",
+                "runner": "docker",
+                "timeout_seconds": timeout_seconds,
+                "failure_kind": "docker_unavailable",
+                "retryable": False,
+            }
+
+        cwd = repo_path or "."
+        inspect = subprocess.run(
+            [docker_binary, "image", "inspect", self._image],
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            check=False,
+        )
+        failure_kind: str | None = None
+        if inspect.returncode != 0:
+            failure_kind = "image_missing"
+            stderr = inspect.stderr or f"docker image '{self._image}' not available"
+            lowered = stderr.lower()
+            if "permission denied" in lowered or "cannot connect" in lowered or "daemon" in lowered:
+                failure_kind = "docker_daemon_unavailable"
+            return {
+                "passed": False,
+                "returncode": inspect.returncode,
+                "stdout": inspect.stdout,
+                "stderr": stderr,
+                "runner": "docker",
+                "timeout_seconds": timeout_seconds,
+                "failure_kind": failure_kind,
+                "retryable": False,
+            }
+
+        try:
+            with tempfile.TemporaryDirectory() as temp_dir:
+                script_path = Path(temp_dir) / "snippet.py"
+                script_path.write_text(code, encoding="utf-8")
+                completed = subprocess.run(
+                    [
+                        docker_binary,
+                        "run",
+                        "--rm",
+                        "--network",
+                        "none",
+                        "--read-only",
+                        "-v",
+                        f"{temp_dir}:/workspace:ro",
+                        "-w",
+                        "/workspace",
+                        self._image,
+                        "python",
+                        "snippet.py",
+                    ],
+                    capture_output=True,
+                    text=True,
+                    cwd=cwd,
+                    timeout=timeout_seconds,
+                    check=False,
+                )
+        except subprocess.TimeoutExpired as exc:
+            return {
+                "passed": False,
+                "returncode": 124,
+                "stdout": exc.stdout or "",
+                "stderr": exc.stderr or "docker verification timed out",
+                "runner": "docker",
+                "timeout_seconds": timeout_seconds,
+                "failure_kind": "timeout",
+                "retryable": False,
+            }
+
+        failure_kind = None
+        retryable = False
+        if completed.returncode != 0:
+            failure_kind = "container_error"
+            retryable = False
+        return {
+            "passed": completed.returncode == 0,
+            "returncode": completed.returncode,
+            "stdout": completed.stdout,
+            "stderr": completed.stderr,
+            "runner": "docker",
+            "timeout_seconds": timeout_seconds,
+            "repo_path": repo_path,
+            "failure_kind": failure_kind,
+            "retryable": retryable,
+        }
+
+
+class VerificationNode:
+    def __init__(
+        self,
+        sandbox: str = "docker",
+        timeout_seconds: int = 30,
+        docker_runner: VerificationRunner | None = None,
+        subprocess_runner: VerificationRunner | None = None,
+        image: str = "minder-sandbox:latest",
+    ) -> None:
+        self._sandbox = sandbox
+        self._timeout_seconds = timeout_seconds
+        self._docker_runner = docker_runner or DockerSandboxRunner(image=image)
+        self._subprocess_runner = subprocess_runner or SubprocessVerificationRunner()
+
+    def run(self, state: GraphState) -> GraphState:
+        payload = state.metadata.get("verification_payload")
+        if payload is None:
+            state.verification_result = {
+                "passed": True,
+                "returncode": 0,
+                "stdout": "",
+                "stderr": "",
+                "runner": self._sandbox,
+                "skipped": True,
+                "timeout_seconds": self._timeout_seconds,
+                "failure_kind": None,
+                "retryable": False,
+            }
+            return state
+
+        if payload.get("language") != "python":
+            state.verification_result = {
+                "passed": False,
+                "returncode": 1,
+                "stdout": "",
+                "runner": self._sandbox,
+                "stderr": "Unsupported verification language",
+                "timeout_seconds": self._timeout_seconds,
+                "failure_kind": "unsupported_language",
+                "retryable": False,
+            }
+            return state
+
+        code = str(payload.get("code", ""))
+        if self._sandbox == "subprocess":
+            result = self._subprocess_runner.run_python(
+                code, self._timeout_seconds, state.repo_path
+            )
+        else:
+            result = self._docker_runner.run_python(
+                code, self._timeout_seconds, state.repo_path
+            )
+        state.verification_result = self._normalize_result(result)
+        return state
+
+    @staticmethod
+    def _normalize_result(result: dict[str, object]) -> dict[str, object]:
+        normalized: dict[str, Any] = dict(result)
+        normalized.setdefault("failure_kind", None if normalized.get("passed") else "runtime_error")
+        normalized.setdefault("retryable", False)
+        normalized.setdefault("stdout", "")
+        normalized.setdefault("stderr", "")
+        normalized.setdefault("returncode", 0 if normalized.get("passed") else 1)
+        return normalized