minder-cli 0.2.0__py3-none-any.whl

minder/prompts/formatter.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+from minder.config import MinderConfig
+
+
+@dataclass(slots=True)
+class PromptDraft:
+    name: str
+    title: str
+    description: str
+    content_template: str
+    arguments: list[str]
+
+
+def _normalize_arguments(arguments: list[str]) -> list[str]:
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for argument in arguments:
+        value = str(argument).strip()
+        if not value or value in seen:
+            continue
+        seen.add(value)
+        normalized.append(value)
+    return normalized
+
+
+def _humanize_name(name: str) -> str:
+    parts = [part for part in re.split(r"[_\-\s]+", name.strip()) if part]
+    return " ".join(part.capitalize() for part in parts) or "Prompt"
+
+
+def _heuristic_polish(draft: PromptDraft) -> PromptDraft:
+    normalized_args = _normalize_arguments(draft.arguments)
+    title = draft.title.strip() or _humanize_name(draft.name)
+    description = draft.description.strip() or (
+        f"Guide the model to act as {title.lower()} with grounded, actionable output."
+    )
+    base_task = draft.content_template.strip()
+    arg_section = "\n".join(f"- {{{argument}}}" for argument in normalized_args)
+    if not arg_section:
+        arg_section = "- No named placeholders required."
+
+    polished_template = "\n\n".join(
+        section
+        for section in [
+            f"## Role\nYou are {title}. {description}",
+            f"## Inputs\n{arg_section}",
+            (
+                "## Task\n" + base_task
+                if base_task
+                else "## Task\nRespond with a concrete, well-structured answer tailored to the provided inputs."
+            ),
+            "## Output Requirements\n- Be specific and practical.\n- Preserve important technical constraints.\n- Avoid filler and generic advice.",
+        ]
+        if section.strip()
+    )
+
+    return PromptDraft(
+        name=draft.name.strip(),
+        title=title,
+        description=description,
+        content_template=polished_template,
+        arguments=normalized_args,
+    )
+
+
+def _extract_json_object(raw: str) -> dict[str, object] | None:
+    if not raw.strip():
+        return None
+    candidates = re.findall(r"\{.*\}", raw, flags=re.DOTALL)
+    for candidate in candidates:
+        try:
+            value = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict):
+            return value
+    return None
+
+
+def polish_prompt_draft(
+    draft: PromptDraft, config: MinderConfig
+) -> tuple[PromptDraft, dict[str, str]]:
+    from minder.llm.local import LocalModelLLM
+
+    polished = _heuristic_polish(draft)
+    llm = LocalModelLLM(
+        config.llm.model_path,
+        runtime="auto",
+        context_length=config.llm.context_length,
+    )
+    runtime = llm.runtime
+
+    instruction = """You are polishing an MCP prompt template for an engineering assistant.
+Return only valid JSON with keys: title, description, content_template.
+Keep placeholders exactly as provided, for example {repo_name} or {error}.
+Do not invent new placeholders.
+Make the prompt direct, structured, and useful for a coding workflow.
+"""
+    request_payload = {
+        "name": polished.name,
+        "title": polished.title,
+        "description": polished.description,
+        "arguments": polished.arguments,
+        "content_template": polished.content_template,
+    }
+    llm_response = llm.complete_text(
+        f"{instruction}\n\nDraft:\n{json.dumps(request_payload, ensure_ascii=True, indent=2)}",
+        max_tokens=900,
+        temperature=min(max(config.llm.temperature, 0.05), 0.3),
+        fallback="",
+    )
+    parsed = _extract_json_object(llm_response)
+    if not parsed:
+        return polished, {
+            "provider": "heuristic",
+            "model": config.llm.model_name,
+            "runtime": runtime,
+        }
+
+    merged = PromptDraft(
+        name=polished.name,
+        title=str(parsed.get("title", polished.title)).strip() or polished.title,
+        description=(
+            str(parsed.get("description", polished.description)).strip()
+            or polished.description
+        ),
+        content_template=(
+            str(parsed.get("content_template", polished.content_template)).strip()
+            or polished.content_template
+        ),
+        arguments=polished.arguments,
+    )
+    return merged, {
+        "provider": "local_llm",
+        "model": "gemma-4-e2b-it",
+        "runtime": runtime,
+    }

minder/resources/__init__.py

@@ -0,0 +1,318 @@
+"""MCP resource registration for Minder."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from minder.store.interfaces import IGraphRepository, IOperationalStore
+
+
+class ResourceRegistry:
+    """Registers all Minder MCP resources onto a :class:`FastMCP` app."""
+
+    @staticmethod
+    def register(
+        app: FastMCP,
+        store: IOperationalStore,
+        graph_store: IGraphRepository | None = None,
+    ) -> None:
+        """Register core Minder resources, and graph resources when available.
+
+        Args:
+            app:   The FastMCP application to register resources with.
+            store: An initialised operational store used to fetch live data.
+        """
+
+        # ------------------------------------------------------------------
+        # minder://skills
+        # ------------------------------------------------------------------
+
+        @app.resource(
+            "minder://skills",
+            name="minder_skills",
+            title="Minder Skills",
+            description=(
+                "List all stored skills with their id, title, language, and tags."
+            ),
+            mime_type="application/json",
+        )
+        async def skills_resource() -> str:
+            skills = await store.list_skills()
+            return json.dumps(
+                [
+                    {
+                        "id": str(s.id),
+                        "title": s.title,
+                        "language": getattr(s, "language", ""),
+                        "tags": list(s.tags) if s.tags else [],
+                    }
+                    for s in skills
+                ],
+                indent=2,
+            )
+
+        # ------------------------------------------------------------------
+        # minder://repos
+        # ------------------------------------------------------------------
+
+        @app.resource(
+            "minder://repos",
+            name="minder_repos",
+            title="Minder Repositories",
+            description=(
+                "List all repositories with their name, URL, and current workflow state."
+            ),
+            mime_type="application/json",
+        )
+        async def repos_resource() -> str:
+            repos = await store.list_repositories()
+            result: list[dict[str, Any]] = []
+            for repo in repos:
+                state = await store.get_workflow_state_by_repo(repo.id)
+                workflow_info: dict[str, Any] | None = None
+                if state is not None:
+                    workflow_info = {
+                        "current_step": state.current_step,
+                        "completed_steps": list(state.completed_steps),
+                        "blocked_by": list(state.blocked_by),
+                    }
+                result.append(
+                    {
+                        "id": str(repo.id),
+                        "name": repo.repo_name,
+                        "url": getattr(repo, "repo_url", ""),
+                        "workflow_state": workflow_info,
+                    }
+                )
+            return json.dumps(result, indent=2)
+
+        # ------------------------------------------------------------------
+        # minder://stats
+        # ------------------------------------------------------------------
+
+        @app.resource(
+            "minder://stats",
+            name="minder_stats",
+            title="Minder Statistics",
+            description=(
+                "Aggregated counts: total skills, repos, workflows, and recorded errors."
+            ),
+            mime_type="application/json",
+        )
+        async def stats_resource() -> str:
+            skills = await store.list_skills()
+            repos = await store.list_repositories()
+            workflows = await store.list_workflows()
+            errors = await store.list_errors()
+            return json.dumps(
+                {
+                    "skill_count": len(skills),
+                    "repo_count": len(repos),
+                    "workflow_count": len(workflows),
+                    "error_count": len(errors),
+                },
+                indent=2,
+            )
+
+        if graph_store is None:
+            return
+
+        @app.resource(
+            "minder://repos/{repo_name}/structure",
+            name="minder_repo_structure",
+            title="Minder Repository Structure",
+            description="Graph-backed structural summary for a repository, grouped by node type.",
+            mime_type="application/json",
+        )
+        async def repo_structure_resource(repo_name: str) -> str:
+            repo_nodes = await _repo_graph_nodes(graph_store, repo_name)
+            counts = Counter(str(getattr(node, "node_type", "")) for node in repo_nodes)
+            grouped: dict[str, list[dict[str, Any]]] = {}
+            for node in sorted(
+                repo_nodes,
+                key=lambda item: (
+                    str(getattr(item, "node_type", "")),
+                    str(getattr(item, "name", "")),
+                ),
+            ):
+                item = _serialize_graph_node(node)
+                grouped.setdefault(item["node_type"], []).append(item)
+            return json.dumps(
+                {
+                    "repo_name": repo_name,
+                    "counts": dict(counts),
+                    "nodes": grouped,
+                },
+                indent=2,
+            )
+
+        @app.resource(
+            "minder://repos/{repo_name}/todos",
+            name="minder_repo_todos",
+            title="Minder Repository TODOs",
+            description="Graph-backed TODO items extracted for a repository.",
+            mime_type="application/json",
+        )
+        async def repo_todos_resource(repo_name: str) -> str:
+            repo_nodes = await _repo_graph_nodes(graph_store, repo_name)
+            todos = [
+                _serialize_graph_node(node)
+                for node in repo_nodes
+                if str(getattr(node, "node_type", "")) == "todo"
+            ]
+            todos.sort(
+                key=lambda item: (
+                    str(item["metadata"].get("path", "")),
+                    int(item["metadata"].get("line", 0) or 0),
+                    item["name"],
+                )
+            )
+            return json.dumps(
+                {
+                    "repo_name": repo_name,
+                    "count": len(todos),
+                    "items": todos,
+                },
+                indent=2,
+            )
+
+        @app.resource(
+            "minder://repos/{repo_name}/routes",
+            name="minder_repo_routes",
+            title="Minder Repository Routes",
+            description="Graph-backed route inventory for a repository.",
+            mime_type="application/json",
+        )
+        async def repo_routes_resource(repo_name: str) -> str:
+            repo_nodes = await _repo_graph_nodes(graph_store, repo_name)
+            routes = [
+                _serialize_graph_node(node)
+                for node in repo_nodes
+                if str(getattr(node, "node_type", "")) == "route"
+            ]
+            routes.sort(
+                key=lambda item: (
+                    str(item["metadata"].get("method", "")),
+                    str(item["metadata"].get("route_path", "")),
+                    item["name"],
+                )
+            )
+            return json.dumps(
+                {
+                    "repo_name": repo_name,
+                    "count": len(routes),
+                    "items": routes,
+                },
+                indent=2,
+            )
+
+        @app.resource(
+            "minder://repos/{repo_name}/dependencies",
+            name="minder_repo_dependencies",
+            title="Minder Repository Dependencies",
+            description="Graph-backed internal and external dependency summary for a repository.",
+            mime_type="application/json",
+        )
+        async def repo_dependencies_resource(repo_name: str) -> str:
+            repo_nodes = await _repo_graph_nodes(graph_store, repo_name)
+            repo_node_ids = {str(getattr(node, "id")) for node in repo_nodes}
+            services = [node for node in repo_nodes if str(getattr(node, "node_type", "")) == "service"]
+            internal_dependencies: list[dict[str, Any]] = []
+            for service in services:
+                neighbors = await graph_store.get_neighbors(getattr(service, "id"), direction="out", relation="depends_on")
+                targets = [
+                    {
+                        "id": str(getattr(neighbor, "id")),
+                        "name": str(getattr(neighbor, "name", "")),
+                        "node_type": str(getattr(neighbor, "node_type", "")),
+                    }
+                    for neighbor in neighbors
+                    if str(getattr(neighbor, "id")) in repo_node_ids
+                ]
+                if targets:
+                    internal_dependencies.append(
+                        {
+                            "service": str(getattr(service, "name", "")),
+                            "depends_on": sorted(targets, key=lambda item: item["name"]),
+                        }
+                    )
+
+            external_apis = [
+                _serialize_graph_node(node)
+                for node in repo_nodes
+                if str(getattr(node, "node_type", "")) == "external_service_api"
+            ]
+            external_apis.sort(key=lambda item: item["name"])
+            return json.dumps(
+                {
+                    "repo_name": repo_name,
+                    "internal_dependencies": internal_dependencies,
+                    "external_services": external_apis,
+                },
+                indent=2,
+            )
+
+        @app.resource(
+            "minder://repos/{repo_name}/symbols",
+            name="minder_repo_symbols",
+            title="Minder Repository Symbols",
+            description="Graph-backed symbol inventory for functions, classes, controllers, and interfaces within a repository.",
+            mime_type="application/json",
+        )
+        async def repo_symbols_resource(repo_name: str) -> str:
+            repo_nodes = await _repo_graph_nodes(graph_store, repo_name)
+            symbol_types = {"function", "class", "controller", "interface", "abstract_class", "module"}
+            symbols = [
+                _serialize_graph_node(node)
+                for node in repo_nodes
+                if str(getattr(node, "node_type", "")) in symbol_types
+            ]
+            symbols.sort(
+                key=lambda item: (
+                    item["node_type"],
+                    str(item["metadata"].get("path", "")),
+                    item["name"],
+                )
+            )
+            return json.dumps(
+                {
+                    "repo_name": repo_name,
+                    "count": len(symbols),
+                    "items": symbols,
+                },
+                indent=2,
+            )
+
+
+def _serialize_graph_node(node: Any) -> dict[str, Any]:
+    metadata = getattr(node, "node_metadata", {}) or {}
+    return {
+        "id": str(getattr(node, "id")),
+        "node_type": str(getattr(node, "node_type", "")),
+        "name": str(getattr(node, "name", "")),
+        "metadata": metadata if isinstance(metadata, dict) else {},
+    }
+
+
+async def _repo_graph_nodes(graph_store: IGraphRepository, repo_name: str) -> list[Any]:
+    nodes = await graph_store.list_nodes()
+    selected: list[Any] = []
+    for node in nodes:
+        metadata = getattr(node, "node_metadata", {}) or {}
+        project = str(metadata.get("project", "") or "")
+        path_value = str(metadata.get("path", "") or "")
+        if project == repo_name:
+            selected.append(node)
+            continue
+        if path_value:
+            try:
+                if Path(path_value).name == repo_name:
+                    selected.append(node)
+            except (TypeError, ValueError):
+                continue
+    return selected

minder/retrieval/__init__.py

@@ -0,0 +1,5 @@
+from minder.retrieval.hybrid import HybridRetriever
+from minder.retrieval.mmr import mmr_rerank
+from minder.retrieval.multi_hop import MultiHopRetriever, RetrieveFn
+
+__all__ = ["HybridRetriever", "MultiHopRetriever", "RetrieveFn", "mmr_rerank"]

minder/retrieval/hybrid.py

@@ -0,0 +1,178 @@
+"""
+BM25 + Vector hybrid retrieval.
+
+Combines normalised BM25 keyword scores with normalised vector similarity
+scores using a configurable alpha blend:
+
+    combined = alpha * vector_score + (1 - alpha) * bm25_score
+
+alpha = 1.0  →  pure vector search
+alpha = 0.0  →  pure BM25
+alpha = 0.5  →  equal blend (default)
+
+BM25 is implemented in pure Python (no external index server required).
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# BM25 helpers
+# ---------------------------------------------------------------------------
+
+_BM25_K1 = 1.5
+_BM25_B = 0.75
+
+
+def _tokenize(text: str) -> list[str]:
+    return [tok for tok in text.lower().split() if len(tok) > 1]
+
+
+def _bm25_score(
+    query_terms: list[str],
+    doc_tokens: list[str],
+    doc_freq: dict[str, int],
+    num_docs: int,
+    avg_dl: float,
+) -> float:
+    dl = len(doc_tokens)
+    tf_map: Counter[str] = Counter(doc_tokens)
+    score = 0.0
+    for term in query_terms:
+        tf = tf_map.get(term, 0)
+        if tf == 0:
+            continue
+        df = doc_freq.get(term, 0)
+        idf = math.log((num_docs - df + 0.5) / (df + 0.5) + 1.0)
+        tf_norm = (tf * (_BM25_K1 + 1.0)) / (
+            tf + _BM25_K1 * (1.0 - _BM25_B + _BM25_B * dl / max(avg_dl, 1.0))
+        )
+        score += idf * tf_norm
+    return score
+
+
+def _min_max_normalize(scores: list[float]) -> list[float]:
+    if not scores:
+        return scores
+    lo, hi = min(scores), max(scores)
+    if math.isclose(hi, lo):
+        return [1.0] * len(scores)
+    span = hi - lo
+    return [(s - lo) / span for s in scores]
+
+
+# ---------------------------------------------------------------------------
+# HybridRetriever
+# ---------------------------------------------------------------------------
+
+
+class HybridRetriever:
+    """
+    Merge vector-search results with BM25 scores computed over a corpus.
+
+    Args:
+        alpha: blend coefficient in [0, 1].
+            1.0 = pure vector, 0.0 = pure BM25.
+    """
+
+    def __init__(self, alpha: float = 0.5) -> None:
+        if not 0.0 <= alpha <= 1.0:
+            raise ValueError(f"alpha must be in [0.0, 1.0], got {alpha}")
+        self._alpha = alpha
+
+    @property
+    def alpha(self) -> float:
+        return self._alpha
+
+    def merge(
+        self,
+        query: str,
+        vector_results: list[dict[str, Any]],
+        corpus: list[dict[str, Any]],
+        *,
+        limit: int = 5,
+        content_key: str = "content",
+        id_key: str = "path",
+    ) -> list[dict[str, Any]]:
+        """
+        Merge *vector_results* with BM25 scores computed over *corpus*.
+
+        Args:
+            query: original user query (used for BM25 term matching).
+            vector_results: documents returned by vector search, each with a
+                ``"score"`` field (float, already normalised or raw cosine).
+            corpus: the full candidate set to build the BM25 index over.
+                Should include all docs in *vector_results* plus any extra
+                candidates.  May equal *vector_results* when no corpus is
+                separately available.
+            limit: maximum number of merged results to return.
+            content_key: key in each doc dict that holds the text content.
+            id_key: key used to de-duplicate documents across the two lists.
+
+        Returns:
+            Merged, sorted list of doc dicts enriched with ``"score"``,
+            ``"vector_score"``, and ``"bm25_score"`` fields.
+        """
+        all_docs = corpus if corpus else vector_results
+        if not all_docs:
+            return []
+
+        # ---- BM25 index ----
+        tokenized = [_tokenize(str(doc.get(content_key, ""))) for doc in all_docs]
+        avg_dl = sum(len(t) for t in tokenized) / max(len(tokenized), 1)
+        doc_freq: Counter[str] = Counter()
+        for tokens in tokenized:
+            for term in set(tokens):
+                doc_freq[term] += 1
+
+        query_terms = _tokenize(query)
+        raw_bm25 = [
+            _bm25_score(query_terms, tokens, doc_freq, len(all_docs), avg_dl)
+            for tokens in tokenized
+        ]
+        bm25_norm = _min_max_normalize(raw_bm25)
+        bm25_map: dict[str, float] = {
+            str(doc.get(id_key, i)): bm25_norm[i]
+            for i, doc in enumerate(all_docs)
+        }
+
+        # ---- Vector score map ----
+        raw_vec = [float(doc.get("score", 0.0)) for doc in vector_results]
+        vec_norm = _min_max_normalize(raw_vec)
+        vec_map: dict[str, float] = {
+            str(doc.get(id_key, i)): vec_norm[i]
+            for i, doc in enumerate(vector_results)
+        }
+
+        # ---- Union merge ----
+        vec_ids = {str(doc.get(id_key, "")) for doc in vector_results}
+        candidates = list(vector_results) + [
+            doc for doc in all_docs
+            if str(doc.get(id_key, "")) not in vec_ids
+        ]
+
+        seen: set[str] = set()
+        merged: list[dict[str, Any]] = []
+        for doc in candidates:
+            key = str(doc.get(id_key, id(doc)))
+            if key in seen:
+                continue
+            seen.add(key)
+            v = vec_map.get(key, 0.0)
+            b = bm25_map.get(key, 0.0)
+            combined = round(self._alpha * v + (1.0 - self._alpha) * b, 6)
+            merged.append(
+                {
+                    **doc,
+                    "score": combined,
+                    "vector_score": round(v, 6),
+                    "bm25_score": round(b, 6),
+                }
+            )
+
+        merged.sort(key=lambda d: float(d["score"]), reverse=True)
+        return merged[:limit]