synth-ai 0.2.8.dev2__py3-none-any.whl → 0.4.3__py3-none-any.whl

synth_ai/environments/environment/registry.py

@@ -1,233 +0,0 @@
-"""
-Environment Registry Module
-
-This module provides a global registry system for environment types in the Synth AI framework.
-The registry allows environments to be registered by name and retrieved dynamically,
-enabling flexible environment management and discovery.
-
-The registry supports:
-- Dynamic environment registration at runtime
-- Type-safe environment retrieval
-- Environment discovery and listing
-- Centralized environment management
-
-Example:
-    >>> from synth_ai.environments.environment.registry import register_environment
-    >>> from myproject.environments import MyCustomEnvironment
-
-    >>> # Register a custom environment
-    >>> register_environment("my_env", MyCustomEnvironment)
-
-    >>> # List available environments
-    >>> available_envs = list_supported_env_types()
-    >>> print("Available environments:", available_envs)
-
-    >>> # Get environment class for instantiation
-    >>> env_cls = get_environment_cls("my_env")
-    >>> env_instance = env_cls(task_config)
-"""
-
-import importlib.metadata
-import logging
-
-from synth_ai.environments.stateful.core import StatefulEnvironment
-
-logger = logging.getLogger(__name__)
-
-# Global registry for environment types
-ENV_REGISTRY: dict[str, type[StatefulEnvironment]] = {}
-
-
-def register_environment(name: str, cls: type[StatefulEnvironment]) -> None:
-    """
-    Register an environment class under a unique name.
-
-    This function adds an environment class to the global registry, making it
-    available for dynamic instantiation by name. This is particularly useful
-    for building flexible systems where environment types are determined at
-    runtime or configured through external settings.
-
-    Args:
-        name: Unique identifier for the environment. This name will be used
-            to retrieve the environment class later. Names should be descriptive
-            and follow a consistent naming convention (e.g., "CartPole", "Sokoban").
-        cls: The environment class to register. Must be a subclass of
-            StatefulEnvironment and implement all required abstract methods.
-
-    Raises:
-        TypeError: If cls is not a subclass of StatefulEnvironment
-        ValueError: If name is empty or None
-
-    Example:
-        >>> class MyGameEnvironment(StatefulEnvironment):
-        ...     # Implementation of abstract methods
-        ...     pass
-
-        >>> register_environment("my_game", MyGameEnvironment)
-        >>>
-        >>> # Now the environment can be retrieved by name
-        >>> env_cls = get_environment_cls("my_game")
-        >>> env = env_cls(task_config)
-
-    Note:
-        Environment names are case-sensitive. It's recommended to use
-        consistent naming conventions (e.g., lowercase with underscores
-        or CamelCase) across your application.
-    """
-    ENV_REGISTRY[name] = cls
-
-
-def get_environment_cls(env_type: str) -> type[StatefulEnvironment]:
-    """
-    Retrieve a registered environment class by name.
-
-    This function looks up an environment class in the global registry
-    and returns it for instantiation. This enables dynamic environment
-    creation based on string identifiers, which is useful for:
-    - Configuration-driven environment selection
-    - API endpoints that accept environment type parameters
-    - Plugin systems and modular architectures
-    - Testing frameworks that need to test multiple environment types
-
-    Args:
-        env_type: The name of the environment type to retrieve. Must match
-            a name that was previously registered using register_environment().
-
-    Returns:
-        Type[StatefulEnvironment]: The environment class that can be instantiated
-            with appropriate task parameters.
-
-    Raises:
-        ValueError: If env_type is not found in the registry. The error message
-            will include the invalid type name and suggest checking available types.
-
-    Example:
-        >>> # Retrieve and instantiate an environment
-        >>> env_cls = get_environment_cls("CartPole")
-        >>> environment = env_cls(task_instance)
-        >>>
-        >>> # Use in configuration-driven scenarios
-        >>> config = {"environment_type": "Sokoban", "difficulty": "easy"}
-        >>> env_cls = get_environment_cls(config["environment_type"])
-        >>> env = env_cls(create_task(config))
-
-    See Also:
-        list_supported_env_types(): Get all available environment type names
-        register_environment(): Register new environment types
-    """
-    try:
-        return ENV_REGISTRY[env_type]
-    except KeyError:
-        available_types = list(ENV_REGISTRY.keys())
-        raise ValueError(
-            f"Unsupported environment type: '{env_type}'. Available types: {available_types}"
-        ) from None
-
-
-def list_supported_env_types() -> list[str]:
-    """
-    List all registered environment type names.
-
-    This function returns a list of all environment names that have been
-    registered in the global registry. It's useful for:
-    - Displaying available options to users
-    - Validating environment type parameters
-    - Building dynamic UIs or configuration tools
-    - Debugging and development
-
-    Returns:
-        List[str]: Sorted list of all registered environment type names.
-            Returns an empty list if no environments have been registered.
-
-    Example:
-        >>> # Check what environments are available
-        >>> available_envs = list_supported_env_types()
-        >>> print("Supported environments:")
-        >>> for env_type in available_envs:
-        ...     print(f"  - {env_type}")
-
-        >>> # Validate user input
-        >>> user_choice = input("Choose environment: ")
-        >>> if user_choice not in list_supported_env_types():
-        ...     print(f"Error: {user_choice} not available")
-
-        >>> # Build configuration options
-        >>> config_schema = {
-        ...     "environment_type": {
-        ...         "enum": list_supported_env_types(),
-        ...         "description": "Type of environment to use"
-        ...     }
-        ... }
-
-    Note:
-        The returned list is sorted alphabetically for consistent ordering.
-        This function returns a copy of the environment names, so modifying
-        the returned list will not affect the registry.
-    """
-    return sorted(ENV_REGISTRY.keys())
-
-
-def discover_entry_point_environments() -> None:
-    """
-    Discover and register environments from entry points.
-
-    This function scans for environments registered via setuptools entry points
-    under the group 'synth_ai.environments'. This allows third-party packages
-    to register environments by declaring them in their pyproject.toml:
-
-    [project.entry-points."synth_ai.environments"]
-    my_env = "my_package.my_env:MyEnvironment"
-    another_env = "my_package.other:AnotherEnv"
-
-    The function will automatically import and register all discovered environments.
-    """
-    try:
-        entry_points = importlib.metadata.entry_points()
-        if hasattr(entry_points, "select"):
-            # Python 3.10+
-            env_entry_points = entry_points.select(group="synth_ai.environments")
-        else:
-            # Python 3.9 and below
-            env_entry_points = entry_points.get("synth_ai.environments", [])
-
-        for entry_point in env_entry_points:
-            try:
-                env_cls = entry_point.load()
-
-                # Validate that it's a StatefulEnvironment subclass
-                if not issubclass(env_cls, StatefulEnvironment):
-                    logger.warning(
-                        f"Entry point '{entry_point.name}' from '{entry_point.value}' "
-                        f"is not a StatefulEnvironment subclass. Skipping."
-                    )
-                    continue
-
-                register_environment(entry_point.name, env_cls)
-                logger.info(f"Registered environment '{entry_point.name}' from entry point")
-
-            except Exception as e:
-                logger.error(
-                    f"Failed to load environment entry point '{entry_point.name}' "
-                    f"from '{entry_point.value}': {e}"
-                )
-    except Exception as e:
-        logger.debug(f"Entry point discovery failed (this is normal if no entry points exist): {e}")
-
-
-def auto_discover_environments() -> None:
-    """
-    Automatically discover and register environments from multiple sources.
-
-    This function combines multiple discovery mechanisms:
-    1. Entry points (setuptools plugins)
-    2. Could be extended with more discovery methods in the future
-
-    This should be called once at application startup to populate the registry
-    with all available environments.
-    """
-    discover_entry_point_environments()
-
-
-# Auto-discover environments when the registry module is imported
-# This ensures third-party environments are available as soon as the registry is used
-auto_discover_environments()

synth_ai/environments/environment/resources/sqlite.py

@@ -1,45 +0,0 @@
-import contextlib
-import sqlite3
-import threading
-from pathlib import Path
-
-
-class SQLiteManager:
-    def __init__(self, db_path: Path, read_only: bool = True, ephemeral: bool = False):
-        """Initializes SQLiteManager with optional read-only or ephemeral mode."""
-        self.db_path = db_path
-        self.read_only = read_only
-        self.ephemeral = ephemeral
-        self._lock = threading.RLock()
-        self._conn: sqlite3.Connection | None = None
-
-    @contextlib.contextmanager
-    def connection(self):
-        with self._lock:
-            if self._conn is None:
-                uri = f"file:{self.db_path}?mode=ro" if self.read_only else str(self.db_path)
-                self._conn = sqlite3.connect(uri, uri=self.read_only, isolation_level="DEFERRED")
-                self._conn.execute("PRAGMA foreign_keys=ON;")
-                self._conn.execute("PRAGMA journal_mode=WAL;")
-            try:
-                yield self._conn
-                self._conn.commit()
-            except:
-                self._conn.rollback()
-                raise
-
-    def close(self):
-        """Closes the underlying connection for cleanup at environment teardown."""
-        with self._lock:
-            if self._conn:
-                self._conn.close()
-                self._conn = None
-
-    def reset(self, new_db_path: Path | None = None):
-        """Resets the connection, optionally switching to a new database path for a fresh session."""
-        with self._lock:
-            if self._conn:
-                self._conn.close()
-            if new_db_path:
-                self.db_path = new_db_path
-            self._conn = None

synth_ai/environments/environment/results.py

@@ -1 +0,0 @@
-# EnvHistory, EnvRecord, EnvironmentCheckpointObservation (customer supplied, not for agent but only designer)

synth_ai/environments/environment/rewards/__init__.py

@@ -1 +0,0 @@
-# rewards package

synth_ai/environments/environment/rewards/core.py

@@ -1,29 +0,0 @@
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any
-
-
-class RewardComponent(ABC):
-    """Interface for a component contributing to stepwise reward."""
-
-    weight: float = 1.0
-
-    @abstractmethod
-    async def score(self, state: Any, action: Any) -> float:
-        """Compute the component's reward given current state and action."""
-        ...
-
-
-class RewardStack:
-    """Aggregates multiple RewardComponent instances to compute a total reward."""
-
-    def __init__(self, components: list[RewardComponent]):
-        self.components = components
-
-    async def step_reward(self, state: Any, action: Any) -> float:
-        """Compute the sum of weighted component rewards for a single step."""
-        total = 0.0
-        for comp in self.components:
-            total += comp.weight * await comp.score(state, action)
-        return total

synth_ai/environments/environment/shared_engine.py

@@ -1,26 +0,0 @@
-from abc import abstractmethod
-from typing import Any
-
-
-class InternalObservation:
-    public_observation: Any
-    private_observation: Any
-
-
-class GetObservationCallable:
-    @abstractmethod
-    async def get_observation(self) -> InternalObservation:
-        pass
-
-    pass
-
-
-class Engine:
-    async def initialize(self):
-        pass
-
-    async def terminate(self):
-        pass
-
-    async def _step_engine(self):
-        pass

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",
-]