Source code for sim_platform.agents.tools.client.base

"""Tool interfaces for local computation and remote platform operations."""

from __future__ import annotations

from abc import ABC, abstractmethod
from inspect import signature, Parameter
from typing import Any, Dict, Optional, Protocol, Tuple

from sim_platform.domain.json_values import copy_json
from sim_platform.domain.models import ContractError
from ..protocol.errors import ToolError

ToolResponse = Dict[str, Any]


class ToolClient(Protocol):
    """What a platform tool proxy needs: the Agent client's call_tool."""

    def call_tool(self, name: str, arguments: dict) -> ToolResponse:
        """Send a tool operation under the client's active work identity."""
        ...


def text(description: str) -> Dict[str, Any]:
    """JSON schema for a string argument."""
    return dict(type='string', description=description)


def counter(description: str) -> Dict[str, Any]:
    """JSON schema for a canonical decimal counter string."""
    return dict(type='string', pattern=r'^(0|[1-9][0-9]*)$', description=description)


def integer(description: str, minimum: int = 1, maximum: Optional[int] = None) -> Dict[str, Any]:
    """JSON schema for an integer argument with bounds."""
    value: Dict[str, Any] = dict(type='integer', minimum=minimum, description=description)
    if maximum is not None:
        value['maximum'] = maximum
    return value


SYMBOL = text('The experiment stock symbol, such as AAPL.')
CURSOR = text('A next_cursor returned by this tool; omit on the first page.')
LIMIT = integer('Maximum items in this page.')


[docs] class Tool(ABC): """Keep one tool's name, description, arguments and callable behavior together. Subclasses implement a typed run() method. Required arguments come from that signature; optional arguments have Python defaults. Both direct code and model calls use run(). Local tools execute in the Agent process and return finite JSON values. They do not need a platform client or a platform result envelope. """ name: str description: str parameters: dict = {} category = 'read' ends_work = False
[docs] @classmethod def required_arguments(cls) -> Tuple[str, ...]: return tuple( name for name, value in signature(cls.run).parameters.items() if name != 'self' and value.default is Parameter.empty )
[docs] @classmethod def optional_arguments(cls) -> Tuple[str, ...]: return tuple( name for name, value in signature(cls.run).parameters.items() if name != 'self' and value.default is not Parameter.empty )
@property def function_name(self) -> str: return self.name.replace('.', '_')
[docs] def input_schema(self, limits: dict) -> dict: """Describe this tool's arguments with the experiment's granted bounds.""" properties = copy_json(self.parameters) return dict( type='object', properties=properties, required=list(self.required_arguments()), additionalProperties=False, )
[docs] def invoke(self, arguments: dict) -> Any: """Call run() with model-supplied arguments, rejecting missing or extra fields.""" if type(arguments) is not dict: raise ToolError('INVALID_SCHEMA', 'tool arguments must be an object') if any(value is None for value in arguments.values()): raise ToolError('INVALID_SCHEMA', 'omit optional tool arguments instead of using null') try: signature(self.run).bind(**arguments) except TypeError as exc: raise ToolError('INVALID_SCHEMA', 'invalid arguments for ' + self.name) from exc try: result = self.run(**arguments) except ContractError: raise except (ValueError, TypeError, ArithmeticError) as exc: raise ToolError('TOOL_EXECUTION_FAILED', 'tool failed: ' + self.name) from exc try: return copy_json(result) except ContractError as exc: raise ToolError('TOOL_RESULT_INVALID', 'tool must return finite JSON') from exc
[docs] @abstractmethod def run(self, *positional: Any, **arguments: Any) -> Any: """Execute locally and return a JSON value, such as a number, list or object.""" raise NotImplementedError
class PlatformTool(Tool): """Proxy one granted platform operation through the existing Agent client. The server validates permissions, time boundaries and financial rules. A proxy does not read platform storage or execute financial logic in the Agent process. """ # Mutable account/state and financial operations require the financial owner. execution_route = 'owner' def __init__(self, client: ToolClient) -> None: self.client = client def input_schema(self, limits: dict) -> dict: schema = super().input_schema(limits) for field, limit in ( ('limit', 'page_items'), ('order_limit', 'page_items'), ('levels', 'depth_levels'), ): if field in schema['properties']: schema['properties'][field]['maximum'] = limits[limit] return schema