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

synth_ai/environments/examples/red/engine_helpers/state_extraction.py

@@ -1,172 +0,0 @@
-from typing import Any, Dict, List
-
-from .memory_map import *
-
-
-def get_byte(memory, addr: int) -> int:
-    """Get single byte from memory"""
-    try:
-        return memory[addr]
-    except (IndexError, TypeError):
-        return 0
-
-
-def get_word(memory, addr: int) -> int:
-    """Get 16-bit word from memory (little endian)"""
-    return get_byte(memory, addr) | (get_byte(memory, addr + 1) << 8)
-
-
-def get_3byte_int(memory, addr: int) -> int:
-    """Get 24-bit integer from memory for XP values"""
-    return (
-        get_byte(memory, addr)
-        | (get_byte(memory, addr + 1) << 8)
-        | (get_byte(memory, addr + 2) << 16)
-    )
-
-
-def get_bcd_3byte(memory, addr: int) -> int:
-    """Get 3-byte BCD (Binary Coded Decimal) value for money"""
-    byte1 = get_byte(memory, addr)
-    byte2 = get_byte(memory, addr + 1)
-    byte3 = get_byte(memory, addr + 2)
-    return (
-        (byte1 >> 4) * 100000
-        + (byte1 & 0xF) * 10000
-        + (byte2 >> 4) * 1000
-        + (byte2 & 0xF) * 100
-        + (byte3 >> 4) * 10
-        + (byte3 & 0xF)
-    )
-
-
-def extract_party_pokemon(memory) -> List[Dict[str, Any]]:
-    """Extract detailed information for each Pokemon in party"""
-    party_count = get_byte(memory, PARTY_COUNT)
-    party = []
-
-    for i in range(party_count):
-        # Basic Pokemon info
-        species = get_byte(memory, PARTY_SPECIES + i)
-        level = get_byte(memory, PARTY_LEVELS + i)
-
-        # HP (2 bytes each Pokemon)
-        hp_current = get_word(memory, PARTY_HP_CURRENT + (i * 2))
-        hp_max = get_word(memory, PARTY_HP_MAX + (i * 2))
-
-        # XP (3 bytes each Pokemon)
-        xp = get_3byte_int(memory, PARTY_XP + (i * 3))
-
-        pokemon = {
-            "species_id": species,
-            "level": level,
-            "hp_current": hp_current,
-            "hp_max": hp_max,
-            "xp": xp,
-            "hp_percentage": round((hp_current / hp_max * 100) if hp_max > 0 else 0, 1),
-        }
-        party.append(pokemon)
-
-    return party
-
-
-def extract_inventory(memory) -> List[Dict[str, Any]]:
-    """Extract inventory items"""
-    item_count = get_byte(memory, INVENTORY_COUNT)
-    inventory = []
-
-    for i in range(min(item_count, 20)):  # Max 20 items
-        item_id = get_byte(memory, INVENTORY_START + (i * 2))
-        quantity = get_byte(memory, INVENTORY_START + (i * 2) + 1)
-
-        if item_id > 0:  # Valid item
-            inventory.append({"item_id": item_id, "quantity": quantity})
-
-    return inventory
-
-
-def extract_battle_state(memory) -> Dict[str, Any]:
-    """Extract battle-specific state"""
-    in_battle = get_byte(memory, IN_BATTLE_FLAG) > 0
-    
-    if not in_battle:
-        return {
-            "enemy_hp_current": 0,
-            "enemy_hp_max": 0,
-            "enemy_level": 0,
-            "enemy_species_id": 0,
-            "enemy_hp_percentage": 0.0,
-            "battle_turn": 0,
-        }
-    
-    enemy_hp_current = get_word(memory, ENEMY_HP_CURRENT)
-    enemy_hp_max = get_word(memory, ENEMY_HP_MAX)
-    
-    return {
-        "enemy_hp_current": enemy_hp_current,
-        "enemy_hp_max": enemy_hp_max,
-        "enemy_level": get_byte(memory, ENEMY_LEVEL),
-        "enemy_species_id": get_byte(memory, ENEMY_SPECIES),
-        "enemy_hp_percentage": round((enemy_hp_current / enemy_hp_max * 100) if enemy_hp_max > 0 else 0, 1),
-        "battle_turn": get_byte(memory, BATTLE_TURN),
-    }
-
-
-def extract_game_state(memory) -> Dict[str, Any]:
-    """Extract comprehensive game state from Game Boy memory"""
-    # Get party and inventory details
-    party = extract_party_pokemon(memory)
-    inventory = extract_inventory(memory)
-
-    # Get money
-    money = get_bcd_3byte(memory, MONEY)
-    
-    # Get battle state
-    battle_state = extract_battle_state(memory)
-
-    # Basic game state
-    state = {
-        "map_id": get_byte(memory, MAP_ID),
-        "player_x": get_byte(memory, PLAYER_X),
-        "player_y": get_byte(memory, PLAYER_Y),
-        "badges": get_byte(memory, BADGE_FLAGS),
-        "in_battle": get_byte(memory, IN_BATTLE_FLAG) > 0,
-        "battle_outcome": get_byte(memory, BATTLE_OUTCOME),
-        "money": money,
-        "menu_state": get_byte(memory, MENU_STATE),
-        "warp_flag": get_byte(memory, WARP_FLAG),
-        "text_box_active": get_byte(memory, TEXT_BOX_ACTIVE) > 0,
-        # Detailed party and inventory
-        "party_count": len(party),
-        "party_pokemon": party,
-        "inventory_count": len(inventory),
-        "inventory_items": inventory,
-        # Battle state
-        **battle_state,
-        # Legacy fields for compatibility (use first Pokemon if available)
-        "party_level": party[0]["level"] if party else 0,
-        "party_hp_current": party[0]["hp_current"] if party else 0,
-        "party_hp_max": party[0]["hp_max"] if party else 0,
-        "party_xp": party[0]["xp"] if party else 0,
-        "inventory_count_legacy": get_byte(memory, INVENTORY_COUNT),
-    }
-
-    return state
-
-
-def get_badge_count(badges_byte: int) -> int:
-    """Count number of badges from bitfield"""
-    return bin(badges_byte).count("1")
-
-
-def format_position(x: int, y: int, map_id: int) -> str:
-    """Format position as readable string"""
-    return f"Map{map_id:02X}:({x},{y})"
-
-
-def format_hp_status(current: int, max_hp: int) -> str:
-    """Format HP as readable string"""
-    if max_hp == 0:
-        return "HP: Unknown"
-    percentage = (current / max_hp) * 100
-    return f"HP: {current}/{max_hp} ({percentage:.0f}%)"

synth_ai/environments/examples/red/environment.py

@@ -1,298 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Dict, List, Optional, Union
-import base64
-from io import BytesIO
-
-from pydantic import BaseModel, Field
-
-from synth_ai.environments.environment.shared_engine import (
-    GetObservationCallable,
-    InternalObservation,
-)
-from synth_ai.environments.environment.tools import (
-    TOOL_REGISTRY,
-    AbstractTool,
-    EnvToolCall,
-    ToolResult,
-    register_tool,
-)
-from synth_ai.environments.reproducibility.core import ReproducibleEnvironment
-from synth_ai.environments.stateful.core import StatefulEnvironment
-try:  # optional for image encoding
-    import numpy as _np  # type: ignore
-    from PIL import Image as _PILImage  # type: ignore
-except Exception:  # pragma: no cover - optional dependency
-    _np = None  # type: ignore
-    _PILImage = None  # type: ignore
-
-# Import logging configuration to suppress JAX debug messages
-from .engine import (
-    PokemonRedEngine,
-    PokemonRedEngineSnapshot,
-    PokemonRedPrivateState,
-    PokemonRedPublicState,
-)
-from .taskset import INSTANCE as DEFAULT_TASK_INSTANCE
-from .taskset import PokemonRedTaskInstance
-
-
-# Tool input schemas
-class PressButtonInput(BaseModel):
-    button: str = Field(
-        ..., description="Game Boy button: A, B, UP, DOWN, LEFT, RIGHT, START, SELECT"
-    )
-    frames: int = Field(1, description="Number of frames to hold the button")
-
-
-# Tool definitions
-class PressButtonTool(AbstractTool):
-    name = "press_button"
-    description = "Press a Game Boy button for the specified number of frames"
-    call_schema = PressButtonInput
-    result_schema = ToolResult
-
-    def __init__(self, engine: PokemonRedEngine):
-        self.engine = engine
-
-    async def __call__(self, call: EnvToolCall) -> ToolResult:
-        try:
-            validated_args = self.call_schema(**call.args)
-            action = {"button": validated_args.button, "frames": validated_args.frames}
-            priv_state, pub_state = await self.engine._step_engine(action)
-            return ToolResult(
-                ok=True,
-                payload={
-                    "public": pub_state,
-                    "private": priv_state,
-                },
-            )
-        except Exception as e:
-            # Get current state for error context
-            priv_state, pub_state = self.engine._create_states(reward=0.0)
-            return ToolResult(
-                ok=False,
-                error=str(e),
-                payload={"public": pub_state},
-            )
-
-
-# Observation callable for Pokemon Red
-class PokemonRedObservationCallable(GetObservationCallable):
-    async def get_observation(
-        self, pub: PokemonRedPublicState, priv: PokemonRedPrivateState
-    ) -> InternalObservation:
-        """Convert Pokemon Red states to agent observation"""
-        from .engine_helpers.state_extraction import (
-            format_hp_status,
-            format_position,
-            get_badge_count,
-        )
-
-        badge_count = get_badge_count(pub.badges)
-        position = format_position(pub.player_x, pub.player_y, pub.map_id)
-        hp_status = format_hp_status(pub.party_hp_current, pub.party_hp_max)
-
-        obs = {
-            "position": position,
-            "badges_earned": badge_count,
-            "badges_bitfield": pub.badges,
-            "hp_status": hp_status,
-            "party_level": pub.party_level,
-            "party_xp": pub.party_xp,
-            "in_battle": pub.in_battle,
-            "step_count": pub.step_count,
-            "reward_last_step": priv.reward_last_step,
-            "total_reward": priv.total_reward,
-            "terminated": priv.terminated,
-        }
-
-        if pub.error_info:
-            obs["error"] = pub.error_info
-
-        return obs
-
-
-class PokemonRedEnvironment(StatefulEnvironment, ReproducibleEnvironment[PokemonRedEngine]):
-    """Pokemon Red stateful game environment for AI agents"""
-
-    def __init__(
-        self,
-        task_instance: Optional[PokemonRedTaskInstance] = None,
-        custom_step_obs: Optional[GetObservationCallable] = None,
-        custom_ckpt_obs: Optional[GetObservationCallable] = None,
-    ):
-        self.name = "PokemonRed"
-        self.task_instance = task_instance or DEFAULT_TASK_INSTANCE
-        self.custom_step_observation_callable = custom_step_obs or PokemonRedObservationCallable()
-        self.custom_checkpoint_observation_callable = (
-            custom_ckpt_obs or PokemonRedObservationCallable()
-        )
-        self.engine = PokemonRedEngine(self.task_instance)
-
-        # Register tools
-        self._press_button_tool = PressButtonTool(self.engine)
-        if self._press_button_tool.name not in TOOL_REGISTRY:
-            register_tool(self._press_button_tool)
-
-    async def initialize(self) -> InternalObservation:
-        """Initialize the Pokemon Red environment"""
-        priv, pub = await self.engine._reset_engine()
-        return await self._to_observation(priv, pub, self.custom_step_observation_callable)
-
-    async def terminate(self) -> InternalObservation:
-        """Terminate the environment"""
-        priv, pub = self.engine._create_states(reward=0.0, terminated=True)
-        obs_dict = {
-            "terminated": True,
-            "message": "Pokemon Red environment terminated.",
-        }
-        return await self._to_observation(
-            priv, pub, self.custom_step_observation_callable, extra_obs=obs_dict
-        )
-
-    def validate_tool_calls(
-        self, tool_calls: Union[EnvToolCall, List[EnvToolCall], List[List[EnvToolCall]]]
-    ) -> EnvToolCall:
-        """Validate and normalize tool calls to single EnvToolCall"""
-        if isinstance(tool_calls, list):
-            if not tool_calls:
-                raise ValueError("Received empty list of tool calls.")
-            if isinstance(tool_calls[0], list):
-                if not tool_calls[0]:
-                    raise ValueError("Received empty inner list of tool calls.")
-                agent_call = tool_calls[0][0]
-            else:
-                agent_call = tool_calls[0]
-        elif isinstance(tool_calls, EnvToolCall):
-            agent_call = tool_calls
-        else:
-            raise TypeError(f"Unexpected type for tool_calls: {type(tool_calls)}")
-
-        if not isinstance(agent_call, EnvToolCall):
-            raise TypeError(f"Processed call is not EnvToolCall: {type(agent_call)}")
-        if agent_call.tool != "press_button":
-            raise ValueError(f"Unknown tool: {agent_call.tool}. Expected 'press_button'.")
-
-        return agent_call
-
-    async def step(
-        self, tool_calls: Union[EnvToolCall, List[EnvToolCall], List[List[EnvToolCall]]]
-    ) -> InternalObservation:
-        """Execute one step in the Pokemon Red environment"""
-        agent_call = self.validate_tool_calls(tool_calls)
-        tool_result: ToolResult = await self._press_button_tool(agent_call)
-
-        payload_dict = tool_result.payload
-        if not tool_result.ok or not isinstance(payload_dict, dict):
-            # Fallback if tool execution failed
-            priv_state, pub_state = self.engine._create_states(reward=0.0)
-            if tool_result.error and hasattr(pub_state, "error_info"):
-                pub_state.error_info = tool_result.error
-        else:
-            # Extract states from successful tool execution - now they're dataclass objects
-            priv_state = payload_dict.get("private")
-            pub_state = payload_dict.get("public")
-
-            if priv_state is None or pub_state is None:
-                priv_state, pub_state = self.engine._create_states(reward=0.0)
-                if tool_result.error and hasattr(pub_state, "error_info"):
-                    pub_state.error_info = tool_result.error
-            else:
-                # States are already dataclass objects, no need to reconstruct
-                if tool_result.error and hasattr(pub_state, "error_info"):
-                    pub_state.error_info = tool_result.error
-
-        return await self._to_observation(
-            priv_state, pub_state, self.custom_step_observation_callable
-        )
-
-    async def checkpoint(self) -> InternalObservation:
-        """Create a checkpoint of the current environment state"""
-        engine_snapshot: PokemonRedEngineSnapshot = await self.engine._serialize_engine()
-        priv, pub = self.engine._create_states(reward=0.0)
-        obs_data = await self._to_observation(
-            priv, pub, self.custom_checkpoint_observation_callable
-        )
-        if isinstance(obs_data, dict):
-            obs_data["engine_snapshot_data"] = engine_snapshot.model_dump()
-        return obs_data
-
-    async def _to_observation(
-        self,
-        priv: PokemonRedPrivateState,
-        pub: PokemonRedPublicState,
-        obs_cb: Optional[GetObservationCallable],
-        extra_obs: Optional[Dict[str, Any]] = None,
-    ) -> InternalObservation:
-        """Convert states to observation using the specified callback"""
-        active_obs_cb = obs_cb or PokemonRedObservationCallable()
-        observation = await active_obs_cb.get_observation(pub, priv)
-        
-        # Include raw state fields for reward calculation
-        if isinstance(observation, dict):
-            observation["map_id"] = pub.world.map_id if pub.world else None
-            observation["player_x"] = pub.world.player_x if pub.world else None
-            observation["player_y"] = pub.world.player_y if pub.world else None
-            observation["party_count"] = len(pub.party) if pub.party else 0
-            observation["party_pokemon"] = [
-                {
-                    "species_id": p.species_id,
-                    "level": p.level,
-                    "hp_current": p.hp_current,
-                    "hp_max": p.hp_max,
-                    "hp_percentage": (p.hp_current / p.hp_max * 100) if p.hp_max > 0 else 0,
-                }
-                for p in (pub.party or [])
-            ]
-            observation["in_battle"] = pub.system.in_battle if pub.system else False
-            observation["battle_outcome"] = pub.system.battle_outcome if pub.system else 0
-            observation["text_box_active"] = pub.system.text_box_active if pub.system else False
-            observation["enemy_hp_current"] = pub.system.enemy_hp_current if pub.system else 0
-            observation["enemy_hp_max"] = pub.system.enemy_hp_max if pub.system else 0
-            observation["enemy_hp_percentage"] = pub.system.enemy_hp_percentage if pub.system else 0.0
-            observation["badges"] = pub.progress.badges if pub.progress else 0
-        # Attach latest PNG frame for VLM agents if available
-        try:
-            emulator = getattr(self.engine, "emulator", None)
-            screen = getattr(emulator, "screen", None)
-            if screen is not None and _np is not None and _PILImage is not None:
-                # Prefer documented ndarray property if present
-                frame = getattr(screen, "ndarray", None)
-                if frame is None and hasattr(screen, "image"):
-                    frame = screen.image
-                if isinstance(frame, _np.ndarray) and frame.ndim == 3 and frame.shape[0] > 0 and frame.shape[1] > 0:
-                    array_uint8 = (
-                        frame.astype("uint8") if frame.dtype != _np.uint8 else frame
-                    )
-                    # PyBoy gives RGBA; convert to RGB
-                    if array_uint8.shape[-1] == 4:
-                        array_uint8 = array_uint8[:, :, :3]
-                    img = _PILImage.fromarray(array_uint8, mode="RGB")
-                    buf = BytesIO()
-                    img.save(buf, format="PNG")
-                    encoded = base64.b64encode(buf.getvalue()).decode("ascii")
-                    if isinstance(observation, dict):
-                        observation["observation_image_base64"] = encoded
-                        observation["observation_image_format"] = "png"
-                        observation["observation_image_width"] = int(array_uint8.shape[1])
-                        observation["observation_image_height"] = int(array_uint8.shape[0])
-                        observation["observation_image_data_url"] = f"data:image/png;base64,{encoded}"
-        except Exception:
-            pass
-        if extra_obs and isinstance(observation, dict):
-            observation.update(extra_obs)
-        return observation
-
-    # ReproducibleEnvironment methods
-    async def _serialize_engine(self) -> PokemonRedEngineSnapshot:
-        return await self.engine._serialize_engine()
-
-    @classmethod
-    async def _deserialize_engine(
-        cls, snapshot: PokemonRedEngineSnapshot, task_instance: PokemonRedTaskInstance
-    ) -> "PokemonRedEnvironment":
-        eng = await PokemonRedEngine._deserialize_engine(snapshot, task_instance)
-        env = cls(task_instance)
-        env.engine = eng
-        return env

synth_ai/environments/examples/red/taskset.py

@@ -1,79 +0,0 @@
-from __future__ import annotations
-
-import uuid
-from dataclasses import dataclass
-from pathlib import Path
-
-from synth_ai.environments.tasks.core import (
-    Impetus,
-    Intent,
-    Task,
-    TaskInstance,
-    TaskInstanceMetadata,
-)
-
-# Define the main task for Pokemon Red
-TASK = Task(
-    global_premises="You are playing Pokemon Red. Start in Pewter City with a level-10 Pikachu.",
-    global_constraints="No glitches or exploits. Play within normal game mechanics.",
-    global_objectives="Defeat Brock at the Pewter Gym to earn the Boulder Badge.",
-    shared_env_params={},
-)
-
-# Path to initial save state (would contain a save near Pewter Gym)
-INITIAL_SNAPSHOT = Path(__file__).parent / "snapshots" / "pewter_start.state"
-
-
-@dataclass
-class PokemonRedTaskInstance(TaskInstance):
-    """Task instance for Pokemon Red challenges"""
-
-    async def serialize(self) -> dict:
-        """Serialize the task instance to a dictionary"""
-        return {
-            "id": str(self.id),
-            "impetus": {"instructions": self.impetus.instructions},
-            "intent": {
-                "rubric": self.intent.rubric,
-                "gold_trajectories": None,
-                "gold_state_diff": self.intent.gold_state_diff,
-            },
-            "metadata": {},
-            "is_reproducible": self.is_reproducible,
-            "initial_engine_snapshot": str(self.initial_engine_snapshot)
-            if self.initial_engine_snapshot
-            else None,
-        }
-
-    @classmethod
-    async def deserialize(cls, data: dict) -> "PokemonRedTaskInstance":
-        """Deserialize a task instance from a dictionary"""
-        return cls(
-            id=uuid.UUID(data["id"]),
-            impetus=Impetus(instructions=data["impetus"]["instructions"]),
-            intent=Intent(
-                rubric=data["intent"]["rubric"],
-                gold_trajectories=None,
-                gold_state_diff=data["intent"]["gold_state_diff"],
-            ),
-            metadata=TaskInstanceMetadata(),
-            is_reproducible=data["is_reproducible"],
-            initial_engine_snapshot=None,
-        )
-
-
-# Main task instance - beat Brock for Boulder Badge
-INSTANCE = PokemonRedTaskInstance(
-    id=uuid.UUID("12345678-1234-5678-9abc-123456789abc"),
-    impetus=Impetus(
-        instructions="Navigate to Pewter Gym and defeat Brock to earn the Boulder Badge. Use strategic Pokemon battles and item management."
-    ),
-    intent=Intent(
-        rubric="Successfully obtain the Boulder Badge by defeating Brock at Pewter Gym. Efficiency measured by minimal steps and strategic Pokemon usage.",
-        gold_trajectories=None,
-        gold_state_diff={"badges": 1},
-    ),
-    metadata=TaskInstanceMetadata(),
-    is_reproducible=True,
-    initial_engine_snapshot=INITIAL_SNAPSHOT if INITIAL_SNAPSHOT.exists() else None,
-)

synth_ai/environments/examples/red/units/__init__.py

@@ -1 +0,0 @@
-# Unit tests for Pokemon Red environment

synth_ai/environments/examples/sokoban/__init__.py

@@ -1 +0,0 @@
-"""Sokoban environment example."""