nexusagent-runtime 0.4.0__tar.gz

nexusagent_runtime-0.4.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,160 @@
+# 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/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexusagent-runtime"
+description = "A small, modular AI agent runtime in Python — agents, providers, tools and a readable core."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = []
+dynamic = ["version"]
+keywords = ["ai-agents", "agent-runtime", "llm", "tools", "providers"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.scripts]
+nexusagent = "nexusagent.main:main"
+
+[project.urls]
+Homepage = "https://github.com/Abolfazlrwm/nexusagent"
+Repository = "https://github.com/Abolfazlrwm/nexusagent"
+Changelog = "https://github.com/Abolfazlrwm/nexusagent/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Abolfazlrwm/nexusagent/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "mypy>=1.10",
+    "ruff>=0.6",
+    "pre-commit>=3.7",
+    "build>=1.2",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+nexusagent = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = { attr = "nexusagent.__version__" }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=nexusagent --cov-report=term-missing"
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+
+[tool.mypy]
+strict = true
+files = ["src"]
+python_version = "3.10"
+warn_unused_ignores = true
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "BLE", "C4", "SIM", "RUF"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["nexusagent"]

nexusagent_runtime-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nexusagent_runtime-0.4.0/src/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_runtime-0.4.0/src/nexusagent/__main__.py

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

nexusagent_runtime-0.4.0/src/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_runtime-0.4.0/src/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)