nexusagent-runtime 0.4.0__py3-none-any.whl

nexusagent/__init__.py

@@ -0,0 +1,15 @@
+from nexusagent.agent import Agent, AgentResult
+from nexusagent.application import create_application_runtime
+from nexusagent.config import Settings
+from nexusagent.runtime import Runtime, create_runtime
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "Agent",
+    "AgentResult",
+    "Runtime",
+    "Settings",
+    "create_application_runtime",
+    "create_runtime",
+]

nexusagent/__main__.py

@@ -0,0 +1,3 @@
+from nexusagent.main import main
+
+main()

nexusagent/agent.py

@@ -0,0 +1,175 @@
+"""Agent Core for NexusAgent.
+
+Defines the contract for running an agent: input text in, an AgentResult out.
+The Agent delegates generation to a Provider. When it is given a ToolRegistry
+and a ToolExecutor it also runs the autonomous tool loop:
+
+    provider responds -> if it asks for a tool, run it -> feed the result back
+    -> provider responds again -> ... until it answers in plain text
+
+The loop is bounded by ``max_iterations`` so a misbehaving backend can never
+keep the agent running forever. Explicit ``execute_tool()`` remains available.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from nexusagent.logging import get_logger
+from nexusagent.provider import (
+    Provider,
+    ProviderResponse,
+    TextResponse,
+    ToolCallRequest,
+    ToolResult,
+    ToolSpec,
+)
+from nexusagent.tool_executor import ToolExecutionError, ToolExecutor
+from nexusagent.tool_registry import ToolRegistry
+
+DEFAULT_MAX_ITERATIONS = 10
+
+_logger = get_logger("nexusagent.agent")
+
+
+@dataclass(frozen=True)
+class AgentResult:
+    """The result of a single agent run."""
+
+    output: str
+    success: bool
+
+
+class Agent:
+    def __init__(
+        self,
+        provider: Provider,
+        tool_registry: ToolRegistry | None = None,
+        tool_executor: ToolExecutor | None = None,
+        max_iterations: int = DEFAULT_MAX_ITERATIONS,
+    ) -> None:
+        if isinstance(max_iterations, bool) or not isinstance(max_iterations, int):
+            raise TypeError("max_iterations must be an integer")
+
+        if max_iterations < 1:
+            raise ValueError("max_iterations must be at least 1")
+
+        self.provider = provider
+        self.tool_registry = tool_registry
+        self.tool_executor = tool_executor
+        self.max_iterations = max_iterations
+
+    def run(self, input_text: str) -> AgentResult:
+        """Run the agent on the given input and return an AgentResult.
+
+        If the Provider requests tools and this Agent has a ToolRegistry and a
+        ToolExecutor, the requested tools are executed and their results are
+        fed back to the Provider until it returns a plain text answer or
+        ``max_iterations`` provider calls have been made.
+        """
+        if not isinstance(input_text, str):
+            raise TypeError("input_text must be a string")
+
+        if not input_text.strip():
+            raise ValueError("input_text must not be empty or whitespace-only")
+
+        can_use_tools = self.tool_registry is not None and self.tool_executor is not None
+        tools = self._tool_specs() if can_use_tools else ()
+        tool_results: list[ToolResult] = []
+
+        for iteration in range(1, self.max_iterations + 1):
+            try:
+                response = self._ask_provider(input_text, tools, tuple(tool_results))
+            except Exception as exc:  # noqa: BLE001
+                return AgentResult(output=f"provider error: {exc}", success=False)
+
+            if isinstance(response, TextResponse):
+                _logger.debug("iteration %d: provider answered with text", iteration)
+                return AgentResult(output=response.text, success=True)
+
+            if not isinstance(response, ToolCallRequest):
+                return AgentResult(
+                    output=f"provider error: unexpected response type {type(response).__name__}",
+                    success=False,
+                )
+
+            if not can_use_tools:
+                return AgentResult(
+                    output=(
+                        f"provider requested tool {response.tool_name!r} "
+                        "but the agent has no tools configured"
+                    ),
+                    success=False,
+                )
+
+            _logger.info("iteration %d: provider requested tool %r", iteration, response.tool_name)
+            tool_results.append(self._run_tool_call(response))
+
+        return AgentResult(
+            output=f"agent stopped: exceeded the maximum of {self.max_iterations} iterations",
+            success=False,
+        )
+
+    def execute_tool(self, tool_name: str, input_data: str) -> str:
+        """Execute a specific, explicitly named tool and return its output."""
+        if self.tool_registry is None:
+            raise RuntimeError("Agent requires a ToolRegistry to execute tools")
+
+        if self.tool_executor is None:
+            raise RuntimeError("Agent requires a ToolExecutor to execute tools")
+
+        tool = self.tool_registry.get(tool_name)
+        return self.tool_executor.execute(tool, input_data)
+
+    def has_tool(self, tool_name: str) -> bool:
+        """Return whether a tool is currently available through the Agent."""
+        if self.tool_registry is None:
+            raise RuntimeError("Agent requires a ToolRegistry to check tool availability")
+
+        return self.tool_registry.has(tool_name)
+
+    def _ask_provider(
+        self,
+        input_text: str,
+        tools: tuple[ToolSpec, ...],
+        tool_results: tuple[ToolResult, ...],
+    ) -> ProviderResponse:
+        """Ask the provider for its next response.
+
+        Any object with a ``generate(prompt) -> str`` method is accepted as a
+        provider; only ones that also define ``generate_response`` can request
+        tools.
+        """
+        generate_response = getattr(self.provider, "generate_response", None)
+        if generate_response is None:
+            return TextResponse(self.provider.generate(input_text))
+
+        response: ProviderResponse = generate_response(
+            input_text, tools=tools, tool_results=tool_results
+        )
+        return response
+
+    def _tool_specs(self) -> tuple[ToolSpec, ...]:
+        assert self.tool_registry is not None
+        return tuple(ToolSpec(t.name, t.description) for t in self.tool_registry.list_tools())
+
+    def _run_tool_call(self, request: ToolCallRequest) -> ToolResult:
+        """Run one requested tool. Failures become error results, never crashes.
+
+        The Provider (usually a model) is told what went wrong so it can retry
+        with better input, pick another tool, or explain the problem.
+        """
+        try:
+            output = self.execute_tool(request.tool_name, request.tool_input)
+        except KeyError:
+            return self._error_result(request, f"Tool {request.tool_name!r} is not registered")
+        except (TypeError, ValueError, ToolExecutionError) as exc:
+            return self._error_result(request, str(exc))
+
+        _logger.debug("tool %r succeeded", request.tool_name)
+        return ToolResult(request.tool_name, request.tool_input, output)
+
+    @staticmethod
+    def _error_result(request: ToolCallRequest, message: str) -> ToolResult:
+        _logger.warning("tool %r failed: %s", request.tool_name, message)
+        return ToolResult(request.tool_name, request.tool_input, message, is_error=True)

nexusagent/application.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from nexusagent.config import Settings
+from nexusagent.runtime import Runtime
+from nexusagent.runtime_factory import create_tool_runtime
+
+__all__ = ["Runtime", "create_application_runtime"]
+
+
+def create_application_runtime(settings: Settings | None = None) -> Runtime:
+    return create_tool_runtime(settings)

nexusagent/calculator_tool.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import re
+
+from nexusagent.tool import Tool
+
+_EXPRESSION_PATTERN = re.compile(r"\s*(-?\d+(?:\.\d+)?)\s*([+\-*/])\s*(-?\d+(?:\.\d+)?)\s*")
+
+
+class CalculatorTool(Tool):
+    def __init__(self) -> None:
+        super().__init__(name="calculator", description="Performs basic arithmetic operations.")
+
+    def execute(self, input_data: str) -> str:
+        match = _EXPRESSION_PATTERN.fullmatch(input_data)
+        if not match:
+            raise ValueError(
+                "Invalid expression: expected 'number operator number' with operator one of + - * /"
+            )
+
+        left = float(match.group(1))
+        operator = match.group(2)
+        right = float(match.group(3))
+
+        if operator == "+":
+            result = left + right
+        elif operator == "-":
+            result = left - right
+        elif operator == "*":
+            result = left * right
+        else:
+            if right == 0:
+                raise ZeroDivisionError("Division by zero is not allowed")
+            result = left / right
+
+        return _format_result(result)
+
+
+def _format_result(value: float) -> str:
+    if value.is_integer():
+        return str(int(value))
+    return str(value)

nexusagent/config.py

@@ -0,0 +1,81 @@
+"""Application configuration for NexusAgent.
+
+Settings are read from environment variables. No .env loading and no
+external configuration frameworks are used at this stage.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from dataclasses import dataclass
+from urllib.parse import urlparse
+
+SUPPORTED_PROVIDERS = {"fake", "http"}
+
+
+@dataclass(frozen=True, repr=False)
+class Settings:
+    """Basic application settings, loaded from environment variables."""
+
+    env: str = "development"
+    log_level: str = "INFO"
+    model: str | None = None
+    api_key: str | None = None
+    provider: str = "fake"
+    endpoint: str | None = None
+    timeout: float = 30.0
+
+    @classmethod
+    def from_env(cls) -> Settings:
+        """Build Settings from the current process environment."""
+        raw_timeout = os.getenv("NEXUS_TIMEOUT", "30.0")
+        try:
+            timeout = float(raw_timeout)
+        except ValueError:
+            raise ValueError(
+                f"Invalid NEXUS_TIMEOUT: {raw_timeout!r} — "
+                "must be a number of seconds (e.g. 30 or 4.5)"
+            ) from None
+
+        return cls(
+            env=os.getenv("NEXUS_ENV", "development"),
+            log_level=os.getenv("NEXUS_LOG_LEVEL", "INFO"),
+            model=os.getenv("NEXUS_MODEL"),
+            api_key=os.getenv("NEXUS_API_KEY"),
+            provider=os.getenv("NEXUS_PROVIDER", "fake"),
+            endpoint=os.getenv("NEXUS_ENDPOINT"),
+            timeout=timeout,
+        )
+
+    def __repr__(self) -> str:
+        api_key_display = "set" if self.api_key else "None"
+        return (
+            f"Settings(env={self.env!r}, log_level={self.log_level!r}, "
+            f"model={self.model!r}, api_key={api_key_display}, "
+            f"provider={self.provider!r}, endpoint={self.endpoint!r}, "
+            f"timeout={self.timeout!r})"
+        )
+
+    def validate(self) -> None:
+        """Validate the configuration locally, without any network access.
+
+        Raises ValueError with a clear, safe message on the first
+        problem found. Never includes the API key.
+        """
+        if self.provider not in SUPPORTED_PROVIDERS:
+            raise ValueError(f"Unsupported provider: {self.provider!r}")
+
+        if self.model is not None and not self.model.strip():
+            raise ValueError("Model must not be empty")
+
+        if not math.isfinite(self.timeout) or self.timeout <= 0:
+            raise ValueError("Timeout must be a positive finite number")
+
+        if self.provider == "http":
+            if not self.endpoint or not self.endpoint.strip():
+                raise ValueError("HTTP provider requires an endpoint")
+
+            scheme = urlparse(self.endpoint).scheme
+            if scheme not in ("http", "https"):
+                raise ValueError("Endpoint must use http or https")

nexusagent/echo_tool.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from nexusagent.tool import Tool
+
+
+class EchoTool(Tool):
+    def __init__(self) -> None:
+        super().__init__(name="echo", description="Returns its input unchanged.")
+
+    def execute(self, input_data: str) -> str:
+        return input_data

nexusagent/factory.py

@@ -0,0 +1,13 @@
+from nexusagent.http_provider import HttpProvider
+from nexusagent.provider import Provider, ProviderConfig, ProviderConfigurationError
+from nexusagent.providers import FakeProvider
+
+
+def create_provider(name: str, config: ProviderConfig | None = None) -> Provider:
+    if name == "fake":
+        return FakeProvider(config)
+
+    if name == "http":
+        return HttpProvider(config)
+
+    raise ProviderConfigurationError(f"Unsupported provider: {name!r}")

nexusagent/http_provider.py

@@ -0,0 +1,189 @@
+"""Generic HTTP Provider.
+
+Wire format (see docs/protocol.md):
+
+Request  ``POST <endpoint>`` with a JSON body::
+
+    {"model": ..., "input": "<prompt>"}
+
+  and, only when relevant, two extra keys::
+
+    "tools":        [{"name": ..., "description": ...}, ...]
+    "tool_results": [{"tool_name": ..., "tool_input": ..., "output": ...,
+                      "is_error": false}, ...]
+
+Response  a JSON object that is exactly one of::
+
+    {"output": "<text answer>"}
+    {"tool_name": "<tool>", "tool_input": "<input for the tool>"}
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from collections.abc import Sequence
+
+from nexusagent.provider import (
+    Provider,
+    ProviderConfig,
+    ProviderConfigurationError,
+    ProviderRequestError,
+    ProviderResponse,
+    ProviderResponseError,
+    TextResponse,
+    ToolCallRequest,
+    ToolResult,
+    ToolSpec,
+)
+
+_BODY_SNIPPET_MAX_CHARS = 200
+
+
+def _response_body_snippet(exc: urllib.error.HTTPError) -> str:
+    """Return a short, single-line snippet of an HTTP error body (best effort)."""
+    try:
+        body = exc.read().decode("utf-8", errors="replace").strip()
+    except Exception:  # noqa: BLE001 — the body is optional context, never fatal
+        return ""
+
+    if not body:
+        return ""
+
+    snippet = " ".join(body.split())
+    if len(snippet) > _BODY_SNIPPET_MAX_CHARS:
+        snippet = snippet[:_BODY_SNIPPET_MAX_CHARS] + "..."
+    return f": {snippet}"
+
+
+class HttpProvider(Provider):
+    def __init__(self, config: ProviderConfig | None = None) -> None:
+        self.config = config or ProviderConfig()
+
+    def generate(self, prompt: str) -> str:
+        response = self.generate_response(prompt)
+
+        if isinstance(response, ToolCallRequest):
+            raise ProviderResponseError(
+                "HTTP response requested a tool call; use generate_response() to handle it"
+            )
+
+        return response.text
+
+    def generate_response(
+        self,
+        prompt: str,
+        *,
+        tools: Sequence[ToolSpec] = (),
+        tool_results: Sequence[ToolResult] = (),
+    ) -> ProviderResponse:
+        payload = self._post(self._build_body(prompt, tools, tool_results))
+        return self._parse_payload(payload)
+
+    def _build_body(
+        self,
+        prompt: str,
+        tools: Sequence[ToolSpec],
+        tool_results: Sequence[ToolResult],
+    ) -> dict[str, object]:
+        body: dict[str, object] = {"model": self.config.model, "input": prompt}
+
+        if tools:
+            body["tools"] = [{"name": t.name, "description": t.description} for t in tools]
+
+        if tool_results:
+            body["tool_results"] = [
+                {
+                    "tool_name": r.tool_name,
+                    "tool_input": r.tool_input,
+                    "output": r.output,
+                    "is_error": r.is_error,
+                }
+                for r in tool_results
+            ]
+
+        return body
+
+    def _post(self, body: dict[str, object]) -> object:
+        if not self.config.endpoint:
+            raise ProviderConfigurationError("HttpProvider requires a configured endpoint")
+
+        if self.config.timeout <= 0:
+            raise ProviderConfigurationError("HttpProvider requires a positive timeout")
+
+        headers = {"Content-Type": "application/json"}
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+
+        request = urllib.request.Request(
+            self.config.endpoint,
+            data=json.dumps(body).encode("utf-8"),
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=self.config.timeout) as response:
+                raw = response.read()
+        except urllib.error.HTTPError as exc:
+            # Include a short snippet of the response body when available: real
+            # backends put useful context there (rate limits, auth failures, ...).
+            detail = _response_body_snippet(exc)
+            raise ProviderRequestError(
+                f"HTTP request failed with status {exc.code}{detail}"
+            ) from None
+        except urllib.error.URLError as exc:
+            raise ProviderRequestError(f"HTTP request failed: {exc.reason}") from None
+        except TimeoutError:
+            raise ProviderRequestError("HTTP request timed out") from None
+
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            raise ProviderResponseError("HTTP response was not valid JSON") from None
+
+    @staticmethod
+    def _parse_payload(payload: object) -> ProviderResponse:
+        if not isinstance(payload, dict):
+            raise ProviderResponseError("HTTP response must be a JSON object")
+
+        has_output = "output" in payload
+        has_tool_call = "tool_name" in payload
+
+        if has_output and has_tool_call:
+            raise ProviderResponseError(
+                "HTTP response must contain either 'output' or 'tool_name', not both"
+            )
+
+        if has_tool_call:
+            return HttpProvider._parse_tool_call(payload)
+
+        if not has_output:
+            raise ProviderResponseError("HTTP response is missing the 'output' field")
+
+        output = payload["output"]
+        if not isinstance(output, str):
+            raise ProviderResponseError("HTTP response 'output' field must be a string")
+
+        if not output.strip():
+            raise ProviderResponseError("HTTP response 'output' field must not be empty")
+
+        return TextResponse(output)
+
+    @staticmethod
+    def _parse_tool_call(payload: dict[str, object]) -> ToolCallRequest:
+        tool_name = payload["tool_name"]
+        if not isinstance(tool_name, str) or not tool_name.strip():
+            raise ProviderResponseError(
+                "HTTP response 'tool_name' field must be a non-empty string"
+            )
+
+        if "tool_input" not in payload:
+            raise ProviderResponseError("HTTP response is missing the 'tool_input' field")
+
+        tool_input = payload["tool_input"]
+        if not isinstance(tool_input, str):
+            raise ProviderResponseError("HTTP response 'tool_input' field must be a string")
+
+        return ToolCallRequest(tool_name=tool_name, tool_input=tool_input)

nexusagent/logging.py

@@ -0,0 +1,60 @@
+"""Centralized logging setup for NexusAgent.
+
+Provides get_logger() for obtaining namespaced loggers, and
+configure_logging() to attach a single console handler with a
+level derived from the existing Settings configuration.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from nexusagent.config import Settings
+
+_ROOT_LOGGER_NAME = "nexusagent"
+_LOG_FORMAT = "%(asctime)s | %(levelname)s | %(name)s | %(message)s"
+_DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    """Return a logger under the nexusagent namespace.
+
+    Without a name, returns the main "nexusagent" logger.
+    With a name (e.g. "nexusagent.agent"), returns that named logger.
+    """
+    if name is None:
+        return logging.getLogger(_ROOT_LOGGER_NAME)
+    return logging.getLogger(name)
+
+
+def _resolve_level(level: str) -> int:
+    resolved = logging.getLevelName(level.upper())
+    if not isinstance(resolved, int):
+        raise ValueError(f"Invalid log level: {level!r}")
+    return resolved
+
+
+def configure_logging(level: str | None = None) -> logging.Logger:
+    """Configure the nexusagent root logger with a console handler.
+
+    The log level defaults to the value provided by Settings
+    (NEXUS_LOG_LEVEL) unless explicitly overridden. Calling this
+    function multiple times is safe and will not attach duplicate
+    handlers.
+    """
+    if level is None:
+        level = Settings.from_env().log_level
+
+    resolved_level = _resolve_level(level)
+
+    logger = logging.getLogger(_ROOT_LOGGER_NAME)
+    logger.setLevel(resolved_level)
+    logger.propagate = False
+
+    has_console_handler = any(isinstance(h, logging.StreamHandler) for h in logger.handlers)
+    if not has_console_handler:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter(_LOG_FORMAT, datefmt=_DATE_FORMAT))
+        logger.addHandler(handler)
+
+    return logger

nexusagent/main.py

@@ -0,0 +1,75 @@
+import argparse
+import sys
+from dataclasses import replace
+
+from nexusagent.application import Runtime, create_application_runtime
+from nexusagent.config import Settings
+from nexusagent.provider import ProviderError
+from nexusagent.tool_executor import ToolExecutionError
+
+
+def _build_tool_runtime() -> Runtime:
+    return create_application_runtime()
+
+
+def _run_tool_list_command() -> None:
+    runtime = _build_tool_runtime()
+    for tool in runtime.list_tools():
+        print(f"{tool.name} - {tool.description}")
+
+
+def _run_tool_command(argv: list[str]) -> None:
+    parser = argparse.ArgumentParser(prog="nexusagent tool")
+    subparsers = parser.add_subparsers(dest="tool_command", required=True)
+
+    run_parser = subparsers.add_parser("run", help="run a registered tool")
+    run_parser.add_argument("tool_name", help="name of the tool to run")
+    run_parser.add_argument("input_data", help="input passed to the tool")
+
+    subparsers.add_parser("list", help="list registered tools")
+
+    args = parser.parse_args(argv)
+
+    if args.tool_command == "list":
+        _run_tool_list_command()
+        return
+
+    runtime = _build_tool_runtime()
+
+    try:
+        result = runtime.execute_tool(args.tool_name, args.input_data)
+    except (KeyError, TypeError, ValueError, ToolExecutionError, RuntimeError) as exc:
+        print(f"nexusagent: error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    print(result)
+
+
+def main() -> None:
+    argv = sys.argv[1:]
+
+    if argv and argv[0] == "tool":
+        _run_tool_command(argv[1:])
+        return
+
+    parser = argparse.ArgumentParser(prog="nexusagent")
+    parser.add_argument("input_text", help="input text to run through the agent")
+    parser.add_argument("--provider", help="provider to use (overrides NEXUS_PROVIDER)")
+    args = parser.parse_args(argv)
+
+    settings = Settings.from_env()
+    if args.provider is not None:
+        settings = replace(settings, provider=args.provider)
+
+    try:
+        runtime = create_application_runtime(settings)
+    except (ValueError, ProviderError) as exc:
+        print(f"nexusagent: error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    result = runtime.run(args.input_text)
+    if not result.success:
+        print(f"nexusagent: error: {result.output}", file=sys.stderr)
+        sys.exit(1)
+
+    print(result.output)

nexusagent/provider.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, repr=False)
+class ProviderConfig:
+    model: str | None = None
+    api_key: str | None = None
+    endpoint: str | None = None
+    timeout: float = 30.0
+
+    def __repr__(self) -> str:
+        api_key_display = "set" if self.api_key else "None"
+        return (
+            f"ProviderConfig(model={self.model!r}, api_key={api_key_display}, "
+            f"endpoint={self.endpoint!r}, timeout={self.timeout!r})"
+        )
+
+
+@dataclass(frozen=True)
+class TextResponse:
+    """A plain text response from a Provider."""
+
+    text: str
+
+
+@dataclass(frozen=True)
+class ToolCallRequest:
+    """A request from a Provider to call a specific Tool."""
+
+    tool_name: str
+    tool_input: str
+
+
+ProviderResponse = TextResponse | ToolCallRequest
+"""What a Provider can answer with: either a plain text answer or a request
+to call a tool. This is what ``Provider.generate_response()`` returns and what
+the Agent's tool loop consumes."""
+
+
+@dataclass(frozen=True)
+class ToolSpec:
+    """A tool advertised to the Provider so it knows what it may request."""
+
+    name: str
+    description: str
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    """The outcome of a ``ToolCallRequest``, fed back to the Provider.
+
+    ``is_error`` is True when the tool could not be run or failed; ``output``
+    then holds the error message so the model can recover or explain.
+    """
+
+    tool_name: str
+    tool_input: str
+    output: str
+    is_error: bool = False
+
+
+class Provider(ABC):
+    @abstractmethod
+    def generate(self, prompt: str) -> str: ...
+
+    def generate_response(
+        self,
+        prompt: str,
+        *,
+        tools: Sequence[ToolSpec] = (),
+        tool_results: Sequence[ToolResult] = (),
+    ) -> ProviderResponse:
+        """Return a structured response for ``prompt``.
+
+        ``tools`` lists the tools the Provider may request; ``tool_results``
+        holds the results of tool calls it already requested in this run, in
+        order. The default implementation wraps ``generate()`` and therefore
+        only ever answers with text, so text-only Providers need no changes.
+        Providers that can request tools override this method.
+        """
+        return TextResponse(self.generate(prompt))
+
+
+class ProviderError(Exception):
+    """Base exception for provider-related failures."""
+
+
+class ProviderConfigurationError(ProviderError):
+    """Raised when provider configuration is invalid for a provider."""
+
+
+class ProviderRequestError(ProviderError):
+    """Raised when a provider request fails."""
+
+
+class ProviderResponseError(ProviderError):
+    """Raised when a provider response is invalid."""

nexusagent/providers.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+from nexusagent.provider import (
+    Provider,
+    ProviderConfig,
+    ProviderResponse,
+    ProviderResponseError,
+    TextResponse,
+    ToolResult,
+    ToolSpec,
+)
+
+
+class FakeProvider(Provider):
+    def __init__(self, config: ProviderConfig | None = None) -> None:
+        self.config = config or ProviderConfig()
+
+    def generate(self, prompt: str) -> str:
+        return f"fake response: {prompt}"
+
+
+class ScriptedProvider(Provider):
+    """A deterministic, network-free Provider that replays a fixed script.
+
+    Each call to ``generate_response()`` returns the next scripted
+    ``ProviderResponse``. It is meant for demos and tests of the tool loop:
+    script a ``ToolCallRequest`` followed by a ``TextResponse`` and the Agent
+    will run the tool and finish. Every call is recorded in ``calls``.
+    """
+
+    def __init__(self, responses: Iterable[ProviderResponse]) -> None:
+        self._responses = list(responses)
+        self._position = 0
+        self.calls: list[tuple[str, tuple[ToolSpec, ...], tuple[ToolResult, ...]]] = []
+
+    def generate(self, prompt: str) -> str:
+        response = self.generate_response(prompt)
+        if not isinstance(response, TextResponse):
+            raise ProviderResponseError("scripted response is a tool call, not text")
+        return response.text
+
+    def generate_response(
+        self,
+        prompt: str,
+        *,
+        tools: Sequence[ToolSpec] = (),
+        tool_results: Sequence[ToolResult] = (),
+    ) -> ProviderResponse:
+        self.calls.append((prompt, tuple(tools), tuple(tool_results)))
+
+        if self._position >= len(self._responses):
+            raise ProviderResponseError("ScriptedProvider has no more scripted responses")
+
+        response = self._responses[self._position]
+        self._position += 1
+        return response

nexusagent/runtime.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from nexusagent.agent import Agent, AgentResult
+from nexusagent.config import Settings
+from nexusagent.factory import create_provider
+from nexusagent.provider import ProviderConfig
+from nexusagent.tool import Tool
+from nexusagent.tool_executor import ToolExecutor
+from nexusagent.tool_registry import ToolRegistry
+
+
+class Runtime:
+    def __init__(
+        self,
+        agent: Agent,
+        tool_registry: ToolRegistry | None = None,
+        tool_executor: ToolExecutor | None = None,
+    ) -> None:
+        self.agent = agent
+        self.tool_registry = tool_registry
+        self.tool_executor = tool_executor
+
+    def run(self, input_text: str) -> AgentResult:
+        return self.agent.run(input_text)
+
+    def execute_tool(self, tool_name: str, input_data: str) -> str:
+        return self.agent.execute_tool(tool_name, input_data)
+
+    def list_tools(self) -> list[Tool]:
+        if self.tool_registry is None:
+            raise RuntimeError("Runtime requires a ToolRegistry to list tools")
+
+        return self.tool_registry.list_tools()
+
+
+def create_runtime(
+    settings: Settings | None = None,
+    tool_registry: ToolRegistry | None = None,
+    tool_executor: ToolExecutor | None = None,
+) -> Runtime:
+    if settings is None:
+        settings = Settings.from_env()
+
+    settings.validate()
+
+    config = ProviderConfig(
+        model=settings.model,
+        api_key=settings.api_key,
+        endpoint=settings.endpoint,
+        timeout=settings.timeout,
+    )
+    provider = create_provider(settings.provider, config)
+    agent = Agent(provider, tool_registry=tool_registry, tool_executor=tool_executor)
+    return Runtime(agent, tool_registry=tool_registry, tool_executor=tool_executor)

nexusagent/runtime_factory.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from nexusagent.config import Settings
+from nexusagent.runtime import Runtime, create_runtime
+from nexusagent.tool_executor import ToolExecutor
+from nexusagent.tool_factory import create_tool_registry
+
+
+def create_tool_runtime(settings: Settings | None = None) -> Runtime:
+    registry = create_tool_registry()
+    executor = ToolExecutor()
+    return create_runtime(settings, tool_registry=registry, tool_executor=executor)

nexusagent/tool.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class Tool(ABC):
+    def __init__(self, name: str, description: str) -> None:
+        if not isinstance(name, str):
+            raise TypeError("Tool name must be a string")
+
+        if not name.strip():
+            raise ValueError("Tool name must not be empty or whitespace-only")
+
+        if not isinstance(description, str):
+            raise TypeError("Tool description must be a string")
+
+        if not description.strip():
+            raise ValueError("Tool description must not be empty or whitespace-only")
+
+        self.name = name
+        self.description = description
+
+    @abstractmethod
+    def execute(self, input_data: str) -> str: ...

nexusagent/tool_executor.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from nexusagent.tool import Tool
+
+
+class ToolExecutionError(Exception):
+    """Raised when a Tool's execute() call fails."""
+
+
+class ToolExecutor:
+    def execute(self, tool: Tool, input_data: str) -> str:
+        if not isinstance(tool, Tool):
+            raise TypeError("ToolExecutor requires a Tool instance")
+
+        if not isinstance(input_data, str):
+            raise TypeError("Tool input must be a string")
+
+        if not input_data.strip():
+            raise ValueError("Tool input must not be empty or whitespace-only")
+
+        try:
+            return tool.execute(input_data)
+        except Exception as exc:
+            # Preserve the original error class in the message: the chain keeps the
+            # exception itself, but callers often only see the ToolExecutionError text.
+            raise ToolExecutionError(f"{type(exc).__name__}: {exc}") from exc

nexusagent/tool_factory.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from nexusagent.calculator_tool import CalculatorTool
+from nexusagent.echo_tool import EchoTool
+from nexusagent.tool_registry import ToolRegistry
+from nexusagent.uppercase_tool import UppercaseTool
+
+
+def create_tool_registry() -> ToolRegistry:
+    registry = ToolRegistry()
+    registry.register(EchoTool())
+    registry.register(UppercaseTool())
+    registry.register(CalculatorTool())
+    return registry

nexusagent/tool_registry.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from nexusagent.tool import Tool
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, Tool] = {}
+
+    def register(self, tool: Tool) -> None:
+        if not isinstance(tool, Tool):
+            raise TypeError("ToolRegistry requires a Tool instance")
+
+        if tool.name in self._tools:
+            raise ValueError(f"Tool {tool.name!r} is already registered")
+
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool:
+        self._validate_name(name)
+
+        if name not in self._tools:
+            raise KeyError(f"Tool {name!r} is not registered")
+
+        return self._tools[name]
+
+    def has(self, name: str) -> bool:
+        self._validate_name(name)
+
+        return name in self._tools
+
+    def unregister(self, name: str) -> None:
+        self._validate_name(name)
+
+        if name not in self._tools:
+            raise KeyError(f"Tool {name!r} is not registered")
+
+        del self._tools[name]
+
+    def list_tools(self) -> list[Tool]:
+        return list(self._tools.values())
+
+    @staticmethod
+    def _validate_name(name: str) -> None:
+        if not isinstance(name, str):
+            raise TypeError("Tool name must be a string")
+
+        if not name.strip():
+            raise ValueError("Tool name must not be empty or whitespace-only")

nexusagent/uppercase_tool.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from nexusagent.tool import Tool
+
+
+class UppercaseTool(Tool):
+    def __init__(self) -> None:
+        super().__init__(name="uppercase", description="Converts input to uppercase.")
+
+    def execute(self, input_data: str) -> str:
+        return input_data.upper()

nexusagent_runtime-0.4.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: nexusagent-runtime
+Version: 0.4.0
+Summary: A small, modular AI agent runtime in Python — agents, providers, tools and a readable core.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Abolfazlrwm/nexusagent
+Project-URL: Repository, https://github.com/Abolfazlrwm/nexusagent
+Project-URL: Changelog, https://github.com/Abolfazlrwm/nexusagent/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Abolfazlrwm/nexusagent/issues
+Keywords: ai-agents,agent-runtime,llm,tools,providers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+
+# NexusAgent
+
+[![CI](https://github.com/Abolfazlrwm/nexusagent/actions/workflows/ci.yml/badge.svg)](https://github.com/Abolfazlrwm/nexusagent/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Abolfazlrwm/nexusagent/gh-pages/coverage-badge.json)](https://github.com/Abolfazlrwm/nexusagent/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/nexusagent-runtime)](https://pypi.org/project/nexusagent-runtime/)
+[![Python](https://img.shields.io/pypi/pyversions/nexusagent-runtime)](https://pypi.org/project/nexusagent-runtime/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**A modular runtime for AI agents in Python — zero runtime dependencies, a small readable core, and an honest feature list.**
+
+Most agent frameworks hand you a galaxy of abstractions. NexusAgent is the opposite: ~500 lines of typed, contract-tested core that you can read in one sitting — providers, tools, a bounded autonomous tool loop, and a CLI. Nothing hidden, nothing magic.
+
+```python
+from nexusagent import create_application_runtime
+
+runtime = create_application_runtime()  # offline `fake` provider by default
+
+result = runtime.run("Hello NexusAgent")
+print(result.output)  # fake response: Hello NexusAgent
+print(result.success)  # True
+
+print(runtime.execute_tool("calculator", "2 + 3"))  # 5
+```
+
+## Why NexusAgent
+
+- **Zero runtime dependencies** — the whole core is the Python standard library. `pip install nexusagent-runtime` pulls nothing else.
+- **Readable by design** — the core is small enough to audit in an afternoon; architecture rules are enforced by tests, not comments.
+- **Honest** — the feature list below says what exists *and what doesn't*. No fake benchmarks, no aspirational docs.
+- **Typed** — ships `py.typed`; the source itself passes `mypy --strict`.
+- **Tested** — 600+ contract tests, ≥95% coverage floor enforced in CI.
+
+## Features
+
+| Capability | Status |
+| --- | --- |
+| Provider abstraction (bring any backend) | ✅ |
+| Autonomous tool loop, bounded by `max_iterations` | ✅ |
+| Vendor-neutral HTTP wire protocol | ✅ [docs/protocol.md](docs/protocol.md) |
+| Built-in tools: `echo`, `uppercase`, `calculator` | ✅ |
+| Custom tools / custom providers via small ABCs | ✅ [guides](docs/) |
+| Configuration via `NEXUS_*` environment variables | ✅ |
+| CLI (`nexusagent`, `python -m nexusagent`) | ✅ |
+| Fully typed (`py.typed`), strict mypy clean | ✅ |
+| Async execution / streaming | ❌ |
+| Memory, planning, multi-agent orchestration | ❌ |
+| Vendor adapters (OpenAI, Anthropic, …) | ❌ |
+| Retries / backoff on HTTP failures | ❌ |
+
+## Architecture
+
+```mermaid
+flowchart LR
+    U["your code / CLI"] --> R["Runtime"]
+    R --> A["Agent"]
+    A -- "generate_response()" --> P["Provider<br/>(fake · scripted · http)"]
+    P -- "TextResponse" --> A
+    P -- "ToolCallRequest" --> A
+    A --> X["ToolExecutor"]
+    X --> T["ToolRegistry<br/>echo · uppercase · calculator"]
+    X -- "ToolResult" --> A
+```
+
+The Provider answers with text or requests a tool; the Agent runs the tool
+and feeds the result back, repeating until a text answer or the iteration
+limit. Deeper details: [docs/architecture.md](docs/architecture.md) ·
+concepts: [docs/concepts.md](docs/concepts.md) · decisions:
+[docs/adr/](docs/adr/).
+
+## Installation
+
+```bash
+pip install nexusagent-runtime
+```
+
+> The **import name** is `nexusagent`; the **PyPI distribution** is
+> `nexusagent-runtime` — the exact name `nexusagent` is blocked on PyPI by an
+> unrelated placeholder package (`nexus-agent`), see
+> [ADR 0004](docs/adr/0004-pypi-distribution-name.md).
+
+Requires Python 3.10–3.13. From source:
+
+```bash
+git clone https://github.com/Abolfazlrwm/nexusagent
+cd nexusagent
+pip install -e ".[dev]"
+python scripts/check.py   # lint + format + mypy --strict + tests
+```
+
+## Usage
+
+### Agent with tools
+
+```python
+from nexusagent import create_application_runtime
+
+runtime = create_application_runtime()
+
+print(runtime.list_tools())
+# [EchoTool, UppercaseTool, CalculatorTool]
+
+# The provider decides when to request a tool; the agent runs the loop.
+result = runtime.run("What is 19 + 23?")
+```
+
+### The tool loop, end to end, offline
+
+```bash
+python examples/tool_loop_demo.py
+```
+
+Starts a local "model backend" speaking the [HTTP protocol](docs/protocol.md),
+requests the calculator, and turns the result into a final answer — no API
+key, no internet.
+
+### CLI
+
+```bash
+nexusagent "your prompt"          # or: python -m nexusagent "your prompt"
+nexusagent tool list
+nexusagent tool run calculator "2 + 3"
+```
+
+### Configuration
+
+| Variable | Meaning | Default |
+| --- | --- | --- |
+| `NEXUS_PROVIDER` | `fake` or `http` | `fake` |
+| `NEXUS_ENDPOINT` | HTTP provider URL | — |
+| `NEXUS_MODEL` | model identifier passed to the provider | — |
+| `NEXUS_API_KEY` | sent as `Bearer` token (never logged, masked in reprs) | — |
+| `NEXUS_TIMEOUT` | HTTP timeout in seconds | `30` |
+
+## Examples
+
+All examples run offline, with no API keys:
+
+- [`examples/basic.py`](examples/basic.py) — smallest possible run
+- [`examples/custom_tool.py`](examples/custom_tool.py) — define and register your own tool
+- [`examples/tool_loop_demo.py`](examples/tool_loop_demo.py) — the autonomous tool loop over local HTTP
+- [`examples/http_provider_local.py`](examples/http_provider_local.py) — `http` provider against a local backend
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — layers, module map, dependency rules
+- [Concepts](docs/concepts.md) — Agent, Provider, Tool, Runtime, Settings
+- [Guides](docs/) — write a custom [provider](docs/guides/custom-provider.md) or [tool](docs/guides/custom-tool.md)
+- [HTTP protocol](docs/protocol.md) — wire format for backends
+- [ADRs](docs/adr/) — architecture decision records
+- [Security policy](SECURITY.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
+
+## Project status
+
+Actively developed, pre-1.0. See [PROJECT_STATUS.md](PROJECT_STATUS.md) for
+a candid snapshot of what works and what the next steps are. Breaking public
+API changes require an ADR and are discussed in the open.
+
+## License
+
+[MIT](LICENSE)

nexusagent_runtime-0.4.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+nexusagent/__init__.py,sha256=7FZQXiKE_ZNHrX2qrDVHIccab94TZQ28_UTZ0qw5oWI,361
+nexusagent/__main__.py,sha256=e85R9MeC3LyBNDBOd8UPQkCPUWBMxbAuM5AU-T90C4Y,41
+nexusagent/agent.py,sha256=9k2fQAOW-nCp-b7d9RXHi-E4EpGTVDDv6qS33wRzGhs,6806
+nexusagent/application.py,sha256=rDHWdTFLSCVcjH-aSgxfg4Zb8sTPtJ_yLsNwOiS2Ygg,346
+nexusagent/calculator_tool.py,sha256=IlP5QmH29_5a3aA9ylK9ASRfbcX2f0qvR6YrZ6RdNo0,1219
+nexusagent/config.py,sha256=8Mu8StfwXYI_-GuUdmy-r71sJWmWXWfdjuiwUZZWaYw,2819
+nexusagent/echo_tool.py,sha256=Cu6B4oAdtZ9r1cyrsc_NSlEfYbxQfpp-ncwXcQ3tyj4,281
+nexusagent/factory.py,sha256=F-Lv9V0Z431jwBWvIedkEHlAqyJAg8summ-jdaFrnCc,457
+nexusagent/http_provider.py,sha256=5WPRdzEthckQjothOH1csHo_S3Ri1aKY6xSuFIMCHHY,6292
+nexusagent/logging.py,sha256=2DiDJezI0luO79Krq7MlwIJ3PqauOtbGFbFNaZcR-HM,1912
+nexusagent/main.py,sha256=yZfbMUneBSUCgtb2vAj_zXYt0RkQDuxr73vOXNEi6SI,2323
+nexusagent/provider.py,sha256=ef1_s7g6YNbiZfrdqi79TE6rMJkMvdbC5roxr_yAb0c,2779
+nexusagent/providers.py,sha256=39mX_gG3gQB0p9OslmqyeSl-8DG6dLteAYV-cqU0C4w,1899
+nexusagent/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nexusagent/runtime.py,sha256=Fq_uPrZBkwZXB94UB4C6xfuH7zrYtZlJPq9ZU9pJtjs,1739
+nexusagent/runtime_factory.py,sha256=BAiiMpOViCZQCjS8Gy8GwA4vRmYqfSK-sFxQePnNEgs,461
+nexusagent/tool.py,sha256=6I9Nxi0v7xxtkIlx3S_hV_SwoRjc-6JC9qgM2W_sixs,728
+nexusagent/tool_executor.py,sha256=5-RXIIms2NV7cAsa16XYBtepG8RSqTD34f-OhkZnRXY,911
+nexusagent/tool_factory.py,sha256=oOK_YlNeomycXxuIE4XSC0XHGOD9Z336SiDRZGen7TU,443
+nexusagent/tool_registry.py,sha256=1nW77MWUce8pxFYKN_Bu9yncqtSZYS8bp5SSZsyKtSw,1346
+nexusagent/uppercase_tool.py,sha256=jvIHQ9ebdNVDE6gAaRp7t0YldyCkrHqqoBiy8J4mnZ4,299
+nexusagent_runtime-0.4.0.dist-info/licenses/LICENSE,sha256=YnGz4nqnN3q5lB6AqSa_-tpK4btjj0dolg8D7ZtIIFI,1069
+nexusagent_runtime-0.4.0.dist-info/METADATA,sha256=f64Cca2IwtdGvmZksF0ug46ANy5lga9woMYuyXbaPp4,7622
+nexusagent_runtime-0.4.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nexusagent_runtime-0.4.0.dist-info/entry_points.txt,sha256=YksSV12J-TqF8zt9QMo78_EjZMmJgnkJLG8cio6TrZU,52
+nexusagent_runtime-0.4.0.dist-info/top_level.txt,sha256=sXZ4p_tmv61VOgQG2VcxWV-PUmzCgOcewTKJhQLSPOA,11
+nexusagent_runtime-0.4.0.dist-info/RECORD,,

nexusagent_runtime-0.4.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nexusagent_runtime-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nexusagent = nexusagent.main:main

nexusagent_runtime-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abolfazl RWM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nexusagent_runtime-0.4.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nexusagent