minder-cli 0.2.0__py3-none-any.whl

minder/embedding/__init__.py

@@ -0,0 +1,9 @@
+from .base import EmbeddingProvider
+from .local import LocalEmbeddingProvider
+from .openai import OpenAIEmbeddingProvider
+
+__all__ = [
+    "EmbeddingProvider",
+    "LocalEmbeddingProvider",
+    "OpenAIEmbeddingProvider",
+]

minder/embedding/base.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class EmbeddingProvider(Protocol):
+    def embed(self, text: str) -> list[float]: ...

minder/embedding/local.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from minder.runtime import load_attr, module_available
+
+
+class LocalEmbeddingProvider:
+    def __init__(self, model_path: str, dimensions: int = 768, runtime: str = "mock") -> None:
+        self._model_path = model_path
+        self._dimensions = dimensions
+        self._runtime = runtime
+        self._client: Any | None = None
+
+    @property
+    def runtime(self) -> str:
+        runtime = self._runtime
+        if runtime == "auto":
+            if Path(self._model_path).expanduser().exists() and module_available("llama_cpp"):
+                return "llama_cpp"
+            return "mock"
+        return runtime
+
+    def embed(self, text: str) -> list[float]:
+        if self.runtime == "llama_cpp":
+            embedded = self._embed_with_llama_cpp(text)
+            if embedded is not None:
+                return embedded[: self._dimensions]
+        digest = hashlib.sha256(text.encode("utf-8")).digest()
+        values: list[float] = []
+        for index in range(self._dimensions):
+            byte = digest[index % len(digest)]
+            values.append(round(byte / 255.0, 6))
+        return values
+
+    def _embed_with_llama_cpp(self, text: str) -> list[float] | None:
+        client = self._llama_client()
+        if client is None:
+            return None
+        response = client.embed(text)
+        if isinstance(response, list):
+            return [float(value) for value in response]
+        data = response.get("data", []) if isinstance(response, dict) else []
+        if not data:
+            return None
+        embedding = data[0].get("embedding", [])
+        return [float(value) for value in embedding]
+
+    def _llama_client(self) -> Any | None:
+        if self._client is not None:
+            return self._client
+        llama_cls = load_attr("llama_cpp", "Llama")
+        if llama_cls is None:
+            return None
+        try:
+            self._client = llama_cls(
+                model_path=str(Path(self._model_path).expanduser()),
+                embedding=True,
+                verbose=False,
+            )
+        except Exception:
+            return None
+        return self._client

minder/embedding/openai.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from minder.embedding.local import LocalEmbeddingProvider
+
+
+class OpenAIEmbeddingProvider(LocalEmbeddingProvider):
+    pass

minder/graph/__init__.py

@@ -0,0 +1,11 @@
+from .state import GraphState
+
+__all__ = ["GraphState", "MinderGraph"]
+
+
+def __getattr__(name: str):
+    if name == "MinderGraph":
+        from .graph import MinderGraph
+
+        return MinderGraph
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

minder/graph/edges.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from minder.graph.state import GraphState
+
+
+def determine_next_edge(state: GraphState) -> str:
+    if state.metadata.get("fallback_used") is True:
+        return "fallback_complete"
+    if state.guard_result.get("passed") is False:
+        return "guard_failed"
+    if state.verification_result.get("passed") is False:
+        return "verification_failed"
+    return "complete"

minder/graph/executor.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from minder.graph.edges import determine_next_edge
+from minder.graph.nodes import (
+    EvaluatorNode,
+    GuardNode,
+    LLMNode,
+    PlanningNode,
+    ReasoningNode,
+    RerankerNode,
+    RetrieverNode,
+    VerificationNode,
+    WorkflowPlannerNode,
+)
+from minder.graph.runtime import graph_runtime_name, load_langgraph_state_graph
+from minder.graph.state import GraphState
+
+
+@dataclass
+class GraphNodes:
+    workflow_planner: WorkflowPlannerNode
+    planning: PlanningNode
+    retriever: RetrieverNode
+    reasoning: ReasoningNode
+    llm: LLMNode
+    guard: GuardNode
+    verification: VerificationNode
+    evaluator: EvaluatorNode
+    reranker: RerankerNode | None = field(default=None)
+
+
+class InternalGraphExecutor:
+    def __init__(self, nodes: GraphNodes) -> None:
+        self._nodes = nodes
+
+    async def run(self, state: GraphState) -> GraphState:
+        max_attempts = int(state.metadata.get("max_attempts", 1))
+        state.metadata.setdefault("attempt_failures", [])
+        state.metadata["orchestration_runtime"] = "internal"
+        state = await self._nodes.workflow_planner.run(state)
+        state = self._nodes.planning.run(state)
+        state = await self._nodes.retriever.run(state)
+        if self._nodes.reranker is not None:
+            state = await self._nodes.reranker.run(state)
+
+        attempt = 0
+        while True:
+            attempt += 1
+            state.retry_count = attempt - 1
+            state = self._nodes.reasoning.run(state)
+            state = self._nodes.llm.run(state)
+            state = self._nodes.guard.run(state)
+            state = self._nodes.verification.run(state)
+            edge = determine_next_edge(state)
+            state.transition_log.append(
+                {
+                    "attempt": attempt,
+                    "edge": edge,
+                    "provider": state.llm_output.get("provider"),
+                    "fallback_used": state.metadata.get("fallback_used", False),
+                }
+            )
+            if (
+                edge not in {"verification_failed", "guard_failed"}
+                or attempt >= max_attempts
+            ):
+                break
+            retry_reason = (
+                "; ".join(
+                    str(reason)
+                    for reason in state.guard_result.get("reasons", [])
+                    if reason
+                )
+                if edge == "guard_failed"
+                else state.verification_result.get("stderr", "verification failed")
+            )
+            state.metadata["attempt_failures"].append(
+                {
+                    "attempt": attempt,
+                    "reason": retry_reason,
+                    "provider": state.llm_output.get("provider"),
+                    "edge": edge,
+                }
+            )
+            state.metadata["retry_reason"] = retry_reason
+
+        state = self._nodes.evaluator.run(state)
+        state.metadata["edge"] = determine_next_edge(state)
+        return state
+
+
+class LangGraphExecutorAdapter:
+    def __init__(self, nodes: GraphNodes) -> None:
+        self._nodes = nodes
+        self._internal = InternalGraphExecutor(nodes)
+        self._compiled_graph = None
+
+    async def run(self, state: GraphState) -> GraphState:
+        if graph_runtime_name() != "langgraph":
+            state = await self._internal.run(state)
+            state.metadata["orchestration_runtime"] = "internal"
+            return state
+
+        compiled = self._compiled_graph or self._build_compiled_graph()
+        self._compiled_graph = compiled
+        result = await compiled.ainvoke(state)
+        if isinstance(result, GraphState):
+            result.metadata["orchestration_runtime"] = "langgraph"
+            return result
+        validated = GraphState.model_validate(result)
+        validated.metadata["orchestration_runtime"] = "langgraph"
+        return validated
+
+    def _build_compiled_graph(self):
+        state_graph_cls = load_langgraph_state_graph()
+        if state_graph_cls is None:
+            raise RuntimeError(
+                "LangGraph runtime requested but StateGraph is unavailable"
+            )
+
+        workflow = state_graph_cls(GraphState)
+        workflow.add_node("internal_executor", self._internal.run)
+        workflow.set_entry_point("internal_executor")
+        workflow.set_finish_point("internal_executor")
+        return workflow.compile()

minder/graph/graph.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from time import perf_counter
+
+from minder.config import MinderConfig
+from minder.embedding.local import LocalEmbeddingProvider
+from minder.graph.edges import determine_next_edge
+from minder.graph.executor import (
+    GraphNodes,
+    InternalGraphExecutor,
+    LangGraphExecutorAdapter,
+)
+from minder.graph.nodes import (
+    EvaluatorNode,
+    GuardNode,
+    LLMNode,
+    PlanningNode,
+    ReasoningNode,
+    RerankerNode,
+    RetrieverNode,
+    VerificationNode,
+    WorkflowPlannerNode,
+)
+from minder.graph.state import GraphState
+from minder.llm.local import LocalModelLLM
+from minder.llm.openai import OpenAIFallbackLLM
+from minder.store.interfaces import (
+    IOperationalStore,
+    IErrorRepository,
+    IHistoryRepository,
+)
+
+
+class MinderGraph:
+    def __init__(
+        self,
+        store: IOperationalStore,
+        config: MinderConfig,
+        *,
+        workflow_planner: WorkflowPlannerNode | None = None,
+        planning: PlanningNode | None = None,
+        retriever: RetrieverNode | None = None,
+        reranker: RerankerNode | None = None,
+        reasoning: ReasoningNode | None = None,
+        llm: LLMNode | None = None,
+        guard: GuardNode | None = None,
+        verification: VerificationNode | None = None,
+        evaluator: EvaluatorNode | None = None,
+        history_store: IHistoryRepository | None = None,
+        error_store: IErrorRepository | None = None,
+    ) -> None:
+        from minder.store.vector import VectorStore
+
+        self._store = store
+        self._config = config
+        self._workflow_planner = workflow_planner or WorkflowPlannerNode(store)
+        self._planning = planning or PlanningNode()
+        vector_store = VectorStore(store, store)
+        embedder = LocalEmbeddingProvider(
+            config.embedding.model_path,
+            dimensions=config.embedding.dimensions,
+            runtime="auto",
+        )
+        self._retriever = retriever or RetrieverNode(
+            top_k=config.retrieval.top_k,
+            embedding_provider=embedder,
+            vector_store=vector_store,
+            score_threshold=config.retrieval.similarity_threshold,
+        )
+        self._reranker = reranker  # None by default; pass RerankerNode(...) to activate
+        self._reasoning = reasoning or ReasoningNode()
+        self._llm = llm or LLMNode(
+            primary=LocalModelLLM(
+                config.llm.model_path,
+                runtime="auto",
+                context_length=config.llm.context_length,
+            ),
+            fallback=OpenAIFallbackLLM(
+                config.llm.openai_api_key,
+                config.llm.openai_model,
+                runtime="auto",
+            ),
+        )
+        self._guard = guard or GuardNode()
+        self._verification = verification or VerificationNode(
+            sandbox=config.verification.sandbox,
+            timeout_seconds=config.verification.timeout_seconds,
+        )
+        self._evaluator = evaluator or EvaluatorNode()
+        self._history_store = history_store or store
+        self._error_store = error_store or store
+        self._nodes = GraphNodes(
+            workflow_planner=self._workflow_planner,
+            planning=self._planning,
+            retriever=self._retriever,
+            reranker=self._reranker,
+            reasoning=self._reasoning,
+            llm=self._llm,
+            guard=self._guard,
+            verification=self._verification,
+            evaluator=self._evaluator,
+        )
+
+    async def run(self, state: GraphState) -> GraphState:
+        executor = self._select_executor()
+        state = await executor.run(state)
+
+        await self._persist_history(state)
+        await self._persist_error_if_needed(state)
+        await self._advance_workflow_if_needed(state)
+        return state
+
+    async def stream(
+        self, state: GraphState
+    ) -> AsyncGenerator[dict[str, object], None]:
+        max_attempts = int(state.metadata.get("max_attempts", 1))
+        state.metadata.setdefault("attempt_failures", [])
+        state.metadata["orchestration_runtime"] = "internal"
+        state = await self._nodes.workflow_planner.run(state)
+        state = self._nodes.planning.run(state)
+        state = await self._nodes.retriever.run(state)
+        if self._nodes.reranker is not None:
+            state = await self._nodes.reranker.run(state)
+
+        attempt = 0
+        while True:
+            attempt += 1
+            state.retry_count = attempt - 1
+            state = self._nodes.reasoning.run(state)
+            yield {"type": "attempt", "attempt": attempt}
+            for event in self._nodes.llm.stream(state):
+                if str(event.get("type")) == "result":
+                    continue
+                yield {**event, "attempt": attempt}
+            state = self._nodes.guard.run(state)
+            state = self._nodes.verification.run(state)
+            edge = determine_next_edge(state)
+            state.transition_log.append(
+                {
+                    "attempt": attempt,
+                    "edge": edge,
+                    "provider": state.llm_output.get("provider"),
+                    "fallback_used": state.metadata.get("fallback_used", False),
+                }
+            )
+            if (
+                edge not in {"verification_failed", "guard_failed"}
+                or attempt >= max_attempts
+            ):
+                break
+            retry_reason = (
+                "; ".join(
+                    str(reason)
+                    for reason in state.guard_result.get("reasons", [])
+                    if reason
+                )
+                if edge == "guard_failed"
+                else state.verification_result.get("stderr", "verification failed")
+            )
+            state.metadata["attempt_failures"].append(
+                {
+                    "attempt": attempt,
+                    "reason": retry_reason,
+                    "provider": state.llm_output.get("provider"),
+                    "edge": edge,
+                }
+            )
+            state.metadata["retry_reason"] = retry_reason
+            yield {
+                "type": "retry",
+                "attempt": attempt,
+                "reason": retry_reason,
+                "edge": edge,
+            }
+
+        state = self._nodes.evaluator.run(state)
+        state.metadata["edge"] = determine_next_edge(state)
+        await self._persist_history(state)
+        await self._persist_error_if_needed(state)
+        await self._advance_workflow_if_needed(state)
+        yield {"type": "final", "state": state}
+
+    def _select_executor(self) -> InternalGraphExecutor | LangGraphExecutorAdapter:
+        if self._config.workflow.orchestration_runtime == "langgraph":
+            return LangGraphExecutorAdapter(self._nodes)
+        return InternalGraphExecutor(self._nodes)
+
+    async def _persist_history(self, state: GraphState) -> None:
+        if state.session_id is None:
+            return
+        started = perf_counter()
+        await self._history_store.create_history(
+            session_id=state.session_id,
+            role="assistant",
+            content=str(state.llm_output.get("text", "")),
+            reasoning_trace=str(state.reasoning_output.get("prompt", "")),
+            tool_calls={
+                "pipeline": [
+                    "workflow_planner",
+                    "planning",
+                    "retriever",
+                    "reasoning",
+                    "llm",
+                    "guard",
+                    "verification",
+                ],
+                "transition_log": state.transition_log,
+                "provider": state.llm_output.get("provider"),
+                "fallback_used": state.metadata.get("fallback_used", False),
+            },
+            latency_ms=int((perf_counter() - started) * 1000),
+        )
+
+    async def _persist_error_if_needed(self, state: GraphState) -> None:
+        reasons = list(state.guard_result.get("reasons", []))
+        if state.verification_result.get("passed") is False:
+            reasons.append(
+                str(state.verification_result.get("stderr", "verification failed"))
+            )
+        for attempt_failure in state.metadata.get("attempt_failures", []):
+            reasons.append(str(attempt_failure.get("reason", "attempt failed")))
+        if not reasons:
+            return
+        await self._error_store.create_error(
+            error_code="PIPELINE_FAILURE",
+            error_message="; ".join(reason for reason in reasons if reason),
+            context={
+                "query": state.query,
+                "repo_path": state.repo_path,
+                "transition_log": state.transition_log,
+                "provider": state.llm_output.get("provider"),
+                "retry_count": state.retry_count,
+            },
+            resolved=False,
+        )
+
+    async def _advance_workflow_if_needed(self, state: GraphState) -> None:
+        if state.repo_id is None:
+            return
+        if state.guard_result.get("passed") is not True:
+            return
+        if state.verification_result.get("passed") is not True:
+            return
+        workflow_state = await self._store.get_workflow_state_by_repo(state.repo_id)
+        if workflow_state is None:
+            return
+        current_step = workflow_state.current_step
+        completed_steps = list(workflow_state.completed_steps)
+        if current_step not in completed_steps:
+            completed_steps.append(current_step)
+        await self._store.update_workflow_state(
+            workflow_state.id,
+            completed_steps=completed_steps,
+            current_step=state.workflow_context.get("next_step") or current_step,
+            next_step=None,
+            artifacts={
+                **dict(workflow_state.artifacts),
+                "last_transition_reason": "guard+verification passed",
+                "last_provider": state.llm_output.get("provider"),
+                "last_edge": state.metadata.get("edge"),
+            },
+        )

minder/graph/nodes/__init__.py

@@ -0,0 +1,27 @@
+from .evaluator import EvaluatorNode
+from .guard import GuardNode
+from .llm import LLMNode
+from .planning import PlanningNode
+from .reranker import RerankerNode
+from .reasoning import ReasoningNode
+from .retriever import RetrieverNode
+from .verification import (
+    DockerSandboxRunner,
+    SubprocessVerificationRunner,
+    VerificationNode,
+)
+from .workflow_planner import WorkflowPlannerNode
+
+__all__ = [
+    "DockerSandboxRunner",
+    "EvaluatorNode",
+    "GuardNode",
+    "LLMNode",
+    "PlanningNode",
+    "ReasoningNode",
+    "RerankerNode",
+    "RetrieverNode",
+    "SubprocessVerificationRunner",
+    "VerificationNode",
+    "WorkflowPlannerNode",
+]

minder/graph/nodes/evaluator.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from minder.graph.state import GraphState
+
+
+class EvaluatorNode:
+    def run(self, state: GraphState) -> GraphState:
+        score = 1.0
+        if not state.guard_result.get("passed", False):
+            score -= 0.5
+        if not state.verification_result.get("passed", False):
+            score -= 0.3
+        if not state.reranked_docs:
+            score -= 0.1
+        score = max(score, 0.0)
+        state.evaluation = {
+            "quality_score": round(score, 2),
+            "correctness_score": round(score, 2),
+            "used_sources": len(state.reranked_docs),
+        }
+        return state

minder/graph/nodes/guard.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import ast
+import re
+from re import Pattern
+
+from minder.graph.state import GraphState
+
+UNSAFE_PATTERNS = ("rm -rf", "DROP TABLE", "ignore all safety", "steal credentials")
+SECRET_PATTERNS: tuple[Pattern[str], ...] = (
+    re.compile(r"AKIA[0-9A-Z]{16}"),
+    re.compile(r"sk-[A-Za-z0-9]{20,}"),
+)
+
+
+class GuardNode:
+    def run(self, state: GraphState) -> GraphState:
+        text = str(state.llm_output.get("text", ""))
+        reasons: list[str] = []
+        passed = True
+
+        lowered = text.lower()
+        for pattern in UNSAFE_PATTERNS:
+            if pattern.lower() in lowered:
+                passed = False
+                reasons.append(f"unsafe pattern detected: {pattern}")
+
+        for secret_pattern in SECRET_PATTERNS:
+            if secret_pattern.search(text):
+                passed = False
+                reasons.append("secret or token pattern detected")
+
+        if "```python" in text:
+            code = text.split("```python", 1)[1].split("```", 1)[0]
+            try:
+                ast.parse(code)
+            except SyntaxError as exc:
+                passed = False
+                reasons.append(f"python syntax error: {exc.msg}")
+
+        source_paths = [doc["path"] for doc in state.reranked_docs]
+        claimed_sources = state.llm_output.get("sources", [])
+        for source in claimed_sources:
+            if source not in source_paths:
+                passed = False
+                reasons.append(f"hallucinated source: {source}")
+
+        instruction_envelope = dict(
+            state.workflow_context.get("instruction_envelope", {}) or {}
+        )
+        output_contract = dict(instruction_envelope.get("output_contract", {}) or {})
+        required_markers = [
+            str(marker).strip().lower().replace("_", " ")
+            for marker in list(output_contract.get("must_include", []) or [])
+            if str(marker).strip()
+        ]
+        normalized_text = lowered.replace("_", " ")
+        for marker in required_markers:
+            if marker not in normalized_text:
+                passed = False
+                reasons.append(f"workflow output contract missing: {marker}")
+
+        state.guard_result = {"passed": passed, "reasons": reasons}
+        return state

minder/graph/nodes/llm.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from minder.graph.state import GraphState
+from minder.llm.base import LLMClient
+from minder.llm.openai import OpenAIFallbackLLM
+
+
+class LLMNode:
+    def __init__(
+        self, primary: LLMClient, fallback: OpenAIFallbackLLM | None = None
+    ) -> None:
+        self._primary = primary
+        self._fallback = fallback
+
+    def run(self, state: GraphState) -> GraphState:
+        try:
+            state.llm_output = self._primary.generate(state)
+            state.metadata["fallback_used"] = False
+            state.metadata["llm_provider"] = state.llm_output.get("provider")
+        except Exception as exc:
+            state.metadata["llm_error"] = str(exc)
+            if self._fallback is None or not self._fallback.available():
+                raise
+            state.llm_output = self._fallback.generate(state)
+            state.metadata["fallback_used"] = True
+            state.metadata["llm_provider"] = state.llm_output.get("provider")
+        return state
+
+    def stream(self, state: GraphState) -> Generator[dict[str, object], None, None]:
+        try:
+            streamer = getattr(self._primary, "stream_generate", None)
+            if callable(streamer):
+                result = None
+                for event in streamer(state):
+                    if str(event.get("type")) == "result":
+                        result = dict(event.get("result", {}) or {})
+                        continue
+                    yield event
+                state.llm_output = result or self._primary.generate(state)
+            else:
+                state.llm_output = self._primary.generate(state)
+                text = str(state.llm_output.get("text", ""))
+                if text:
+                    yield {"type": "chunk", "delta": text}
+            state.metadata["fallback_used"] = False
+            state.metadata["llm_provider"] = state.llm_output.get("provider")
+        except Exception as exc:
+            state.metadata["llm_error"] = str(exc)
+            if self._fallback is None or not self._fallback.available():
+                raise
+            state.llm_output = self._fallback.generate(state)
+            text = str(state.llm_output.get("text", ""))
+            if text:
+                yield {"type": "chunk", "delta": text}
+            state.metadata["fallback_used"] = True
+            state.metadata["llm_provider"] = state.llm_output.get("provider")
+        yield {"type": "result", "result": state.llm_output}