synth-ai 0.2.14__py3-none-any.whl → 0.4.4__py3-none-any.whl

synth_ai/environments/environment/tools/__init__.py

@@ -1,200 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any
-
-from pydantic import BaseModel, Field
-
-
-class EnvToolCall(BaseModel):
-    """
-    Represents an agent-requested call to an environment tool.
-
-    This class encapsulates an action that an AI agent wants to perform
-    in an environment. Tool calls consist of a tool name and a dictionary
-    of arguments that will be passed to the tool for execution.
-
-    The tool call system provides a standardized way for agents to interact
-    with environments, making it easy to:
-    - Validate agent actions before execution
-    - Log and trace agent behavior
-    - Implement complex multi-step actions
-    - Handle errors and provide feedback
-
-    Attributes:
-        tool: The name of the tool to invoke (must be registered in environment)
-        args: Arguments to pass to the tool, with argument names as keys
-
-    Example:
-        >>> # Simple movement action
-        >>> move_call = EnvToolCall(tool="move", args={"direction": "north"})
-
-        >>> # Complex action with multiple parameters
-        >>> craft_call = EnvToolCall(
-        ...     tool="craft_item",
-        ...     args={"item": "sword", "materials": ["iron", "wood"], "quantity": 1}
-        ... )
-
-        >>> # Action with no arguments
-        >>> look_call = EnvToolCall(tool="look", args={})
-    """
-
-    tool: str
-    args: dict[str, Any] = Field(default_factory=dict)
-
-
-class ToolResult(BaseModel):
-    """
-    Represents the result of executing an environment tool.
-
-    This class standardizes the response format for all tool executions,
-    providing a consistent interface for success/failure status, return
-    values, and error information. This makes it easy for agents and
-    environment systems to handle tool execution results uniformly.
-
-    Attributes:
-        ok: Whether the tool execution was successful
-        payload: The return value from the tool (None if failed or no return value)
-        error: Error message if execution failed (None if successful)
-
-    Example:
-        >>> # Successful tool execution
-        >>> success_result = ToolResult(
-        ...     ok=True,
-        ...     payload={"new_position": [5, 3], "items_collected": ["key"]},
-        ...     error=None
-        ... )
-
-        >>> # Failed tool execution
-        >>> error_result = ToolResult(
-        ...     ok=False,
-        ...     payload=None,
-        ...     error="Cannot move north: wall blocking path"
-        ... )
-
-        >>> # Success with no return value
-        >>> simple_success = ToolResult(ok=True)
-    """
-
-    ok: bool
-    payload: Any | None = None
-    error: str | None = None
-
-
-class AbstractTool(ABC):
-    """
-    Abstract base class for all environment tools.
-
-    Tools are the primary mechanism for agents to interact with environments.
-    Each tool represents a specific action or capability that an agent can
-    invoke, such as moving, picking up items, or examining objects.
-
-    Tools define their own call and result schemas using Pydantic models,
-    enabling automatic validation and documentation generation. This ensures
-    that agents provide valid inputs and receive structured outputs.
-
-    The tool system supports:
-    - Type-safe argument validation
-    - Automatic error handling and reporting
-    - Consistent result formatting
-    - Dynamic tool registration and discovery
-
-    Attributes:
-        name: Unique identifier for this tool (used in EnvToolCall.tool)
-        call_schema: Pydantic model defining valid arguments for this tool
-        result_schema: Pydantic model defining the structure of results
-
-    Example:
-        >>> class MoveTool(AbstractTool):
-        ...     name = "move"
-        ...     call_schema = MoveArgs  # Pydantic model with 'direction' field
-        ...
-        ...     async def __call__(self, call: EnvToolCall) -> ToolResult:
-        ...         direction = call.args['direction']
-        ...         # Perform movement logic
-        ...         if valid_move:
-        ...             return ToolResult(ok=True, payload=new_position)
-        ...         else:
-        ...             return ToolResult(ok=False, error="Invalid move")
-
-        >>> # Register and use the tool
-        >>> move_tool = MoveTool()
-        >>> register_tool(move_tool)
-        >>> call = EnvToolCall(tool="move", args={"direction": "north"})
-        >>> result = await move_tool(call)
-    """
-
-    name: str
-    call_schema: type[BaseModel]
-    result_schema: type[BaseModel] = ToolResult
-
-    @abstractmethod
-    async def __call__(self, call: EnvToolCall) -> ToolResult:
-        """
-        Execute the tool with the given tool call.
-
-        This method contains the core logic for the tool's functionality.
-        It should:
-        1. Validate the tool call arguments (using call_schema)
-        2. Perform the requested action
-        3. Return a ToolResult with appropriate success/failure status
-
-        Args:
-            call: The tool call containing the tool name and arguments
-
-        Returns:
-            ToolResult: Result of tool execution with success status,
-                payload data, and any error messages
-
-        Raises:
-            ValidationError: If call arguments don't match call_schema
-            EnvironmentError: If tool execution fails due to environment state
-
-        Example:
-            >>> call = EnvToolCall(tool="move", args={"direction": "east"})
-            >>> result = await tool(call)
-            >>> if result.ok:
-            ...     print(f"Moved to: {result.payload['position']}")
-            ... else:
-            ...     print(f"Move failed: {result.error}")
-        """
-        ...
-
-
-TOOL_REGISTRY: dict[str, AbstractTool] = {}
-
-
-def register_tool(tool: AbstractTool) -> None:
-    """
-    Register a tool instance for use in environments.
-
-    This function adds a tool to the global registry, making it available
-    for environments to use when processing agent tool calls. Tools must
-    be registered before they can be invoked by agents.
-
-    The registry uses the tool's name attribute as the key, so tool names
-    must be unique across all registered tools.
-
-    Args:
-        tool: The tool instance to register. Must have a unique name.
-
-    Raises:
-        ValueError: If a tool with the same name is already registered
-        TypeError: If tool is not an instance of AbstractTool
-
-    Example:
-        >>> class LookTool(AbstractTool):
-        ...     name = "look"
-        ...     # ... implementation
-
-        >>> look_tool = LookTool()
-        >>> register_tool(look_tool)
-        >>>
-        >>> # Now agents can use: EnvToolCall(tool="look", args={})
-
-    Note:
-        Tools are typically registered during environment initialization
-        or module import. Once registered, tools remain available for
-        the duration of the application session.
-    """
-    TOOL_REGISTRY[tool.name] = tool

synth_ai/environments/examples/__init__.py

@@ -1 +0,0 @@
-"""Environment examples and demos."""

synth_ai/environments/examples/bandit/__init__.py

@@ -1,33 +0,0 @@
-"""Multi-armed bandit example environment."""
-
-from .engine import (
-    BanditEngine,
-    BanditEngineSnapshot,
-    BanditPrivateState,
-    BanditPublicState,
-    SynthBanditCheckpointObservationCallable,
-    SynthBanditObservationCallable,
-)
-from .environment import BanditActionInput, BanditEnvironment, BanditInteractTool
-from .taskset import (
-    BanditTaskInstance,
-    BanditTaskInstanceMetadata,
-    create_bandit_taskset,
-    taskset,
-)
-
-__all__ = [
-    "BanditEngine",
-    "BanditPublicState",
-    "BanditPrivateState",
-    "BanditEngineSnapshot",
-    "SynthBanditObservationCallable",
-    "SynthBanditCheckpointObservationCallable",
-    "BanditEnvironment",
-    "BanditInteractTool",
-    "BanditActionInput",
-    "BanditTaskInstance",
-    "BanditTaskInstanceMetadata",
-    "create_bandit_taskset",
-    "taskset",
-]

synth_ai/environments/examples/bandit/engine.py

@@ -1,302 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any
-
-import numpy as np
-
-from synth_ai.environments.environment.shared_engine import (
-    GetObservationCallable,
-    InternalObservation,
-)
-from synth_ai.environments.reproducibility.core import IReproducibleEngine
-from synth_ai.environments.stateful.engine import StatefulEngine, StatefulEngineSnapshot
-from synth_ai.environments.tasks.core import TaskInstance
-
-
-@dataclass
-class BanditPublicState:
-    arm_count: int
-    step_count: int
-    max_steps: int
-    last_arm: int | None
-    last_reward: float | None
-    cumulative_reward: float
-    reward_history: list[float]
-    arm_pull_counts: list[int]
-    terminated: bool
-    status: str
-
-    @property
-    def steps_remaining(self) -> int:
-        return max(0, self.max_steps - self.step_count)
-
-    @property
-    def average_reward(self) -> float:
-        return self.cumulative_reward / self.step_count if self.step_count else 0.0
-
-
-@dataclass
-class BanditPrivateState:
-    reward_last: float
-    total_reward: float
-    terminated: bool
-    truncated: bool
-    true_expected_rewards: list[float]
-    step_count: int
-
-
-@dataclass
-class BanditEngineSnapshot(StatefulEngineSnapshot):
-    task_instance_dict: dict[str, Any]
-    engine_snapshot: dict[str, Any]
-
-
-class BanditEngine(StatefulEngine, IReproducibleEngine):
-    def __init__(self, task_instance: TaskInstance):
-        self.task_instance = task_instance
-
-        metadata = getattr(task_instance, "metadata", None)
-        self.bandit_type: str = getattr(metadata, "bandit_type", "bernoulli")
-        self.max_steps: int = int(getattr(metadata, "max_steps", 100))
-        self.seed: int | None = getattr(metadata, "seed", None)
-
-        self.arm_probabilities: list[float] | None = None
-        self.arm_means: list[float] | None = None
-        self.arm_stds: list[float] | None = None
-
-        if self.bandit_type.lower() == "bernoulli":
-            probs = list(getattr(metadata, "arm_probabilities", []) or [])
-            if not probs:
-                probs = [0.1, 0.5, 0.9]
-            self.arm_probabilities = [float(p) for p in probs]
-            self.true_expected_rewards = self.arm_probabilities.copy()
-        elif self.bandit_type.lower() == "gaussian":
-            means = list(getattr(metadata, "arm_means", []) or [])
-            if not means:
-                means = [0.0, 0.5, 1.0]
-            stds = getattr(metadata, "arm_stds", None)
-            if stds is None:
-                stds_list = [0.1] * len(means)
-            elif isinstance(stds, int | float):
-                stds_list = [float(stds)] * len(means)
-            else:
-                stds_list = [float(s) for s in stds]
-            if len(stds_list) != len(means):
-                raise ValueError("arm_stds must match arm_means length")
-            self.arm_means = [float(m) for m in means]
-            self.arm_stds = stds_list
-            self.true_expected_rewards = self.arm_means.copy()
-        else:
-            raise ValueError(f"Unsupported bandit_type: {self.bandit_type}")
-
-        self.arm_count = len(self.true_expected_rewards)
-        if self.arm_count == 0:
-            raise ValueError("Bandit must have at least one arm")
-
-        self._rng = np.random.default_rng(self.seed)
-
-        # Runtime state
-        self.step_count: int = 0
-        self.total_reward: float = 0.0
-        self.last_reward: float = 0.0
-        self.last_arm: int | None = None
-        self.reward_history: list[float] = []
-        self.arm_history: list[int] = []
-        self.arm_pull_counts: list[int] = [0 for _ in range(self.arm_count)]
-        self.terminated: bool = False
-        self.status: str = "in_progress"
-
-    async def _reset_engine(self) -> tuple[BanditPrivateState, BanditPublicState]:
-        if self.seed is not None:
-            self._rng = np.random.default_rng(self.seed)
-        else:
-            self._rng = np.random.default_rng()
-
-        self.step_count = 0
-        self.total_reward = 0.0
-        self.last_reward = 0.0
-        self.last_arm = None
-        self.reward_history = []
-        self.arm_history = []
-        self.arm_pull_counts = [0 for _ in range(self.arm_count)]
-        self.terminated = False
-        self.status = "in_progress"
-
-        private_state = self._build_private_state(reward=0.0)
-        public_state = self._build_public_state(reward=None)
-        return private_state, public_state
-
-    async def _step_engine(self, arm_index: int) -> tuple[BanditPrivateState, BanditPublicState]:
-        if self.terminated:
-            raise RuntimeError("Bandit episode already terminated")
-
-        if not isinstance(arm_index, int):
-            raise TypeError("arm_index must be an integer")
-        if arm_index < 0 or arm_index >= self.arm_count:
-            raise ValueError(f"arm_index {arm_index} out of range 0..{self.arm_count - 1}")
-
-        reward = float(self._sample_reward(arm_index))
-
-        self.step_count += 1
-        self.total_reward += reward
-        self.last_reward = reward
-        self.last_arm = arm_index
-        self.reward_history.append(reward)
-        self.arm_history.append(arm_index)
-        self.arm_pull_counts[arm_index] += 1
-
-        if self.step_count >= self.max_steps:
-            self.terminated = True
-            self.status = "completed"
-
-        private_state = self._build_private_state(reward=reward)
-        public_state = self._build_public_state(reward=reward)
-        return private_state, public_state
-
-    def _sample_reward(self, arm_index: int) -> float:
-        if self.bandit_type.lower() == "bernoulli":
-            assert self.arm_probabilities is not None
-            success_prob = self.arm_probabilities[arm_index]
-            return 1.0 if self._rng.random() < success_prob else 0.0
-
-        if self.bandit_type.lower() == "gaussian":
-            assert self.arm_means is not None and self.arm_stds is not None
-            mean = self.arm_means[arm_index]
-            std = self.arm_stds[arm_index]
-            return float(self._rng.normal(loc=mean, scale=std))
-
-        raise RuntimeError(f"Unknown bandit_type during sampling: {self.bandit_type}")
-
-    def get_current_states_for_observation(
-        self,
-    ) -> tuple[BanditPrivateState, BanditPublicState]:
-        private_state = self._build_private_state(reward=self.last_reward)
-        public_state = self._build_public_state(reward=self.last_reward)
-        return private_state, public_state
-
-    def _build_private_state(self, reward: float) -> BanditPrivateState:
-        return BanditPrivateState(
-            reward_last=float(reward),
-            total_reward=float(self.total_reward),
-            terminated=self.terminated,
-            truncated=False,
-            true_expected_rewards=self.true_expected_rewards.copy(),
-            step_count=self.step_count,
-        )
-
-    def _build_public_state(self, reward: float | None) -> BanditPublicState:
-        return BanditPublicState(
-            arm_count=self.arm_count,
-            step_count=self.step_count,
-            max_steps=self.max_steps,
-            last_arm=self.last_arm,
-            last_reward=float(reward)
-            if reward is not None
-            else (self.last_reward if self.step_count else None),
-            cumulative_reward=float(self.total_reward),
-            reward_history=self.reward_history.copy(),
-            arm_pull_counts=self.arm_pull_counts.copy(),
-            terminated=self.terminated,
-            status=self.status,
-        )
-
-    async def _serialize_engine(self) -> BanditEngineSnapshot:
-        snapshot = {
-            "bandit_type": self.bandit_type,
-            "arm_probabilities": self.arm_probabilities,
-            "arm_means": self.arm_means,
-            "arm_stds": self.arm_stds,
-            "max_steps": self.max_steps,
-            "seed": self.seed,
-            "step_count": self.step_count,
-            "total_reward": self.total_reward,
-            "last_reward": self.last_reward,
-            "last_arm": self.last_arm,
-            "reward_history": self.reward_history,
-            "arm_history": self.arm_history,
-            "arm_pull_counts": self.arm_pull_counts,
-            "terminated": self.terminated,
-            "status": self.status,
-            "true_expected_rewards": self.true_expected_rewards,
-            "rng_state": self._rng.bit_generator.state,
-        }
-        return BanditEngineSnapshot(
-            task_instance_dict=await self.task_instance.serialize(),
-            engine_snapshot=snapshot,
-        )
-
-    @classmethod
-    async def _deserialize_engine(cls, snapshot: BanditEngineSnapshot) -> BanditEngine:
-        from .taskset import BanditTaskInstance
-
-        task_instance = await BanditTaskInstance.deserialize(snapshot.task_instance_dict)
-        engine = cls(task_instance)
-
-        data = snapshot.engine_snapshot
-        engine.bandit_type = data.get("bandit_type", engine.bandit_type)
-        engine.max_steps = int(data.get("max_steps", engine.max_steps))
-        engine.seed = data.get("seed", engine.seed)
-        engine.arm_probabilities = data.get("arm_probabilities", engine.arm_probabilities)
-        engine.arm_means = data.get("arm_means", engine.arm_means)
-        engine.arm_stds = data.get("arm_stds", engine.arm_stds)
-        engine.true_expected_rewards = list(
-            data.get("true_expected_rewards", engine.true_expected_rewards)
-        )
-        engine.arm_count = len(engine.true_expected_rewards)
-
-        engine.step_count = int(data.get("step_count", 0))
-        engine.total_reward = float(data.get("total_reward", 0.0))
-        engine.last_reward = float(data.get("last_reward", 0.0))
-        engine.last_arm = data.get("last_arm")
-        engine.reward_history = list(data.get("reward_history", []))
-        engine.arm_history = list(data.get("arm_history", []))
-        engine.arm_pull_counts = list(
-            data.get("arm_pull_counts", [0 for _ in range(engine.arm_count)])
-        )
-        engine.terminated = bool(data.get("terminated", False))
-        engine.status = data.get("status", "in_progress")
-
-        engine._rng = np.random.default_rng()
-        rng_state = data.get("rng_state")
-        if rng_state is not None:
-            engine._rng.bit_generator.state = rng_state
-
-        return engine
-
-
-class SynthBanditObservationCallable(GetObservationCallable):
-    async def get_observation(
-        self, pub: BanditPublicState, priv: BanditPrivateState
-    ) -> InternalObservation:
-        observation: InternalObservation = {
-            "arm_count": pub.arm_count,
-            "steps_taken": pub.step_count,
-            "steps_remaining": pub.steps_remaining,
-            "last_arm": pub.last_arm,
-            "last_reward": pub.last_reward,
-            "cumulative_reward": priv.total_reward,
-            "average_reward": pub.average_reward,
-            "arm_pull_counts": pub.arm_pull_counts,
-            "reward_history": pub.reward_history,
-            "terminated": pub.terminated,
-            "status": pub.status,
-        }
-        return observation
-
-
-class SynthBanditCheckpointObservationCallable(GetObservationCallable):
-    async def get_observation(
-        self, pub: BanditPublicState, priv: BanditPrivateState
-    ) -> InternalObservation:
-        observation: InternalObservation = {
-            "arm_count": pub.arm_count,
-            "total_reward": priv.total_reward,
-            "steps_taken": pub.step_count,
-            "best_expected_reward": max(priv.true_expected_rewards)
-            if priv.true_expected_rewards
-            else None,
-            "terminated": pub.terminated,
-            "status": pub.status,
-        }
-        return observation