synth-ai 0.2.0__py3-none-any.whl → 0.2.1.dev0__py3-none-any.whl

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

@@ -0,0 +1,28 @@
+# Pokemon Red memory addresses for state extraction
+BADGE_FLAGS = 0xD356  # bit-field for badges
+MAP_ID = 0xD35E  # current map ID
+PLAYER_X = 0xD362  # player X coordinate
+PLAYER_Y = 0xD361  # player Y coordinate
+IN_BATTLE_FLAG = 0xD057  # battle state flag
+BATTLE_OUTCOME = 0xD089  # 0=ongoing, 1=win, 2=lose
+
+# Party Pokemon data (up to 6 Pokemon)
+PARTY_COUNT = 0xD163  # number of Pokemon in party (0-6)
+PARTY_SPECIES = 0xD164  # species of each Pokemon (6 bytes)
+PARTY_HP_CURRENT = 0xD16C  # current HP of each Pokemon (2 bytes each, 12 bytes total)
+PARTY_HP_MAX = 0xD188  # max HP of each Pokemon (2 bytes each, 12 bytes total)
+PARTY_LEVELS = 0xD18C  # level of each Pokemon (6 bytes)
+PARTY_XP = 0xD179  # XP of each Pokemon (3 bytes each, 18 bytes total)
+
+# Player data
+MONEY = 0xD347  # player money (3 bytes, BCD format)
+PLAYER_NAME = 0xD158  # player name (up to 11 bytes)
+
+# Inventory data
+INVENTORY_COUNT = 0xD31D  # number of items in bag
+INVENTORY_START = 0xD31E  # start of item/quantity pairs (up to 20 items, 2 bytes each)
+
+# Game state flags
+MENU_STATE = 0xCC26  # menu state flags
+WARP_FLAG = 0xD36C  # warp/transition flags
+TEXT_BOX_ACTIVE = 0xCD3D  # text box display flag

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

@@ -0,0 +1,275 @@
+from synth_ai.environments.environment.rewards.core import RewardComponent
+from typing import Dict, Any, Set
+
+
+class BadgeRewardComponent(RewardComponent):
+    """Reward for earning gym badges"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        prev_badges = action.get("prev_badges", 0)
+        current_badges = state["badges"]
+        new_badges = current_badges & ~prev_badges
+        badge_count = bin(new_badges).count("1")
+        return badge_count * 1.0
+
+
+class MapTransitionComponent(RewardComponent):
+    """Reward for exploring new areas"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        prev_map = action.get("prev_map_id", -1)
+        current_map = state["map_id"]
+        return 0.1 if current_map != prev_map else 0.0
+
+
+class BattleVictoryComponent(RewardComponent):
+    """Reward for winning battles"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        prev_in_battle = action.get("prev_in_battle", False)
+        current_in_battle = state["in_battle"]
+        battle_outcome = state["battle_outcome"]
+
+        # Transitioning from battle to not in battle with victory
+        if prev_in_battle and not current_in_battle and battle_outcome == 1:
+            return 0.5
+        return 0.0
+
+
+class LevelUpComponent(RewardComponent):
+    """Reward for Pokemon leveling up"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        prev_level = action.get("prev_party_level", 0)
+        current_level = state["party_level"]
+        level_gain = max(0, current_level - prev_level)
+        return level_gain * 0.3
+
+
+class XPGainComponent(RewardComponent):
+    """Small reward for XP gains"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        prev_xp = action.get("prev_party_xp", 0)
+        current_xp = state["party_xp"]
+        xp_gain = max(0, current_xp - prev_xp)
+        return xp_gain * 0.001  # Very small multiplier
+
+
+class StepPenaltyComponent(RewardComponent):
+    """Small penalty for each step to encourage efficiency"""
+
+    def __init__(self, penalty: float = -0.001):
+        self.penalty = penalty
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        return self.penalty
+
+
+class MenuPenaltyComponent(RewardComponent):
+    """Penalty for excessive menu usage"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # This would need more sophisticated menu tracking
+        return 0.0
+
+
+# ===== NEW EARLY GAME PALLET TOWN REWARDS =====
+
+
+class ExitHouseReward(RewardComponent):
+    """High reward for first time leaving the starting house - +2.0 points"""
+
+    def __init__(self):
+        self.house_exited = False
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if self.house_exited:
+            return 0.0
+
+        prev_map = action.get("prev_map_id", -1)
+        current_map = state["map_id"]
+
+        # Exit from house to town (assuming house maps are 1,2 and town is 0)
+        if prev_map in [1, 2] and current_map == 0:
+            self.house_exited = True
+            return 2.0
+        return 0.0
+
+
+class NPCInteractionReward(RewardComponent):
+    """Reward for talking to NPCs - +0.8 points per unique NPC"""
+
+    def __init__(self):
+        self.npcs_talked_to: Set[tuple] = set()
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Detect NPC conversations
+        if state["text_box_active"] and not action.get("prev_text_box_active", False):
+            # Use position as NPC identifier
+            npc_key = (state["player_x"], state["player_y"], state["map_id"])
+            if npc_key not in self.npcs_talked_to:
+                self.npcs_talked_to.add(npc_key)
+                return 0.8
+        return 0.0
+
+
+class OakLabDiscoveryReward(RewardComponent):
+    """High reward for finding and entering Oak's lab - +2.5 points"""
+
+    def __init__(self):
+        self.lab_discovered = False
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if self.lab_discovered:
+            return 0.0
+
+        prev_map = action.get("prev_map_id", -1)
+        current_map = state["map_id"]
+
+        # Entering Oak's lab (assuming map 3)
+        if prev_map == 0 and current_map == 3:
+            self.lab_discovered = True
+            return 2.5
+        return 0.0
+
+
+class StarterPokemonReward(RewardComponent):
+    """Very high reward for getting first Pokemon - +10.0 points"""
+
+    def __init__(self):
+        self.starter_obtained = False
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if self.starter_obtained:
+            return 0.0
+
+        # Detect getting first Pokemon
+        prev_party_count = len(action.get("prev_party", []))
+        current_party_count = len(state.get("party", []))
+
+        if prev_party_count == 0 and current_party_count == 1:
+            if state["map_id"] == 3:  # In Oak's lab
+                self.starter_obtained = True
+                return 10.0
+        return 0.0
+
+
+class FirstBattleReward(RewardComponent):
+    """High reward for engaging in first battle - +5.0 points"""
+
+    def __init__(self):
+        self.first_battle = False
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if self.first_battle:
+            return 0.0
+
+        prev_in_battle = action.get("prev_in_battle", False)
+        current_in_battle = state["in_battle"]
+
+        if not prev_in_battle and current_in_battle:
+            self.first_battle = True
+            return 5.0
+        return 0.0
+
+
+class DirectionExplorationReward(RewardComponent):
+    """Reward for trying all movement directions - +1.0 points when complete"""
+
+    def __init__(self):
+        self.directions_tried: Set[str] = set()
+        self.reward_given = False
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if self.reward_given:
+            return 0.0
+
+        # Track movement directions based on position changes
+        prev_x = action.get("prev_player_x", state["player_x"])
+        prev_y = action.get("prev_player_y", state["player_y"])
+        current_x = state["player_x"]
+        current_y = state["player_y"]
+
+        if current_x > prev_x:
+            self.directions_tried.add("RIGHT")
+        elif current_x < prev_x:
+            self.directions_tried.add("LEFT")
+        elif current_y > prev_y:
+            self.directions_tried.add("DOWN")
+        elif current_y < prev_y:
+            self.directions_tried.add("UP")
+
+        if len(self.directions_tried) >= 4:
+            self.reward_given = True
+            return 1.0
+        return 0.0
+
+
+class BuildingExplorationReward(RewardComponent):
+    """Reward for entering different buildings - +0.5 points per building"""
+
+    def __init__(self):
+        self.buildings_entered: Set[int] = set()
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        prev_map = action.get("prev_map_id", -1)
+        current_map = state["map_id"]
+
+        # Entering a new building from town
+        if (
+            prev_map == 0 and current_map > 0 and current_map not in [1, 2]
+        ):  # From town to new building
+            if current_map not in self.buildings_entered:
+                self.buildings_entered.add(current_map)
+                return 0.5
+        return 0.0
+
+
+class ObjectInteractionReward(RewardComponent):
+    """Reward for pressing A on various objects - +0.3 points per object"""
+
+    def __init__(self):
+        self.objects_interacted: Set[tuple] = set()
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Detect A button interactions that trigger text
+        if state["text_box_active"] and not action.get("prev_text_box_active", False):
+            object_key = (state["player_x"], state["player_y"], state["map_id"])
+            if object_key not in self.objects_interacted:
+                self.objects_interacted.add(object_key)
+                return 0.3
+        return 0.0
+
+
+class TownExplorationReward(RewardComponent):
+    """Reward for thorough town exploration - +0.1 per new position"""
+
+    def __init__(self):
+        self.positions_visited: Set[tuple] = set()
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if state["map_id"] == 0:  # In Pallet Town
+            position_key = (state["player_x"], state["player_y"])
+            if position_key not in self.positions_visited:
+                self.positions_visited.add(position_key)
+                return 0.1
+        return 0.0
+
+
+class RouteAttemptReward(RewardComponent):
+    """Reward for trying to leave town (triggers story) - +3.0 points"""
+
+    def __init__(self):
+        self.route_attempted = False
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        if self.route_attempted:
+            return 0.0
+
+        # Detect reaching the edge of Pallet Town (attempting to go north)
+        if state["map_id"] == 0:  # In Pallet Town
+            if state["player_y"] <= 1:  # At northern edge
+                self.route_attempted = True
+                return 3.0
+        return 0.0

synth_ai/environments/examples/red/engine_helpers/reward_library/__init__.py

@@ -0,0 +1,142 @@
+"""
+Pokemon Red Reward Library
+
+Comprehensive collection of reward components organized by category.
+"""
+
+from .pallet_town_rewards import *
+from .exploration_rewards import *
+from .social_rewards import *
+from .pokemon_rewards import *
+from .battle_rewards import *
+from .story_rewards import *
+from .economy_rewards import *
+from .efficiency_rewards import *
+from .novelty_rewards import *
+from .adaptive_rewards import *
+from .composite_rewards import *
+
+__all__ = [
+    # Pallet Town Early Game
+    "LeaveStartingRoomReward",
+    "TalkToMomReward",
+    "InteractWithTVReward",
+    "CheckComputerReward",
+    "HouseFullyExploredReward",
+    "ExitHouseReward",
+    "ExploreTownReward",
+    "TalkToNPCsReward",
+    "OakLabDiscoveryReward",
+    "AttemptRoute1Reward",
+    "OakEncounterReward",
+    "FollowOakToLabReward",
+    "ChooseStarterPokemonReward",
+    "RivalEncounterReward",
+    "FirstPokemonBattleReward",
+    "MenuDiscoveryReward",
+    "PokemonMenuReward",
+    "BagDiscoveryReward",
+    "SaveGameReward",
+    "TryAllDirectionsReward",
+    "DoorInteractionReward",
+    "ObjectInteractionReward",
+    "SignReadingReward",
+    "CompleteTownExplorationReward",
+    "AllNPCsTalkedToReward",
+    "ReadyForAdventureReward",
+    # Exploration
+    "NewAreaDiscoveryReward",
+    "AreaCompletionReward",
+    "RouteCompletionReward",
+    "BuildingEntryReward",
+    "HiddenAreaDiscoveryReward",
+    "HiddenItemFoundReward",
+    "FirstItemOfTypeReward",
+    "RareItemDiscoveryReward",
+    "KeyItemAcquisitionReward",
+    "FirstWarpUsageReward",
+    "PCUsageReward",
+    "VendingMachineReward",
+    # Social & NPC
+    "NewNPCConversationReward",
+    "HelpfulInformationReceivedReward",
+    "StoryDialogueProgressionReward",
+    "ProfessorOakInteractionsReward",
+    "NPCGiftReceivedReward",
+    "TradeCompletionReward",
+    "NameRaterUsageReward",
+    # Pokemon Collection
+    "FirstPokemonCaughtReward",
+    "NewSpeciesCaughtReward",
+    "RarePokemonCaughtReward",
+    "EvolutionStonePokemonReward",
+    "PokedexMilestonesReward",
+    "AreaPokedexCompletionReward",
+    "TypeCollectionReward",
+    "PokemonEvolutionReward",
+    "LevelMilestonesReward",
+    "MoveLearningReward",
+    "TMHMTeachingReward",
+    # Battle & Combat
+    "WildPokemonDefeatedReward",
+    "TrainerBattleVictoryReward",
+    "GymLeaderVictoryReward",
+    "EliteFourMemberVictoryReward",
+    "ChampionVictoryReward",
+    "TypeAdvantageUsageReward",
+    "CriticalHitReward",
+    "StatusEffectUsageReward",
+    "OHKOReward",
+    "FlawlessVictoryReward",
+    "UnderleveledVictoryReward",
+    "BattleStreakReward",
+    # Story & Achievement
+    "GymBadgeEarnedReward",
+    "HMAcquisitionReward",
+    "EliteFourAccessReward",
+    "HallOfFameEntryReward",
+    "RivalBattleCompletionReward",
+    "TeamRocketDefeatReward",
+    "LegendaryEncounterReward",
+    "SilphCoCompletionReward",
+    "SafariZoneSuccessReward",
+    "GameCornerPrizesReward",
+    "FossilRevivalReward",
+    # Economy & Resources
+    "FirstEarningsReward",
+    "WealthMilestonesReward",
+    "SmartPurchasesReward",
+    "RarePurchaseReward",
+    "InventoryOrganizationReward",
+    "HealingItemUsageReward",
+    "PokeballEfficiencyReward",
+    # Efficiency & Optimization
+    "FastTravelUsageReward",
+    "OptimalRoutingReward",
+    "PuzzleSolvingReward",
+    "MoveEffectivenessReward",
+    "EvolutionTimingReward",
+    "HMUsageReward",
+    # Novelty & Exploration
+    "FirstBattleReward",
+    "FirstPokemonCenterVisitReward",
+    "FirstPokemartPurchaseReward",
+    "FirstSaveReward",
+    "MenuExplorationReward",
+    "ButtonDiscoveryReward",
+    "FeatureDiscoveryReward",
+    # Adaptive & Learning
+    "MistakeRecoveryReward",
+    "StrategyAdaptationReward",
+    "ResourceConservationReward",
+    "PatternRecognitionReward",
+    "RouteOptimizationReward",
+    "BattlePreparationReward",
+    # Composite & Milestone
+    "PerfectGymRunReward",
+    "AreaMasteryReward",
+    "SpeedrunMilestonesReward",
+    "ExplorationStreakReward",
+    "BattleWinStreakReward",
+    "PerfectDayReward",
+]

synth_ai/environments/examples/red/engine_helpers/reward_library/adaptive_rewards.py

@@ -0,0 +1,56 @@
+"""
+Adaptive & Learning Reward Components
+
+Rewards for improvement over time and meta-learning.
+"""
+
+from synth_ai.environments.environment.rewards.core import RewardComponent
+from typing import Dict, Any
+
+
+class MistakeRecoveryReward(RewardComponent):
+    """Reward for correcting previous errors - +10 points"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Placeholder - would need mistake tracking and recovery detection
+        return 0.0
+
+
+class StrategyAdaptationReward(RewardComponent):
+    """Reward for changing tactics based on type matchups - +15 points"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Placeholder - would need strategy analysis
+        return 0.0
+
+
+class ResourceConservationReward(RewardComponent):
+    """Reward for efficient PP/item usage - +8 points"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Placeholder - would need resource usage tracking
+        return 0.0
+
+
+class PatternRecognitionReward(RewardComponent):
+    """Reward for recognizing and adapting to trainer patterns - +12 points"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Placeholder - would need pattern analysis
+        return 0.0
+
+
+class RouteOptimizationReward(RewardComponent):
+    """Reward for finding better paths on repeat visits - +20 points"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Placeholder - would need route comparison
+        return 0.0
+
+
+class BattlePreparationReward(RewardComponent):
+    """Reward for healing/preparing before major battles - +15 points"""
+
+    async def score(self, state: Dict[str, Any], action: Dict[str, Any]) -> float:
+        # Placeholder - would need preparation detection
+        return 0.0