minder-cli 0.2.0__py3-none-any.whl

minder/graph/nodes/workflow_planner.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+from collections.abc import Awaitable
+
+from minder.continuity import build_continuity_brief, build_instruction_envelope
+from minder.graph.state import GraphState
+from minder.store.interfaces import IGraphRepository, IOperationalStore
+
+logger = logging.getLogger(__name__)
+
+
+def _explicit_attribute(value: Any, name: str) -> Any | None:
+    if value is None:
+        return None
+    if hasattr(value, "__dict__") and name in value.__dict__:
+        return value.__dict__[name]
+    return getattr(value, name, None)
+
+
+class WorkflowPlannerNode:
+    """Plan the workflow step and optionally enrich guidance with graph context.
+
+    Args:
+        store:       Operational store for workflow / session data.
+        graph_store: Optional knowledge-graph store.  When provided the node
+                     queries the graph for cross-service dependencies and
+                     failing-test artefacts belonging to the current repo and
+                     appends that context to the ``guidance`` string.
+                     Omitting it (or passing ``None``) restores the original
+                     behaviour and is fully backwards-compatible.
+    """
+
+    def __init__(
+        self,
+        store: IOperationalStore,
+        *,
+        graph_store: IGraphRepository | None = None,
+    ) -> None:
+        self._store = store
+        self._graph_store = graph_store
+
+    async def _load_session(self, session_id: Any) -> Any:
+        result = self._store.get_session_by_id(session_id)
+        if isinstance(result, Awaitable):
+            return await result
+        return result
+
+    async def run(self, state: GraphState) -> GraphState:
+        workflow = None
+        if state.workflow_context.get("workflow_name"):
+            workflow = await self._store.get_workflow_by_name(
+                state.workflow_context["workflow_name"]
+            )
+
+        if workflow is None:
+            workflows = await self._store.list_workflows()
+            workflow = next((item for item in workflows if item.default_for_repo), None)
+            if workflow is None and workflows:
+                workflow = workflows[0]
+
+        workflow_steps: list[dict[str, Any]] = []
+        if workflow is not None:
+            raw_steps: list[Any] = (
+                workflow.steps if isinstance(workflow.steps, list) else []
+            )
+            workflow_steps = [step for step in raw_steps if isinstance(step, dict)]
+
+        workflow_state = None
+        if state.repo_id is not None:
+            workflow_state = await self._store.get_workflow_state_by_repo(state.repo_id)
+
+        if not workflow_steps:
+            workflow_steps = [{"name": "Test Writing"}, {"name": "Implementation"}]
+
+        current_step = workflow_steps[0]["name"]
+        completed_steps: list[str] = []
+        blocked_by: list[str] = []
+        artifacts: dict[str, Any] = {}
+        if workflow_state is not None:
+            current_step = workflow_state.current_step
+            completed_steps = list(workflow_state.completed_steps)
+            blocked_by = list(workflow_state.blocked_by)
+            artifacts = dict(workflow_state.artifacts)
+
+        next_step = self._next_step(current_step, workflow_steps)
+        guidance = self._guidance_for_step(current_step)
+        instruction_envelope: dict[str, Any] | None = None
+        continuity_brief: dict[str, Any] | None = None
+        session = None
+        workflow_state_session_id = _explicit_attribute(workflow_state, "session_id")
+        if state.session_id is not None:
+            session = await self._load_session(state.session_id)
+        elif workflow_state_session_id is not None:
+            session = await self._load_session(workflow_state_session_id)
+
+        if workflow is not None and workflow_state is not None:
+            instruction_envelope = build_instruction_envelope(
+                workflow=workflow,
+                workflow_state=workflow_state,
+            )
+            if session is not None:
+                continuity_brief = build_continuity_brief(
+                    session=session,
+                    workflow_state=workflow_state,
+                    workflow=workflow,
+                )
+            guidance = self._format_guidance(
+                guidance,
+                instruction_envelope=instruction_envelope,
+                continuity_brief=continuity_brief,
+            )
+
+        # ------------------------------------------------------------------
+        # Graph-enriched guidance (P3-T12)
+        # ------------------------------------------------------------------
+        if self._graph_store is not None and state.repo_path:
+            graph_guidance = await self._build_graph_guidance(
+                state.repo_path, artifacts
+            )
+            if graph_guidance:
+                guidance = guidance + "\n\n" + graph_guidance
+
+        cross_repo_context = str(
+            state.workflow_context.get("cross_repo_context", "") or ""
+        ).strip()
+        if cross_repo_context:
+            guidance = guidance + "\n\n" + cross_repo_context
+
+        state.workflow_context.update(
+            {
+                "workflow_name": workflow.name if workflow is not None else "default",
+                "workflow_steps": workflow_steps,
+                "current_step": current_step,
+                "next_step": next_step,
+                "completed_steps": completed_steps,
+                "blocked_by": blocked_by,
+                "artifacts": artifacts,
+                "guidance": guidance,
+                "instruction_envelope": instruction_envelope or {},
+                "continuity_brief": continuity_brief or {},
+            }
+        )
+        return state
+
+    # ------------------------------------------------------------------
+    # Graph guidance helper
+    # ------------------------------------------------------------------
+
+    async def _build_graph_guidance(
+        self, repo_path: str, artifacts: dict[str, Any]
+    ) -> str:
+        """Query the graph store for dependency context for *repo_path*.
+
+        Returns a non-empty string with additional guidance lines, or an
+        empty string when no relevant graph data is found.  All exceptions
+        from the graph store are caught and logged so that a graph query
+        failure never breaks the workflow pipeline.
+        """
+        repo_name = Path(repo_path).name
+        lines: list[str] = []
+
+        try:
+            service_nodes = await self._graph_store.query_by_type("service")  # type: ignore[union-attr]
+        except Exception as exc:  # pragma: no cover
+            logger.debug("graph_store.query_by_type failed: %s", exc)
+            return ""
+
+        # Find the service node that best matches this repo path.
+        matching = [
+            n
+            for n in service_nodes
+            if n.name == repo_name
+            or (
+                hasattr(n, "node_metadata")
+                and n.node_metadata.get("path", "").startswith(repo_path)
+            )
+        ]
+
+        if not matching:
+            return ""
+
+        service = matching[0]
+
+        # Cross-service dependencies via ``depends_on`` edges.
+        try:
+            dep_neighbors = await self._graph_store.get_neighbors(  # type: ignore[union-attr]
+                service.id,
+                direction="out",
+                relation="depends_on",
+            )
+        except Exception as exc:  # pragma: no cover
+            logger.debug("graph_store.get_neighbors failed: %s", exc)
+            dep_neighbors = []
+
+        if dep_neighbors:
+            dep_names = sorted({n.name for n in dep_neighbors})
+            lines.append(
+                f"Cross-service dependencies detected: {', '.join(dep_names)}. "
+                "Ensure changes do not break these dependency contracts."
+            )
+
+        # Failing tests recorded in the last workflow artefact run.
+        failing = artifacts.get("failing_tests")
+        if failing:
+            lines.append(f"Failing tests from last run: {failing}")
+
+        return "\n".join(lines)
+
+    # ------------------------------------------------------------------
+    # Static helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _next_step(current_step: str, steps: list[dict[str, Any]]) -> str | None:
+        names = [step["name"] for step in steps]
+        if current_step not in names:
+            return names[0] if names else None
+        current_index = names.index(current_step)
+        if current_index + 1 >= len(names):
+            return None
+        return names[current_index + 1]
+
+    @staticmethod
+    def _guidance_for_step(current_step: str) -> str:
+        lowered = current_step.lower()
+        if "test" in lowered:
+            return "Current step: Test Writing. Write tests before implementation."
+        if "implement" in lowered:
+            return "Current step: Implementation. Use existing failing tests as the contract."
+        if "review" in lowered:
+            return (
+                "Current step: Review. Focus on correctness, regressions, and coverage."
+            )
+        return f"Current step: {current_step}. Follow the workflow and do not skip prerequisites."
+
+    @staticmethod
+    def _format_guidance(
+        base_guidance: str,
+        *,
+        instruction_envelope: dict[str, Any],
+        continuity_brief: dict[str, Any] | None,
+    ) -> str:
+        sections = [base_guidance]
+        sections.append(f"Instruction envelope: {instruction_envelope}")
+        if continuity_brief:
+            sections.append(f"Continuity brief: {continuity_brief}")
+        return "\n\n".join(sections)

minder/graph/runtime.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Any
+
+from minder.runtime import load_attr, module_available
+
+
+def graph_runtime_name(preferred: str = "langgraph") -> str:
+    if preferred == "langgraph" and module_available("langgraph"):
+        return "langgraph"
+    return "internal"
+
+
+def load_langgraph_state_graph() -> Any | None:
+    return load_attr("langgraph.graph", "StateGraph")

minder/graph/state.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import uuid
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GraphState(BaseModel):
+    query: str
+    session_id: uuid.UUID | None = None
+    user_id: uuid.UUID | None = None
+    repo_id: uuid.UUID | None = None
+    repo_path: str | None = None
+    plan: dict[str, Any] = Field(default_factory=dict)
+    retrieved_docs: list[dict[str, Any]] = Field(default_factory=list)
+    reranked_docs: list[dict[str, Any]] = Field(default_factory=list)
+    workflow_context: dict[str, Any] = Field(default_factory=dict)
+    reasoning_output: dict[str, Any] = Field(default_factory=dict)
+    llm_output: dict[str, Any] = Field(default_factory=dict)
+    guard_result: dict[str, Any] = Field(default_factory=dict)
+    verification_result: dict[str, Any] = Field(default_factory=dict)
+    evaluation: dict[str, Any] = Field(default_factory=dict)
+    transition_log: list[dict[str, Any]] = Field(default_factory=list)
+    retry_count: int = 0
+    metadata: dict[str, Any] = Field(default_factory=dict)

minder/llm/__init__.py

@@ -0,0 +1,5 @@
+from .base import LLMClient
+from .local import LocalModelLLM
+from .openai import OpenAIFallbackLLM
+
+__all__ = ["LLMClient", "LocalModelLLM", "OpenAIFallbackLLM"]

minder/llm/base.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from typing import Protocol
+
+from minder.graph.state import GraphState
+
+
+class LLMClient(Protocol):
+    def generate(self, state: GraphState) -> dict[str, object]: ...
+
+    def stream_generate(
+        self, state: GraphState
+    ) -> Generator[dict[str, object], None, None]: ...

minder/llm/local.py

@@ -0,0 +1,381 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+from minder.graph.state import GraphState
+from minder.runtime import load_attr, module_available
+
+_RUNTIME_LOG_MARKERS = (
+    "Using chat eos_token:",
+    "Using chat bos_token:",
+    "llama_perf_context_print:",
+    "~llama_context:",
+    "ggml_metal_free:",
+)
+
+_CHAT_TEMPLATE_MARKERS = (
+    "{{- '<turn|>\\n' -}}",
+    "{%- if add_generation_prompt -%}",
+    "{%- endif -%}",
+    "{%- endfor -%}",
+)
+
+
+class LocalModelLLM:
+
+    def __init__(
+        self,
+        model_path: str,
+        fail: bool = False,
+        runtime: str = "mock",
+        context_length: int = 131072,
+    ) -> None:
+        self._model_path = model_path
+        self._fail = fail
+        self._runtime = runtime
+        self._context_length = max(512, context_length)
+        self._client: Any | None = None
+
+    @property
+    def runtime(self) -> str:
+        runtime = self._runtime
+        model_exists = Path(self._model_path).expanduser().exists()
+        if runtime == "auto":
+            return (
+                "llama_cpp"
+                if model_exists and module_available("llama_cpp")
+                else "mock"
+            )
+        return runtime
+
+    def generate(self, state: GraphState) -> dict[str, object]:
+        if self._fail:
+            raise RuntimeError("Local model unavailable")
+
+        runtime = self.runtime
+
+        source_paths = [doc["path"] for doc in state.reranked_docs[:3]]
+        guidance = state.workflow_context.get("guidance", "")
+        text = (
+            f"{guidance}\n"
+            f"Plan intent: {state.plan.get('intent', 'unknown')}.\n"
+            f"Answer: grounded response for '{state.query}'.\n"
+            f"Sources: {', '.join(source_paths) if source_paths else 'none'}."
+        )
+        if runtime == "llama_cpp":
+            text = self._generate_with_llama_cpp(state, fallback=text)
+
+        return {
+            "text": text,
+            "sources": source_paths,
+            "provider": "local_llm",
+            "model": "gemma-4-e2b-it",
+            "model_path": self._model_path,
+            "runtime": runtime,
+            "stream": [line for line in text.splitlines() if line],
+        }
+
+    def stream_generate(
+        self, state: GraphState
+    ) -> Generator[dict[str, object], None, None]:
+        if self._fail:
+            raise RuntimeError("Local model unavailable")
+
+        runtime = self.runtime
+        source_paths = [doc["path"] for doc in state.reranked_docs[:3]]
+        guidance = state.workflow_context.get("guidance", "")
+        fallback = (
+            f"{guidance}\n"
+            f"Plan intent: {state.plan.get('intent', 'unknown')}.\n"
+            f"Answer: grounded response for '{state.query}'.\n"
+            f"Sources: {', '.join(source_paths) if source_paths else 'none'}."
+        )
+
+        if runtime != "llama_cpp":
+            if fallback:
+                yield {"type": "chunk", "delta": fallback}
+            yield {
+                "type": "result",
+                "result": {
+                    "text": fallback,
+                    "sources": source_paths,
+                    "provider": "local_llm",
+                    "model": "gemma-4-e2b-it",
+                    "model_path": self._model_path,
+                    "runtime": runtime,
+                    "stream": [fallback] if fallback else [],
+                },
+            }
+            return
+
+        client = self._llama_client()
+        if client is None:
+            if fallback:
+                yield {"type": "chunk", "delta": fallback}
+            yield {
+                "type": "result",
+                "result": {
+                    "text": fallback,
+                    "sources": source_paths,
+                    "provider": "local_llm",
+                    "model": "gemma-4-e2b-it",
+                    "model_path": self._model_path,
+                    "runtime": runtime,
+                    "stream": [fallback] if fallback else [],
+                },
+            }
+            return
+
+        reasoning_output = getattr(state, "reasoning_output", {}) or {}
+        prompt = str(reasoning_output.get("prompt") or state.query)
+        deltas: list[str] = []
+        try:
+            for delta in self._stream_with_llama_cpp(
+                client,
+                prompt=prompt,
+                max_tokens=256,
+                temperature=0.1,
+            ):
+                cleaned_delta = self._clean_stream_delta(delta)
+                if not cleaned_delta:
+                    continue
+                deltas.append(cleaned_delta)
+                yield {"type": "chunk", "delta": cleaned_delta}
+        except Exception:
+            if fallback:
+                yield {"type": "chunk", "delta": fallback}
+            deltas = [fallback] if fallback else []
+
+        text = self._clean_generated_text("".join(deltas)) or fallback
+        yield {
+            "type": "result",
+            "result": {
+                "text": text,
+                "sources": source_paths,
+                "provider": "local_llm",
+                "model": "gemma-4-e2b-it",
+                "model_path": self._model_path,
+                "runtime": runtime,
+                "stream": deltas if deltas else ([text] if text else []),
+            },
+        }
+
+    def complete_text(
+        self,
+        prompt: str,
+        *,
+        max_tokens: int = 512,
+        temperature: float = 0.1,
+        fallback: str = "",
+    ) -> str:
+        if self._fail:
+            raise RuntimeError("Local model unavailable")
+
+        if self.runtime != "llama_cpp":
+            return fallback
+
+        client = self._llama_client()
+        if client is None:
+            return fallback
+
+        try:
+            response = self._complete_with_llama_cpp(
+                client,
+                prompt=prompt,
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+        except Exception:
+            return fallback
+
+        text = self._response_text(response, fallback=fallback)
+        cleaned = self._clean_generated_text(text)
+        return cleaned or fallback
+
+    def _generate_with_llama_cpp(self, state: GraphState, *, fallback: str) -> str:
+        reasoning_output = getattr(state, "reasoning_output", {}) or {}
+        prompt = reasoning_output.get("prompt") or state.query
+        return self.complete_text(
+            str(prompt),
+            max_tokens=256,
+            temperature=0.1,
+            fallback=fallback,
+        )
+
+    def _complete_with_llama_cpp(
+        self,
+        client: Any,
+        *,
+        prompt: str,
+        max_tokens: int,
+        temperature: float,
+    ) -> Any:
+        chat_completion = getattr(client, "create_chat_completion", None)
+        if callable(chat_completion):
+            return chat_completion(
+                messages=[
+                    {
+                        "role": "user",
+                        "content": prompt,
+                    }
+                ],
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+        return client.create_completion(
+            prompt=prompt,
+            max_tokens=max_tokens,
+            temperature=temperature,
+        )
+
+    def _stream_with_llama_cpp(
+        self,
+        client: Any,
+        *,
+        prompt: str,
+        max_tokens: int,
+        temperature: float,
+    ) -> Generator[str, None, None]:
+        chat_completion = getattr(client, "create_chat_completion", None)
+        if callable(chat_completion):
+            response = chat_completion(
+                messages=[{"role": "user", "content": prompt}],
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=True,
+            )
+            yield from self._extract_stream_deltas(response)
+            return
+
+        response = client.create_completion(
+            prompt=prompt,
+            max_tokens=max_tokens,
+            temperature=temperature,
+            stream=True,
+        )
+        yield from self._extract_stream_deltas(response)
+
+    def _extract_stream_deltas(self, response: Any) -> Generator[str, None, None]:
+        for chunk in response:
+            delta = self._response_delta(chunk)
+            if delta:
+                yield delta
+
+    def _response_delta(self, chunk: Any) -> str:
+        if isinstance(chunk, dict):
+            choices = chunk.get("choices", [])
+        else:
+            choices = getattr(chunk, "choices", [])
+        if not choices:
+            return ""
+
+        first = choices[0]
+        if isinstance(first, dict):
+            delta = first.get("delta")
+            if isinstance(delta, dict):
+                content = delta.get("content")
+                if isinstance(content, str):
+                    return content
+            text = first.get("text")
+            if isinstance(text, str):
+                return text
+        delta = getattr(first, "delta", None)
+        content = getattr(delta, "content", None) if delta is not None else None
+        if isinstance(content, str):
+            return content
+        text = getattr(first, "text", None)
+        if isinstance(text, str):
+            return text
+        return ""
+
+    def _response_text(self, response: Any, *, fallback: str) -> str:
+        if isinstance(response, dict):
+            choices = response.get("choices", [])
+        else:
+            choices = getattr(response, "choices", [])
+        if not choices:
+            return fallback
+
+        first = choices[0]
+        if isinstance(first, dict):
+            message = first.get("message")
+            if isinstance(message, dict):
+                content = message.get("content")
+                if isinstance(content, str):
+                    return content.strip() or fallback
+                if isinstance(content, list):
+                    parts = [
+                        str(item.get("text", "")).strip()
+                        for item in content
+                        if isinstance(item, dict) and str(item.get("text", "")).strip()
+                    ]
+                    if parts:
+                        return "\n".join(parts)
+            text = first.get("text")
+            if isinstance(text, str):
+                return text.strip() or fallback
+
+        message = getattr(first, "message", None)
+        content = getattr(message, "content", None) if message is not None else None
+        if isinstance(content, str):
+            return content.strip() or fallback
+        text = getattr(first, "text", None)
+        if isinstance(text, str):
+            return text.strip() or fallback
+        return fallback
+
+    def _clean_generated_text(self, text: str) -> str:
+        if not text:
+            return ""
+
+        kept_lines: list[str] = []
+        for line in text.splitlines():
+            stripped = line.strip()
+            if not stripped:
+                if kept_lines and kept_lines[-1] != "":
+                    kept_lines.append("")
+                continue
+            if any(marker in stripped for marker in _RUNTIME_LOG_MARKERS):
+                continue
+            if any(marker in stripped for marker in _CHAT_TEMPLATE_MARKERS):
+                continue
+            kept_lines.append(line)
+
+        return "\n".join(kept_lines).strip()
+
+    def _clean_stream_delta(self, delta: str) -> str:
+        stripped = delta.strip()
+        if not stripped:
+            return delta
+        if any(marker in stripped for marker in _RUNTIME_LOG_MARKERS):
+            return ""
+        if any(marker in stripped for marker in _CHAT_TEMPLATE_MARKERS):
+            return ""
+        return delta
+
+    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
+        base_kwargs = {
+            "model_path": str(Path(self._model_path).expanduser()),
+            "verbose": False,
+            "n_ctx": self._context_length,
+        }
+        try:
+            self._client = llama_cls(
+                **base_kwargs,
+                flash_attn=True,
+            )
+        except TypeError:
+            try:
+                self._client = llama_cls(**base_kwargs)
+            except Exception:
+                return None
+        except Exception:
+            return None
+        return self._client