agentlings 0.2.2__tar.gz → 0.2.4__tar.gz

{agentlings-0.2.2 → agentlings-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlings
-Version: 0.2.2
+Version: 0.2.4
 Summary: Lightweight A2A + MCP single-process agent framework
 Project-URL: Homepage, https://github.com/andyjmorgan/DonkeyWork-Agentlings
 Project-URL: Repository, https://github.com/andyjmorgan/DonkeyWork-Agentlings

{agentlings-0.2.2 → agentlings-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentlings"
-version = "0.2.2"
+version = "0.2.4"
 description = "Lightweight A2A + MCP single-process agent framework"
 readme = "README.md"
 license = { text = "MIT" }

{agentlings-0.2.2 → agentlings-0.2.4}/src/agentlings/config.py

@@ -162,6 +162,7 @@ class AgentConfig(BaseSettings):
     agent_otel_insecure: bool = True
     agent_otel_headers: str = ""
     agent_task_await_seconds: int = 60
+    agent_tools_dir: Path | None = None
 
     _definition: AgentDefinition = AgentDefinition()
 

{agentlings-0.2.2 → agentlings-0.2.4}/src/agentlings/protocol/a2a.py

@@ -7,6 +7,11 @@ A2A ``Task`` object (``status.state == working``) is enqueued so the caller
 can poll via ``GetTask`` — those GetTask calls are routed back to our engine
 by ``EngineTaskStore`` so the SDK's answers always reflect live state.
 
+Clients can opt out of the await window per-request by setting
+``configuration.return_immediately = true`` on ``message/send``; in that
+case the executor passes ``await_seconds=0`` to the engine and a ``Task``
+object is enqueued without blocking.
+
 Cancellation (``CancelTask``) hits the engine's cancel path by task id.
 """
 
@@ -78,10 +83,19 @@ class AgentlingExecutor(AgentExecutor):
         # through EngineTaskStore) and the Task object we enqueue all agree.
         sdk_task_id = context.task_id
 
+        # A2A 1.0: clients can opt out of blocking by setting
+        # ``configuration.return_immediately``. When set, skip the await
+        # window so a Task handle is enqueued immediately.
+        return_immediately = bool(
+            getattr(context.configuration, "return_immediately", False)
+        )
+        await_seconds = 0.0 if return_immediately else self._await_seconds
+
         logger.debug(
-            "a2a execute: context_id=%s task_id=%s text=%r",
+            "a2a execute: context_id=%s task_id=%s return_immediately=%s text=%r",
             context_id,
             sdk_task_id,
+            return_immediately,
             (user_text or "")[:100],
         )
 
@@ -90,7 +104,7 @@ class AgentlingExecutor(AgentExecutor):
                 message=user_text,
                 context_id=context_id,
                 via="a2a",
-                await_seconds=self._await_seconds,
+                await_seconds=await_seconds,
                 task_id=sdk_task_id,
             )
         except ContextBusyError as e:

{agentlings-0.2.2 → agentlings-0.2.4}/src/agentlings/server.py

@@ -32,6 +32,7 @@ from agentlings.protocol.a2a import AgentlingExecutor
 from agentlings.protocol.a2a_task_store import EngineTaskStore
 from agentlings.protocol.agent_card import generate_agent_card
 from agentlings.protocol.mcp import create_mcp_server
+from agentlings.tools.loader import load_tools_from_directory
 from agentlings.tools.memory import init_memory_tool
 from agentlings.tools.registry import ToolRegistry
 
@@ -91,6 +92,9 @@ def _create_app(config: AgentConfig | None = None) -> Starlette:
     tools = ToolRegistry()
     tools.register_tools(config.enabled_tools, bash_timeout=config.definition.bash_timeout)
 
+    if config.agent_tools_dir is not None:
+        load_tools_from_directory(config.agent_tools_dir, tools)
+
     if not tools.tool_names():
         logger.warning(
             "no tools enabled — add tools to agent.yaml or set AGENT_CONFIG "

agentlings-0.2.4/src/agentlings/tools/__init__.py

@@ -0,0 +1,10 @@
+"""Pluggable tool system with built-in bash and filesystem implementations."""
+
+from agentlings.tools.decorator import (
+    Tool,
+    ToolDefinitionError,
+    ToolInputError,
+    tool,
+)
+
+__all__ = ["Tool", "ToolDefinitionError", "ToolInputError", "tool"]

agentlings-0.2.4/src/agentlings/tools/decorator.py

@@ -0,0 +1,218 @@
+"""``@tool`` decorator: turn a typed Python function into a self-describing tool.
+
+A tool is a self-contained unit. The decorator infers everything the LLM needs
+from the function itself:
+
+- ``name``         from ``func.__name__`` (or override).
+- ``description``  from the docstring (or override).
+- ``input_schema`` derived from the parameter type annotations using Pydantic.
+
+Per-parameter descriptions and constraints attach via
+``Annotated[T, Field(description="...", ge=..., le=...)]`` — the idiomatic
+Python way and the single source of truth (no separate docstring parser).
+
+Sync and async functions are both supported; the resulting ``Tool`` exposes a
+unified ``async call(args)`` regardless.
+
+Output: ``tool.to_anthropic_dict()`` returns ``{name, description,
+input_schema}`` — exactly the shape the agent registry already passes to
+``messages.create(tools=...)``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from inspect import Parameter
+from typing import Any, Awaitable, Callable, Generic, TypeVar, get_type_hints, overload
+
+from pydantic import BaseModel, ValidationError, create_model
+
+R = TypeVar("R")
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class ToolDefinitionError(TypeError):
+    """Raised when a function cannot be turned into a tool.
+
+    Common causes: missing type annotations, ``*args``/``**kwargs``, or
+    positional-only parameters.
+    """
+
+
+class ToolInputError(ValueError):
+    """Raised when ``Tool.call`` receives arguments that fail schema validation.
+
+    Carries the underlying ``pydantic.ValidationError`` for callers that want
+    structured error reporting; ``str(e)`` is a human-readable summary.
+    """
+
+    def __init__(self, message: str, *, validation_error: ValidationError) -> None:
+        super().__init__(message)
+        self.validation_error = validation_error
+
+
+class Tool(Generic[R]):
+    """A typed, self-describing callable the agent can expose to the LLM.
+
+    Attributes:
+        func: The underlying user function.
+        name: The identifier the LLM uses to invoke the tool.
+        description: Human-readable description for the LLM.
+        input_schema: JSON Schema describing the tool's input parameters.
+        is_async: ``True`` when ``func`` is a coroutine function.
+    """
+
+    func: Callable[..., Any]
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    is_async: bool
+
+    def __init__(
+        self,
+        func: Callable[..., R] | Callable[..., Awaitable[R]],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        self.func = func
+        self.is_async = asyncio.iscoroutinefunction(func)
+        self.name = name or func.__name__
+
+        if description is not None:
+            self.description = description
+        elif func.__doc__:
+            self.description = inspect.cleandoc(func.__doc__)
+        else:
+            self.description = ""
+
+        self._input_model = _build_input_model(func)
+        self.input_schema = _clean_schema(
+            self._input_model.model_json_schema(),
+        )
+
+    async def call(self, args: dict[str, Any]) -> R:
+        """Validate ``args`` against the schema and invoke the tool.
+
+        Sync functions run on a worker thread so an async caller never blocks.
+        """
+        try:
+            validated = self._input_model.model_validate(args)
+        except ValidationError as e:
+            raise ToolInputError(
+                f"Invalid arguments for tool {self.name!r}: {e.error_count()} "
+                f"validation error(s).",
+                validation_error=e,
+            ) from e
+
+        kwargs = {k: getattr(validated, k) for k in self._input_model.model_fields}
+        if self.is_async:
+            return await self.func(**kwargs)  # type: ignore[no-any-return]
+        return await asyncio.to_thread(self.func, **kwargs)
+
+    def to_anthropic_dict(self) -> dict[str, Any]:
+        """Render the tool in the shape ``messages.create(tools=...)`` expects."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.input_schema,
+        }
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        kind = "async" if self.is_async else "sync"
+        return f"<Tool {self.name!r} ({kind})>"
+
+
+@overload
+def tool(func: F) -> Tool[Any]: ...
+
+
+@overload
+def tool(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[[F], Tool[Any]]: ...
+
+
+def tool(
+    func: Callable[..., Any] | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Tool[Any] | Callable[[Callable[..., Any]], Tool[Any]]:
+    """Wrap a function as a ``Tool``.
+
+    Usable bare or with overrides::
+
+        @tool
+        async def fetch(url: str) -> str:
+            ...
+
+        @tool(name="custom", description="…")
+        def other(...): ...
+    """
+
+    def _make(fn: Callable[..., Any]) -> Tool[Any]:
+        return Tool(fn, name=name, description=description)
+
+    if func is not None:
+        return _make(func)
+    return _make
+
+
+def _build_input_model(func: Callable[..., Any]) -> type[BaseModel]:
+    """Build a Pydantic model representing the function's keyword arguments.
+
+    Uses ``get_type_hints(..., include_extras=True)`` so ``Annotated`` metadata
+    (``pydantic.Field(...)``) is preserved and feeds ``model_json_schema``.
+    """
+    sig = inspect.signature(func)
+    try:
+        type_hints = get_type_hints(func, include_extras=True)
+    except NameError as e:
+        raise ToolDefinitionError(
+            f"Tool {func.__name__!r}: could not resolve type hints ({e}). "
+            f"Use ``from __future__ import annotations`` and ensure all referenced "
+            f"types are importable from the function's module."
+        ) from e
+
+    fields: dict[str, Any] = {}
+    for param_name, param in sig.parameters.items():
+        if param.kind == Parameter.VAR_POSITIONAL:
+            raise ToolDefinitionError(
+                f"Tool {func.__name__!r}: ``*{param_name}`` is not supported."
+            )
+        if param.kind == Parameter.VAR_KEYWORD:
+            raise ToolDefinitionError(
+                f"Tool {func.__name__!r}: ``**{param_name}`` is not supported."
+            )
+        if param.kind == Parameter.POSITIONAL_ONLY:
+            raise ToolDefinitionError(
+                f"Tool {func.__name__!r}: positional-only parameter "
+                f"{param_name!r} is not supported."
+            )
+        if param_name not in type_hints:
+            raise ToolDefinitionError(
+                f"Tool {func.__name__!r}: parameter {param_name!r} must have a "
+                f"type annotation."
+            )
+
+        annotation = type_hints[param_name]
+        default: Any = param.default if param.default is not Parameter.empty else ...
+        fields[param_name] = (annotation, default)
+
+    return create_model(f"{func.__name__}__InputSchema", **fields)
+
+
+def _clean_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Drop Pydantic's noisy top-level ``title`` field; keep everything else.
+
+    The top-level ``title`` is a Pydantic auto-generated identifier (e.g.
+    ``foo__InputSchema``) that clutters the LLM-facing schema. Nested ``title``
+    fields are left alone — Pydantic generates them for enum classes and
+    sub-models where they may carry meaning.
+    """
+    schema.pop("title", None)
+    return schema

agentlings-0.2.4/src/agentlings/tools/examples/__init__.py

@@ -0,0 +1,22 @@
+"""Reference tools demonstrating the ``@tool`` decorator surface.
+
+These are intentionally small and illustrative — they exist to show
+authors how to express common patterns:
+
+- ``echo``    — simplest possible tool, no I/O.
+- ``http_get``— async I/O + ``Annotated[..., Field(...)]`` per-param descriptions.
+- ``set_severity`` — string ``Enum`` parameter.
+- ``geocode`` — env-var-driven config + nested ``BaseModel`` parameter.
+
+They are not registered by default; agent configs opt in by name once the
+loader supports plugin discovery.
+"""
+
+from agentlings.tools.examples.echo import echo
+from agentlings.tools.examples.geocode import geocode
+from agentlings.tools.examples.http_get import http_get
+from agentlings.tools.examples.set_severity import set_severity
+
+EXAMPLE_TOOLS = [echo, http_get, set_severity, geocode]
+
+__all__ = ["EXAMPLE_TOOLS", "echo", "geocode", "http_get", "set_severity"]

agentlings-0.2.4/src/agentlings/tools/examples/echo.py

@@ -0,0 +1,14 @@
+"""Smallest possible tool — echoes its input back."""
+
+from __future__ import annotations
+
+from agentlings.tools import tool
+
+
+@tool
+def echo(message: str) -> str:
+    """Echo a message back unchanged.
+
+    Useful for sanity-checking that the tool plumbing is working end-to-end.
+    """
+    return message

agentlings-0.2.4/src/agentlings/tools/examples/geocode.py

@@ -0,0 +1,57 @@
+"""Env-var-driven config + nested ``BaseModel`` parameter.
+
+Demonstrates the recommended pattern for tools that need credentials or
+endpoint config: read them from the process environment inside the tool —
+the framework stays out of secret plumbing entirely.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Annotated
+
+import httpx
+from pydantic import BaseModel, Field
+
+from agentlings.tools import tool
+
+
+class Address(BaseModel):
+    """A postal address. Only the fields the geocoder needs are required."""
+
+    street: str
+    city: str
+    country: Annotated[str, Field(description="ISO 3166-1 alpha-2 country code, e.g. 'IE'.")]
+
+
+class Coordinates(BaseModel):
+    lat: float
+    lng: float
+
+
+@tool
+async def geocode(address: Address) -> Coordinates:
+    """Resolve a postal address to latitude/longitude.
+
+    Reads ``GEOCODE_API_KEY`` from the environment. Tools own their own
+    secret plumbing; the framework is intentionally not involved.
+    """
+    api_key = os.environ.get("GEOCODE_API_KEY")
+    if not api_key:
+        raise RuntimeError(
+            "GEOCODE_API_KEY is not set. Configure the tool's environment "
+            "before enabling it on an agent."
+        )
+
+    base_url = os.environ.get("GEOCODE_BASE_URL", "https://api.example.com/geocode")
+    params = {
+        "street": address.street,
+        "city": address.city,
+        "country": address.country,
+        "key": api_key,
+    }
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        response = await client.get(base_url, params=params)
+        response.raise_for_status()
+        payload = response.json()
+        return Coordinates(lat=payload["lat"], lng=payload["lng"])

agentlings-0.2.4/src/agentlings/tools/examples/http_get.py

@@ -0,0 +1,29 @@
+"""Async I/O tool with ``Annotated[..., Field(...)]`` parameter descriptions."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import httpx
+from pydantic import Field
+
+from agentlings.tools import tool
+
+
+@tool
+async def http_get(
+    url: Annotated[str, Field(description="Absolute URL to fetch (must be http/https).")],
+    timeout_seconds: Annotated[
+        float,
+        Field(ge=1.0, le=60.0, description="Per-request timeout in seconds."),
+    ] = 10.0,
+) -> str:
+    """Fetch a URL via HTTP GET and return the response body as text.
+
+    The tool follows redirects and raises if the response status is >= 400 so
+    the LLM sees a clear failure signal rather than a misleading empty body.
+    """
+    async with httpx.AsyncClient(follow_redirects=True, timeout=timeout_seconds) as client:
+        response = await client.get(url)
+        response.raise_for_status()
+        return response.text

agentlings-0.2.4/src/agentlings/tools/examples/set_severity.py

@@ -0,0 +1,25 @@
+"""String ``Enum`` parameter — the LLM sees a constrained set of values."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from agentlings.tools import tool
+
+
+class Severity(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+@tool
+def set_severity(severity: Severity, reason: str) -> str:
+    """Record an incident's severity level.
+
+    The model picks one of the enum values; the framework validates the input
+    before the function is invoked, so the function body can rely on
+    ``severity`` being a valid ``Severity``.
+    """
+    return f"severity={severity.value} reason={reason}"

agentlings-0.2.4/src/agentlings/tools/loader.py

@@ -0,0 +1,126 @@
+"""Folder-scan loader for ``@tool``-decorated user tools.
+
+Discovery contract:
+
+- The framework scans ``AGENT_TOOLS_DIR`` (a directory) for ``*.py`` files.
+- Each file is imported as an isolated module under the synthetic package
+  ``agentling_user_tools.<filename_stem>``; the directory is *not* added to
+  ``sys.path`` so user tools cannot accidentally shadow installed packages.
+- Files whose name begins with ``_`` are skipped (private/helpers).
+- Every module-level attribute that is a ``Tool`` instance is registered
+  with the supplied ``ToolRegistry``.
+- Import failures and registration failures are logged and skipped — one
+  broken tool must not crash the agent.
+
+The loader is intentionally permissive about *what* a user file contains:
+it only registers ``Tool`` instances and ignores everything else, so a file
+can define helpers, classes, env-var reads, or whatever the tool author
+needs.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from agentlings.tools.decorator import Tool
+
+if TYPE_CHECKING:
+    from agentlings.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+_USER_TOOLS_PACKAGE = "agentling_user_tools"
+
+
+def load_tools_from_directory(
+    directory: Path,
+    registry: "ToolRegistry",
+) -> list[str]:
+    """Scan ``directory`` and register every ``Tool`` instance found.
+
+    Args:
+        directory: Filesystem path to scan. ``.py`` files at the top level
+            are imported (no recursion, no sub-packages).
+        registry: The ``ToolRegistry`` to register discovered tools into.
+
+    Returns:
+        The names of tools that were successfully registered. The list is in
+        directory-walk order, which the caller may sort if it wants stable
+        output.
+
+    The function never raises for content issues: missing directory, broken
+    imports, and registration failures are logged and the scan continues. It
+    only raises for argument-shape problems (wrong types passed in).
+    """
+    if not directory.exists():
+        logger.info(
+            "tool directory %s does not exist — skipping scan", directory
+        )
+        return []
+    if not directory.is_dir():
+        logger.warning(
+            "AGENT_TOOLS_DIR=%s is not a directory — skipping scan", directory
+        )
+        return []
+
+    registered: list[str] = []
+    for path in sorted(directory.iterdir()):
+        if not path.is_file():
+            continue
+        if path.suffix != ".py":
+            continue
+        if path.stem.startswith("_"):
+            logger.debug("skipping private tool file: %s", path)
+            continue
+
+        module_name = f"{_USER_TOOLS_PACKAGE}.{path.stem}"
+        try:
+            module = _import_isolated_module(module_name, path)
+        except Exception:  # noqa: BLE001 — log and continue to next file
+            logger.exception("failed to import tool file %s", path)
+            continue
+
+        for attr_name in dir(module):
+            attr = getattr(module, attr_name)
+            if not isinstance(attr, Tool):
+                continue
+            try:
+                registry.register_tool_object(attr)
+                registered.append(attr.name)
+            except Exception:  # noqa: BLE001
+                logger.exception(
+                    "failed to register tool %r from %s", attr.name, path
+                )
+
+    if registered:
+        logger.info(
+            "loaded %d user tool(s) from %s: %s",
+            len(registered),
+            directory,
+            sorted(registered),
+        )
+    else:
+        logger.info("no user tools registered from %s", directory)
+
+    return registered
+
+
+def _import_isolated_module(module_name: str, path: Path) -> object:
+    """Import a single file as ``module_name`` without polluting ``sys.path``.
+
+    Uses ``importlib.util.spec_from_file_location`` so the file is imported
+    by absolute path; the parent directory is never injected into the
+    interpreter's import paths.
+    """
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(
+            f"could not build import spec for {path} as {module_name}"
+        )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module

{agentlings-0.2.2 → agentlings-0.2.4}/src/agentlings/tools/registry.py

@@ -5,7 +5,10 @@ from __future__ import annotations
 import asyncio
 import logging
 from dataclasses import dataclass
-from typing import Any, Callable
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from agentlings.tools.decorator import Tool
 
 logger = logging.getLogger(__name__)
 
@@ -64,6 +67,35 @@ class ToolRegistry:
         )
         logger.info("registered tool: %s", name)
 
+    def register_tool_object(self, tool: "Tool[Any]") -> None:
+        """Register a ``@tool``-decorated ``Tool`` instance.
+
+        Bridges the decorator surface to the existing registry shape: the
+        tool's input schema and metadata are extracted via
+        ``to_anthropic_dict()``; execution is wrapped so a unified
+        ``ToolResult`` is returned regardless of the underlying function's
+        return type.
+
+        Args:
+            tool: The ``Tool`` produced by the ``@tool`` decorator.
+        """
+        async def _execute(**kwargs: Any) -> ToolResult:
+            try:
+                output = await tool.call(kwargs)
+            except Exception as e:  # noqa: BLE001 — surface to LLM, not crash
+                return ToolResult(
+                    output=f"Tool {tool.name} failed: {e}",
+                    is_error=True,
+                )
+            return ToolResult(output=str(output), is_error=False)
+
+        self.register(
+            name=tool.name,
+            description=tool.description,
+            input_schema=tool.input_schema,
+            execute_fn=_execute,
+        )
+
     def list_schemas(self) -> list[dict[str, Any]]:
         """Return tool schemas in the format expected by the Anthropic API."""
         return [