ellements 0.2.0__py3-none-any.whl

ellements/core/tools/executor.py

@@ -0,0 +1,48 @@
+"""Tool-call runtime helpers used by :class:`~ellements.core.LLMClient`.
+
+The executor type and the result-stringification helper live here
+together because they are always used in concert by the tool-calling
+loop.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+
+from pydantic import BaseModel
+
+ToolExecutor = Callable[[str, dict[str, Any]], Awaitable[str]]
+"""Async ``(tool_name, arguments) -> result_string`` runtime callable."""
+
+
+def stringify_tool_result(result: Any) -> str:
+    """Convert arbitrary tool output into a stable string payload."""
+    if result is None:
+        return ""
+    if isinstance(result, str):
+        return result
+    if isinstance(result, bytes):
+        return result.decode("utf-8", errors="replace")
+    if isinstance(result, BaseModel):
+        return result.model_dump_json()
+    if isinstance(result, Mapping):
+        return json.dumps(dict(result), default=_json_default)
+    if isinstance(result, (list, tuple, set)):
+        return json.dumps(list(result), default=_json_default)
+    try:
+        return json.dumps(result, default=_json_default)
+    except TypeError:
+        return str(result)
+
+
+def _json_default(value: Any) -> Any:
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, bytes):
+        return value.decode("utf-8", errors="replace")
+    return str(value)
+
+
+__all__ = ["ToolExecutor", "stringify_tool_result"]

ellements/core/tools/protocol.py

@@ -0,0 +1,36 @@
+"""The :class:`Tool` Protocol — what every tool looks like to ellements.
+
+A tool is any object that exposes a stable name, a description, a
+provider-neutral JSON Schema for its parameters, and an awaitable
+``invoke`` method that runs it.
+
+Anything matching this shape is a tool. Inheritance is not required.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Tool(Protocol):
+    """Provider-neutral tool surface consumed by every backend.
+
+    Implementations must expose:
+
+    - ``name`` — stable identifier (matches the function name the LLM emits).
+    - ``description`` — human-readable description shown to the model.
+    - ``params_json_schema`` — JSON Schema (Draft-2020-12 compatible) for
+      the parameters object. Provider-specific dialects are produced
+      from this by :class:`~ellements.core.tools.ToolDialect`.
+    - ``invoke`` — async invocation accepting keyword arguments.
+    """
+
+    name: str
+    description: str
+    params_json_schema: dict[str, Any]
+
+    async def invoke(self, **kwargs: Any) -> Any: ...
+
+
+__all__ = ["Tool"]

ellements/core/tools/records.py

@@ -0,0 +1,28 @@
+"""Result records for multi-turn tool-calling completions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ToolCallRecord(BaseModel):
+    """One tool invocation made during a multi-turn completion."""
+
+    name: str = Field(description="Tool/function name that was invoked")
+    arguments: dict[str, Any] = Field(description="Arguments passed to the tool")
+    result: str = Field(description="String result returned by the tool executor")
+
+
+class ToolCallResponse(BaseModel):
+    """Final response of a multi-turn completion with tool calling."""
+
+    content: str = Field(description="Final text response from the model")
+    tool_calls: list[ToolCallRecord] = Field(
+        default_factory=list,
+        description="Ordered log of every tool invocation during the session",
+    )
+
+
+__all__ = ["ToolCallRecord", "ToolCallResponse"]

ellements/core/tools/registry.py

@@ -0,0 +1,205 @@
+"""The :class:`ToolRegistry` — a typed, composable tool collection.
+
+Every tool factory should return a ``ToolRegistry``. Apps compose
+registries with :meth:`ToolRegistry.merge` (or with the
+``Mapping`` interface — ``{**r1, **r2}`` and ``dict.update(r)`` both
+work because :class:`ToolRegistry` is a read-only ``Mapping[str,
+ToolSpec]``). LLM clients call :meth:`ToolRegistry.to_dialect` to
+produce the provider-specific wire format, and
+:meth:`ToolRegistry.executor` to obtain the async runtime.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, Iterator, Mapping
+from typing import Any
+
+from .protocol import Tool
+from .simple import SimpleTool
+from .spec import ToolSpec
+
+ToolInput = Tool | ToolSpec | Callable[..., Any]
+"""Anything accepted by :meth:`ToolRegistry.register`."""
+
+ToolExecutorFn = Callable[[str, dict[str, Any]], Awaitable[str]]
+"""Async ``(tool_name, args) -> result_string`` runtime executor."""
+
+
+class ToolRegistry(Mapping[str, ToolSpec]):
+    """An ordered, named collection of tools.
+
+    The registry preserves insertion order so the order of tools shown
+    to a model is deterministic across runs. It implements the
+    read-only :class:`~collections.abc.Mapping` interface, which means
+    every standard dict idiom works without surprises:
+
+    >>> combined = {**search_tools(), **crawler_tools()}
+    >>> for name in registry:
+    ...     spec = registry[name]
+    """
+
+    def __init__(self, tools: Iterable[ToolInput] | Mapping[str, ToolInput] | None = None) -> None:
+        self._specs: dict[str, ToolSpec] = {}
+        if tools is None:
+            return
+        if isinstance(tools, Mapping):
+            for name, tool in tools.items():
+                self.register(tool, name=name)
+        else:
+            for tool in tools:
+                self.register(tool)
+
+    # ── registration ─────────────────────────────────────────────────
+
+    def register(
+        self,
+        tool: ToolInput,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ToolSpec:
+        """Add *tool* to the registry and return the materialized spec.
+
+        Args:
+            tool: A :class:`Tool`, :class:`ToolSpec`, or plain callable.
+            name: Override the resulting tool name.
+            description: Override the description.
+
+        Returns:
+            The :class:`ToolSpec` that was registered.
+
+        Raises:
+            ValueError: If a tool with the same name already exists.
+        """
+        spec = self._to_spec(tool, name=name, description=description)
+        if spec.name in self._specs:
+            raise ValueError(f"Tool {spec.name!r} is already registered.")
+        self._specs[spec.name] = spec
+        return spec
+
+    def merge(self, other: Mapping[str, ToolInput]) -> ToolRegistry:
+        """Return a new registry containing this and *other*.
+
+        *other* may be another :class:`ToolRegistry` or any
+        ``{name: tool}`` mapping.
+
+        Raises:
+            ValueError: If the two registries share a tool name.
+        """
+        other_specs: dict[str, ToolSpec]
+        if isinstance(other, ToolRegistry):
+            other_specs = dict(other._specs)
+        else:
+            other_specs = {
+                name: self._to_spec(tool, name=name, description=None)
+                for name, tool in other.items()
+            }
+        overlap = set(self._specs) & set(other_specs)
+        if overlap:
+            raise ValueError(
+                f"Cannot merge registries: duplicate tool names {sorted(overlap)}."
+            )
+        merged = ToolRegistry()
+        merged._specs.update(self._specs)
+        merged._specs.update(other_specs)
+        return merged
+
+    # ── Mapping[str, ToolSpec] protocol ──────────────────────────────
+
+    def __len__(self) -> int:
+        return len(self._specs)
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._specs)
+
+    def __contains__(self, name: object) -> bool:
+        return isinstance(name, str) and name in self._specs
+
+    def __getitem__(self, name: str) -> ToolSpec:
+        return self._specs[name]
+
+    # ── consumption ──────────────────────────────────────────────────
+
+    def to_dialect(self, dialect: Any) -> list[dict[str, Any]]:
+        """Render every tool as a provider-specific definition.
+
+        Args:
+            dialect: Any object with an ``emit(spec) -> dict`` method.
+
+        Returns:
+            The list of provider-specific tool definitions in
+            registration order.
+        """
+        return [dialect.emit(spec) for spec in self._specs.values()]
+
+    def executor(self) -> ToolExecutorFn:
+        """Return an async ``(name, args) -> result_string`` executor."""
+        from .executor import stringify_tool_result
+
+        specs = dict(self._specs)
+
+        async def execute(tool_name: str, arguments: dict[str, Any]) -> str:
+            spec = specs.get(tool_name)
+            if spec is None:
+                available = ", ".join(sorted(specs)) or "(none)"
+                raise KeyError(
+                    f"Unknown tool {tool_name!r}. Available: {available}."
+                )
+            result = await spec.invoke(**arguments)
+            return stringify_tool_result(result)
+
+        return execute
+
+    # ── construction helpers ─────────────────────────────────────────
+
+    @staticmethod
+    def _to_spec(
+        tool: ToolInput,
+        *,
+        name: str | None,
+        description: str | None,
+    ) -> ToolSpec:
+        if isinstance(tool, ToolSpec):
+            if name is None and description is None:
+                return tool
+            return ToolSpec(
+                name=name or tool.name,
+                description=description or tool.description,
+                params_json_schema=tool.params_json_schema,
+                invoke=tool.invoke,
+            )
+        if isinstance(tool, SimpleTool):
+            spec = tool.to_spec()
+            if name is None and description is None:
+                return spec
+            return ToolSpec(
+                name=name or spec.name,
+                description=description or spec.description,
+                params_json_schema=spec.params_json_schema,
+                invoke=spec.invoke,
+            )
+        if isinstance(tool, Tool):
+            return ToolSpec(
+                name=name or tool.name,
+                description=description or tool.description,
+                params_json_schema=tool.params_json_schema,
+                invoke=tool.invoke,
+            )
+        if callable(tool):
+            return SimpleTool(tool, name=name, description=description).to_spec()
+        raise TypeError(
+            f"Cannot register {type(tool).__name__}; expected Tool, ToolSpec, or callable."
+        )
+
+    @classmethod
+    def from_mapping(cls, tools: Mapping[str, ToolInput]) -> ToolRegistry:
+        """Build a registry from a ``{name: tool}`` mapping."""
+        return cls(tools)
+
+    @classmethod
+    def from_callables(cls, tools: Iterable[Callable[..., Any]]) -> ToolRegistry:
+        """Build a registry from an iterable of plain callables."""
+        return cls(tools)
+
+
+__all__ = ["ToolExecutorFn", "ToolInput", "ToolRegistry"]

ellements/core/tools/schemas.py

@@ -0,0 +1,80 @@
+"""JSON Schema generation from Python callable signatures.
+
+A callable's parameters are introspected via :mod:`inspect` and type
+hints. Pydantic ``create_model`` then produces the canonical JSON Schema
+that every dialect re-emits in its own wire format.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel, create_model
+
+
+def resolve_callable_signature(func: Callable[..., Any]) -> inspect.Signature:
+    """Resolve postponed annotations in *func*'s signature when possible."""
+    signature = inspect.signature(func)
+    resolved_hints = resolve_type_hints(func)
+    if not resolved_hints:
+        return signature
+    parameters = [
+        parameter.replace(annotation=resolved_hints.get(parameter.name, parameter.annotation))
+        for parameter in signature.parameters.values()
+    ]
+    return signature.replace(
+        parameters=parameters,
+        return_annotation=resolved_hints.get("return", signature.return_annotation),
+    )
+
+
+def resolve_type_hints(func: Callable[..., Any]) -> dict[str, Any]:
+    """Best-effort ``get_type_hints`` that never raises."""
+    try:
+        return get_type_hints(func)
+    except Exception:
+        return {}
+
+
+def json_schema_for_callable(func: Callable[..., Any], *, tool_name: str) -> dict[str, Any]:
+    """Build a JSON Schema for *func*'s keyword-bound parameters.
+
+    Args:
+        func: The callable whose signature is converted to a schema.
+        tool_name: Stable tool name used to derive the Pydantic model
+            name (purely cosmetic in the schema).
+
+    Returns:
+        A JSON Schema dictionary describing the parameters object.
+    """
+    fields: dict[str, tuple[Any, Any]] = {}
+    signature = resolve_callable_signature(func)
+    resolved_hints = resolve_type_hints(func)
+
+    for parameter in signature.parameters.values():
+        if parameter.kind in {
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        }:
+            continue
+        annotation = resolved_hints.get(parameter.name, parameter.annotation)
+        if annotation is inspect.Signature.empty:
+            annotation = Any
+        default = parameter.default
+        if default is inspect.Signature.empty:
+            default = ...
+        fields[parameter.name] = (annotation, default)
+
+    model_name = f"{tool_name.title().replace('_', '')}Params"
+    model: type[BaseModel] = create_model(model_name, **fields)  # type: ignore[call-overload]
+    schema: dict[str, Any] = model.model_json_schema()
+    return schema
+
+
+__all__ = [
+    "json_schema_for_callable",
+    "resolve_callable_signature",
+    "resolve_type_hints",
+]

ellements/core/tools/simple.py

@@ -0,0 +1,119 @@
+"""The :class:`SimpleTool` convenience builder.
+
+``SimpleTool`` wraps an arbitrary Python callable so it satisfies the
+:class:`~ellements.core.tools.Tool` Protocol and can be materialized as
+a :class:`~ellements.core.tools.ToolSpec`.
+
+Construction is cheap; the JSON Schema is computed lazily on first
+access and cached. The instance is also callable, so simple in-process
+test harnesses can drive it without going through the schema path.
+
+The module also exposes :func:`bind_json_invoker`, a helper used by
+agent backends that bridge between a provider's JSON-payload calling
+convention and a Python callable's positional/keyword binding.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Any
+
+from .schemas import json_schema_for_callable, resolve_callable_signature
+from .spec import ToolSpec
+
+
+class SimpleTool:
+    """Adapt a callable as a :class:`~ellements.core.tools.Tool`.
+
+    Args:
+        func: The callable to expose as a tool.
+        name: Override the tool name. Defaults to ``func.__name__``.
+        description: Override the description. Defaults to the
+            callable's docstring.
+    """
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> None:
+        self.func = func
+        self.name: str = name or getattr(func, "__name__", None) or "tool"
+        self.description: str = description or inspect.getdoc(func) or self.name
+        self.__name__ = self.name
+        self.__doc__ = self.description
+        self.__signature__ = resolve_callable_signature(func)
+        self._params_json_schema: dict[str, Any] | None = None
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        return self.func(*args, **kwargs)
+
+    async def invoke(self, *args: Any, **kwargs: Any) -> Any:
+        """Run the underlying callable, awaiting it if needed."""
+        result = self.func(*args, **kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+
+    async def on_invoke_tool(self, _context: Any, input_json: str) -> Any:
+        """Invoke the tool from a JSON payload (OpenAI Agents SDK shape)."""
+        return await _invoke_from_json(self.invoke, input_json)
+
+    @property
+    def params_json_schema(self) -> dict[str, Any]:
+        """JSON Schema of the wrapped callable's parameters (cached)."""
+        if self._params_json_schema is None:
+            self._params_json_schema = json_schema_for_callable(self.func, tool_name=self.name)
+        return self._params_json_schema
+
+    def to_spec(self) -> ToolSpec:
+        """Materialize this tool as a :class:`ToolSpec`."""
+        return ToolSpec(
+            name=self.name,
+            description=self.description,
+            params_json_schema=self.params_json_schema,
+            invoke=self.invoke,
+        )
+
+
+def bind_json_invoker(
+    invoke: Callable[..., Awaitable[Any]],
+) -> Callable[[Any, str], Awaitable[Any]]:
+    """Wrap an awaitable to accept an OpenAI-Agents-style JSON payload.
+
+    Many agent SDKs hand the tool a single JSON string and expect the
+    adapter to parse it into ``*args``/``**kwargs``. This helper does
+    that translation once so adapters don't reinvent it.
+    """
+
+    async def on_invoke(_context: Any, input_json: str) -> Any:
+        return await _invoke_from_json(invoke, input_json)
+
+    return on_invoke
+
+
+async def _invoke_from_json(
+    invoke: Callable[..., Awaitable[Any]],
+    input_json: str,
+) -> Any:
+    text = str(input_json or "").strip()
+    if not text:
+        return await invoke()
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        return await invoke(text)
+    if isinstance(payload, Mapping):
+        return await invoke(**dict(payload))
+    if isinstance(payload, list):
+        return await invoke(*payload)
+    if payload is None:
+        return await invoke()
+    return await invoke(payload)
+
+
+__all__ = ["SimpleTool", "bind_json_invoker"]

ellements/core/tools/spec.py

@@ -0,0 +1,33 @@
+"""The canonical in-memory tool representation: :class:`ToolSpec`.
+
+Every tool — built from a callable, declared via a builder, or adapted
+from an external system — is converted to a ``ToolSpec`` before it
+reaches an LLM provider or an agent runtime. This is the seam every
+dialect and backend adapter speaks to.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(slots=True, frozen=True)
+class ToolSpec:
+    """Provider-neutral canonical tool record.
+
+    Args:
+        name: Stable identifier (the function name the LLM emits).
+        description: Human-readable description shown to the model.
+        params_json_schema: JSON Schema for the keyword parameters.
+        invoke: Async callable executing the tool given keyword args.
+    """
+
+    name: str
+    description: str
+    params_json_schema: dict[str, Any]
+    invoke: Callable[..., Awaitable[Any]]
+
+
+__all__ = ["ToolSpec"]

ellements/domain_specific/__init__.py

@@ -0,0 +1,7 @@
+"""Domain-specific packages for vertical ellements functionality.
+
+Install the matching optional extras before importing a concrete domain
+subpackage, for example ``ellements[finance]`` for Yahoo Finance tools.
+"""
+
+__all__ = ["finance"]