nrgrd 0.1.0__py3-none-any.whl

nrgrd/__init__.py

@@ -0,0 +1,7 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Set at build time from the git tag, so there is one source of truth.
+    __version__ = version("nrgrd")
+except PackageNotFoundError:  # Running from a checkout that was never installed.
+    __version__ = "0.0.0"

nrgrd/__main__.py

@@ -0,0 +1,5 @@
+from nrgrd.app import main
+
+
+if __name__ == "__main__":
+    main()

nrgrd/agent/__init__.py

@@ -0,0 +1,29 @@
+from nrgrd.agent.events import (
+    AgentCancelled,
+    AgentError,
+    AgentEvent,
+    AgentFinished,
+    AgentStarted,
+    AssistantChunk,
+    PermissionRequested,
+    ToolCallDenied,
+    ToolCallOutput,
+    ToolCallStarted,
+)
+from nrgrd.agent.loop import Agent
+from nrgrd.agent.permissions import PermissionManager
+
+__all__ = [
+    "Agent",
+    "AgentCancelled",
+    "AgentError",
+    "AgentEvent",
+    "AgentFinished",
+    "AgentStarted",
+    "AssistantChunk",
+    "PermissionManager",
+    "PermissionRequested",
+    "ToolCallDenied",
+    "ToolCallOutput",
+    "ToolCallStarted",
+]

nrgrd/agent/events.py

@@ -0,0 +1,86 @@
+"""Events emitted by the agent loop.
+
+The TUI (or any other interface) renders these; the agent never renders
+anything itself.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AgentStarted:
+    pass
+
+
+@dataclass(frozen=True)
+class AssistantChunk:
+    """A streamed slice of the assistant's reply."""
+
+    delta: str
+    text: str
+
+
+@dataclass(frozen=True)
+class ToolCallStarted:
+    name: str
+    arguments: str
+
+
+@dataclass(frozen=True)
+class ToolCallOutput:
+    name: str
+    result: str
+
+
+@dataclass(frozen=True)
+class PermissionRequested:
+    """The agent is about to ask whether a gated tool may run."""
+
+    name: str
+    arguments: str
+
+
+@dataclass(frozen=True)
+class ToolCallDenied:
+    """A tool call the permission system rejected."""
+
+    name: str
+    arguments: str
+
+
+@dataclass(frozen=True)
+class AgentError:
+    """A failure, split so the interface can render it usefully.
+
+    ``message`` says what happened, ``detail`` shows the configuration
+    involved, and ``hint`` says what to do next.
+    """
+
+    message: str
+    detail: str = ""
+    hint: str = ""
+
+
+@dataclass(frozen=True)
+class AgentCancelled:
+    """The user interrupted. ``text`` is whatever had been generated."""
+
+    text: str
+
+
+@dataclass(frozen=True)
+class AgentFinished:
+    text: str
+
+
+AgentEvent = (
+    AgentStarted
+    | AgentCancelled
+    | AssistantChunk
+    | PermissionRequested
+    | ToolCallStarted
+    | ToolCallOutput
+    | ToolCallDenied
+    | AgentError
+    | AgentFinished
+)

nrgrd/agent/loop.py

@@ -0,0 +1,182 @@
+"""The nrgrd agent runtime: an iterative tool-use loop over an
+OpenAI-compatible model.
+
+This module has no dependency on Rich or Textual. It mutates the message
+list it is given and yields events as they happen; it never prints or
+renders. That keeps it usable headlessly (CLI, tests, future interfaces)
+and testable with a mocked model provider.
+"""
+
+import itertools
+from collections.abc import Iterator
+from typing import Any
+
+from nrgrd.agent.events import (
+    AgentCancelled,
+    AgentError,
+    AgentEvent,
+    AgentFinished,
+    AgentStarted,
+    AssistantChunk,
+    PermissionRequested,
+    ToolCallDenied,
+    ToolCallOutput,
+    ToolCallStarted,
+)
+from nrgrd.agent.permissions import PermissionManager
+from nrgrd.api.provider import ModelProvider, ProviderError
+from nrgrd.tools.registry import PermissionLevel, ToolRegistry
+
+MAX_ITERATIONS = 12
+
+
+class Agent:
+    def __init__(
+        self,
+        provider: ModelProvider,
+        model: str,
+        tool_registry: ToolRegistry,
+        permissions: PermissionManager | None = None,
+        max_iterations: int = MAX_ITERATIONS,
+    ) -> None:
+        self.provider = provider
+        self.model = model
+        self.tool_registry = tool_registry
+        self.permissions = permissions or PermissionManager()
+        self.max_iterations = max_iterations
+        self._call_ids = itertools.count(1)
+
+    def run(self, messages: list[dict[str, Any]]) -> Iterator[AgentEvent]:
+        """Run the tool-use loop, mutating ``messages`` in place."""
+        yield AgentStarted()
+
+        for _ in range(self.max_iterations):
+            response_text = ""
+            tool_calls: dict[int, dict[str, str]] = {}
+
+            try:
+                for delta in self.provider.stream_chat(
+                    model=self.model,
+                    messages=messages,
+                    tools=self.tool_registry.schemas(),
+                ):
+                    if delta.content:
+                        response_text += delta.content
+                        yield AssistantChunk(delta.content, response_text)
+                    for fragment in delta.tool_calls:
+                        # Some compatible servers omit ``index`` and send
+                        # each call whole in one chunk. Keying those on
+                        # None would glue separate calls into one garbled
+                        # call, so give each its own slot instead.
+                        slot = (
+                            fragment.index
+                            if fragment.index is not None
+                            else len(tool_calls)
+                        )
+                        item = tool_calls.setdefault(
+                            slot, {"id": "", "name": "", "arguments": ""}
+                        )
+                        if fragment.id:
+                            item["id"] = fragment.id
+                        if fragment.name:
+                            item["name"] += fragment.name
+                        if fragment.arguments:
+                            item["arguments"] += fragment.arguments
+            except KeyboardInterrupt:
+                # Keep the partial reply: it is context the user may still
+                # want, and dropping it mid-turn loses their work.
+                yield AgentCancelled(response_text)
+                return
+            except ProviderError as error:
+                yield AgentError(error.summary, error.detail, error.hint)
+                return
+            except Exception as error:
+                yield AgentError(str(error))
+                return
+
+            if not tool_calls:
+                yield AgentFinished(response_text)
+                return
+
+            calls = list(tool_calls.values())
+            for call in calls:
+                # Tool results are matched to calls by id, and a blank id
+                # is rejected. Servers that do not send ids get stable,
+                # unique ones.
+                if not call["id"]:
+                    call["id"] = f"call_{next(self._call_ids)}"
+
+            messages.append(
+                {
+                    "role": "assistant",
+                    "content": response_text or None,
+                    "tool_calls": [
+                        {
+                            "id": call["id"],
+                            "type": "function",
+                            "function": {
+                                "name": call["name"],
+                                "arguments": call["arguments"],
+                            },
+                        }
+                        for call in calls
+                    ],
+                }
+            )
+
+            cancelled = False
+            for call in calls:
+                name, arguments = call["name"], call["arguments"]
+                tool = self.tool_registry.get(name)
+
+                if cancelled:
+                    # Interrupted earlier in this batch: run nothing further,
+                    # but still answer the call. An assistant message whose
+                    # tool_calls are not all answered is rejected by the
+                    # endpoint, so a half-filled batch would poison the
+                    # conversation rather than simply end it.
+                    result = "Cancelled by the user."
+                elif tool is None:
+                    # Nothing would run, so there is nothing to approve:
+                    # asking "allow delete_file?" for a tool that does not
+                    # exist only confuses the user. Tell the model instead.
+                    yield ToolCallStarted(name, arguments)
+                    result = self.tool_registry.execute(name, arguments)
+                    yield ToolCallOutput(name, result)
+                else:
+                    level = tool.permission
+
+                    if level is PermissionLevel.ASK:
+                        # Yielded before asking, so an interface can stop
+                        # any live rendering first; otherwise a refreshing
+                        # stream panel draws over the prompt.
+                        yield PermissionRequested(name, arguments)
+
+                    if not self.permissions.check(name, arguments, level):
+                        result = "Permission denied by the user."
+                        yield ToolCallDenied(name, arguments)
+                    else:
+                        yield ToolCallStarted(name, arguments)
+                        try:
+                            result = self.tool_registry.execute(name, arguments)
+                        except KeyboardInterrupt:
+                            cancelled = True
+                            result = "Cancelled by the user."
+                        else:
+                            yield ToolCallOutput(name, result)
+
+                messages.append(
+                    {
+                        "role": "tool",
+                        "tool_call_id": call["id"],
+                        "content": result,
+                    }
+                )
+
+            if cancelled:
+                yield AgentCancelled(response_text)
+                return
+
+        yield AgentError(
+            "Tool call limit reached; please continue with a narrower request."
+        )

nrgrd/agent/permissions.py

@@ -0,0 +1,43 @@
+"""Permission gating for tool calls.
+
+``ALLOW`` and ``DENY`` are decided without user interaction. ``ASK`` defers
+to a callback supplied by the interface (TUI or CLI); the manager never
+silently downgrades ``ASK`` to allowed just because no callback was given.
+"""
+
+from collections.abc import Callable
+
+from nrgrd.tools.registry import PermissionLevel
+
+PermissionCallback = Callable[[str, str], str]
+"""Given a tool name and its raw JSON arguments, return "yes", "no", or "always"."""
+
+
+class PermissionManager:
+    def __init__(self, callback: PermissionCallback | None = None) -> None:
+        self.callback = callback
+        self._always_allowed: set[str] = set()
+
+    @property
+    def session_grants(self) -> list[str]:
+        """Tools the user chose to always allow for this session."""
+        return sorted(self._always_allowed)
+
+    def revoke_session_grants(self) -> None:
+        """Forget every "always allow", so those tools ask again."""
+        self._always_allowed.clear()
+
+    def check(self, name: str, arguments: str, level: PermissionLevel) -> bool:
+        if level == PermissionLevel.ALLOW:
+            return True
+        if level == PermissionLevel.DENY:
+            return False
+        if name in self._always_allowed:
+            return True
+        if self.callback is None:
+            return False
+        decision = self.callback(name, arguments)
+        if decision == "always":
+            self._always_allowed.add(name)
+            return True
+        return decision == "yes"

nrgrd/api/__init__.py

@@ -0,0 +1,15 @@
+from nrgrd.api.openai_compatible import OpenAICompatibleProvider
+from nrgrd.api.provider import (
+    ChatDelta,
+    ModelProvider,
+    ProviderError,
+    ToolCallDelta,
+)
+
+__all__ = [
+    "ChatDelta",
+    "ModelProvider",
+    "OpenAICompatibleProvider",
+    "ProviderError",
+    "ToolCallDelta",
+]

nrgrd/api/openai_compatible.py

@@ -0,0 +1,186 @@
+"""A provider for endpoints that speak the OpenAI HTTP API.
+
+This is not OpenAI. It is the *wire format*: a NeuroGrid deployment, vLLM,
+Ollama, LM Studio, or anything else that serves ``/v1/chat/completions``
+works here, because all nrgrd is given is a URL, a key, and a model name.
+"""
+
+from collections.abc import Iterator, Sequence
+from typing import Any
+
+from openai import (
+    APIConnectionError,
+    APIError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    NotFoundError,
+    OpenAI,
+    PermissionDeniedError,
+    RateLimitError,
+)
+
+from nrgrd.api.provider import ChatDelta, ModelProvider, ProviderError, ToolCallDelta
+
+DEFAULT_TIMEOUT_SECONDS = 120.0
+
+
+class OpenAICompatibleProvider(ModelProvider):
+    name = "OpenAI-compatible"
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_key: str,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+        client: Any | None = None,
+    ) -> None:
+        self.endpoint = endpoint.strip()
+        self._api_key = api_key.strip()
+        self._client = client or OpenAI(
+            base_url=self.endpoint,
+            api_key=self._api_key,
+            timeout=timeout,
+            max_retries=1,
+        )
+
+    def list_models(self) -> list[str]:
+        try:
+            response = self._client.models.list()
+        except Exception as error:
+            raise self._describe(error, model=None) from error
+        return sorted(item.id for item in response.data)
+
+    def stream_chat(
+        self,
+        model: str,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[dict[str, Any]] | None = None,
+    ) -> Iterator[ChatDelta]:
+        request: dict[str, Any] = {
+            "model": model,
+            "messages": list(messages),
+            "stream": True,
+        }
+        # Some compatible servers reject an empty tools array, so only send
+        # the key when there is something to send.
+        if tools:
+            request["tools"] = list(tools)
+            request["tool_choice"] = "auto"
+
+        try:
+            stream = self._client.chat.completions.create(**request)
+            for chunk in stream:
+                if not chunk.choices:
+                    continue
+                delta = chunk.choices[0].delta
+                calls = tuple(
+                    ToolCallDelta(
+                        index=call.index,
+                        id=call.id,
+                        name=call.function.name if call.function else None,
+                        arguments=call.function.arguments if call.function else None,
+                    )
+                    for call in (delta.tool_calls or [])
+                )
+                if delta.content or calls:
+                    yield ChatDelta(content=delta.content, tool_calls=calls)
+        except ProviderError:
+            raise
+        except Exception as error:
+            raise self._describe(error, model=model) from error
+
+    def complete_chat(
+        self,
+        model: str,
+        messages: Sequence[dict[str, Any]],
+    ) -> str:
+        try:
+            response = self._client.chat.completions.create(
+                model=model,
+                messages=list(messages),
+                stream=False,
+            )
+        except Exception as error:
+            raise self._describe(error, model=model) from error
+        return response.choices[0].message.content or ""
+
+    def _redact(self, text: str) -> str:
+        """Strip the API key out of anything on its way to the user."""
+        if self._api_key and self._api_key in text:
+            return text.replace(self._api_key, "***")
+        return text
+
+    def _configuration(self, model: str | None) -> str:
+        lines = [f"Endpoint: {self.endpoint or '(not set)'}"]
+        if model:
+            lines.append(f"Model: {model}")
+        return "\n".join(lines)
+
+    def _describe(self, error: Exception, model: str | None) -> ProviderError:
+        """Turn a transport-level failure into something actionable."""
+        detail = self._configuration(model)
+        change = "Run /config edit to change the configuration."
+
+        if isinstance(error, AuthenticationError):
+            return ProviderError(
+                "The endpoint rejected the API key.",
+                detail,
+                f"Check the key issued with this deployment. {change}",
+            )
+        if isinstance(error, PermissionDeniedError):
+            return ProviderError(
+                "The endpoint refused this request (HTTP 403).",
+                detail,
+                f"The key may not cover this model or route. {change}",
+            )
+        if isinstance(error, NotFoundError):
+            return ProviderError(
+                "The endpoint returned HTTP 404 (not found).",
+                detail,
+                "Check the endpoint path (it usually ends in /v1) and that "
+                f"the model name exists. {change}",
+            )
+        if isinstance(error, RateLimitError):
+            return ProviderError(
+                "The endpoint is rate limiting requests (HTTP 429).",
+                detail,
+                "Wait a moment and try again.",
+            )
+        if isinstance(error, APITimeoutError):
+            return ProviderError(
+                "The endpoint timed out.",
+                detail,
+                "The deployment may be loading the model or overloaded. "
+                "Try again shortly.",
+            )
+        if isinstance(error, APIConnectionError):
+            return ProviderError(
+                "Could not reach the endpoint.",
+                detail,
+                "Check the URL is right, the deployment is still running, "
+                f"and that you are online. {change}",
+            )
+        if isinstance(error, APIStatusError):
+            return ProviderError(
+                f"The endpoint returned HTTP {error.status_code}.",
+                detail,
+                self._redact(str(getattr(error, "message", "")).strip()) or change,
+            )
+        if not isinstance(error, APIError):
+            # The request itself went through, but the reply could not be
+            # read as an API response. Almost always the URL points at
+            # something that is not an OpenAI-compatible API — a web UI, a
+            # proxy error page, or simply the wrong port.
+            return ProviderError(
+                "The endpoint replied with something that is not an "
+                "OpenAI-compatible API response.",
+                detail,
+                "Check the URL points at the API itself (it usually ends "
+                f"in /v1) rather than a web page. {change}",
+            )
+        return ProviderError(
+            "The model request failed.",
+            detail,
+            self._redact(str(error)),
+        )

nrgrd/api/provider.py

@@ -0,0 +1,78 @@
+"""The model provider interface the agent runtime talks to.
+
+The agent never learns which service is behind the endpoint. A provider owns
+HTTP communication, authentication, streaming, and turning wire-level
+failures into :class:`ProviderError`s a user can act on; the agent owns
+context, tools, permissions, and iteration.
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ToolCallDelta:
+    """A slice of one streamed tool call.
+
+    Providers stream tool calls in fragments: the name arrives in one
+    chunk, the arguments across several more. ``index`` identifies which
+    call a fragment belongs to.
+    """
+
+    index: int
+    id: str | None = None
+    name: str | None = None
+    arguments: str | None = None
+
+
+@dataclass(frozen=True)
+class ChatDelta:
+    """One streamed step of a reply: text, tool-call fragments, or both."""
+
+    content: str | None = None
+    tool_calls: tuple[ToolCallDelta, ...] = ()
+
+
+class ProviderError(Exception):
+    """A model request failed, described in terms the user can act on.
+
+    ``summary`` says what happened, ``detail`` shows the configuration the
+    request used, and ``hint`` says what to do about it. None of them may
+    ever contain the API key.
+    """
+
+    def __init__(self, summary: str, detail: str = "", hint: str = "") -> None:
+        super().__init__(summary)
+        self.summary = summary
+        self.detail = detail
+        self.hint = hint
+
+
+class ModelProvider(ABC):
+    """Any endpoint the agent can talk to."""
+
+    name: str = "model provider"
+    endpoint: str = ""
+
+    @abstractmethod
+    def list_models(self) -> list[str]:
+        """Return the model ids the endpoint exposes."""
+
+    @abstractmethod
+    def stream_chat(
+        self,
+        model: str,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[dict[str, Any]] | None = None,
+    ) -> Iterator[ChatDelta]:
+        """Stream a reply, yielding normalized deltas as they arrive."""
+
+    @abstractmethod
+    def complete_chat(
+        self,
+        model: str,
+        messages: Sequence[dict[str, Any]],
+    ) -> str:
+        """Return a complete reply in one shot (used for compaction)."""