grader&rewards

grader.py

@@ -0,0 +1,120 @@
+"""
+Grader module for the Cat Rescue Reinforcement Learning environment.
+Evaluates agent performance based on episode logs.
+"""
+
+class CatRescueGrader:
+    """
+    Evaluates an episode log from the Cat Rescue environment and produces
+    structured grading results and human-readable summaries.
+    """
+
+    def grade(self, episode_log: dict) -> dict:
+        """
+        Grades an episode based on the provided episode log.
+        
+        Args:
+            episode_log (dict): A dictionary containing:
+                - total_steps (int): Total steps taken by the agent.
+                - cats_rescued (int): Number of cats successfully rescued.
+                - total_cats (int): Total number of cats in the episode.
+                - total_reward (float): Total reward accumulated.
+                - hit_walls (int): Number of times the agent hit a wall.
+                - rescue_log (list of bool): True if rescued, one per cat.
+                
+        Returns:
+            dict: A structured evaluation result containing:
+                - cats_rescued_count (int)
+                - all_cats_rescued (bool)
+                - rescue_details (list of dict)
+                - total_steps (int)
+                - wall_hits (int)
+                - total_reward (float)
+                - efficiency_score (float)
+                - passed (bool)
+                - grade_label (str)
+        """
+        total_steps = episode_log.get("total_steps", 0)
+        cats_rescued = episode_log.get("cats_rescued", 0)
+        total_cats = episode_log.get("total_cats", 0)
+        total_reward = episode_log.get("total_reward", 0.0)
+        hit_walls = episode_log.get("hit_walls", 0)
+        rescue_log = episode_log.get("rescue_log", [])
+        
+        all_cats_rescued = (cats_rescued == total_cats) and (total_cats > 0)
+        passed = all_cats_rescued
+        
+        rescue_details = [{"cat_id": i, "rescued": rescued} for i, rescued in enumerate(rescue_log)]
+        
+        efficiency_score = 0.0
+        if total_steps > 0:
+            efficiency_score = min(1.0, float(cats_rescued) / total_steps)
+            
+        if passed and efficiency_score >= 0.8:
+            grade_label = "PERFECT"
+        elif passed and efficiency_score >= 0.5:
+            grade_label = "GOOD"
+        elif cats_rescued > 0 and not passed:
+            grade_label = "PARTIAL"
+        elif cats_rescued == 0:
+            grade_label = "FAIL"
+        else:
+            # Fallback if passed but efficiency < 0.5
+            grade_label = "PASS"
+            
+        return {
+            "cats_rescued_count": cats_rescued,
+            "all_cats_rescued": all_cats_rescued,
+            "rescue_details": rescue_details,
+            "total_steps": total_steps,
+            "wall_hits": hit_walls,
+            "total_reward": total_reward,
+            "efficiency_score": efficiency_score,
+            "passed": passed,
+            "grade_label": grade_label
+        }
+
+    def summary(self, grade_result: dict) -> str:
+        """
+        Generates a human-readable summary of the evaluation result.
+        
+        Args:
+            grade_result (dict): The result dictionary produced by the grade method.
+            
+        Returns:
+            str: A formatted summary string.
+        """
+        status = "PASSED" if grade_result.get("passed") else "FAILED"
+        grade_label = grade_result.get("grade_label", "UNKNOWN")
+        cats_rescued = grade_result.get("cats_rescued_count", 0)
+        total_steps = grade_result.get("total_steps", 0)
+        efficiency = grade_result.get("efficiency_score", 0.0)
+        
+        return (
+            f"--- Grader Summary ---\n"
+            f"Status: {status}\n"
+            f"Grade Label: {grade_label}\n"
+            f"Cats Rescued: {cats_rescued}\n"
+            f"Total Steps: {total_steps}\n"
+            f"Efficiency Score: {efficiency:.2f}\n"
+            f"----------------------"
+        )
+
+
+if __name__ == "__main__":
+    sample_log = {
+        "total_steps": 5,
+        "cats_rescued": 3,
+        "total_cats": 3,
+        "total_reward": 15.5,
+        "hit_walls": 1,
+        "rescue_log": [True, True, True]
+    }
+    
+    grader = CatRescueGrader()
+    result = grader.grade(sample_log)
+    print("Structured Result:")
+    import json
+    print(json.dumps(result, indent=2))
+    print("\nSummary:")
+    print(grader.summary(result))

rewards.py

@@ -0,0 +1,92 @@
+"""
+Rewards module for the Cat Rescue Reinforcement Learning environment.
+Defines reward constants and computes rewards for different agent events.
+"""
+
+class CatRescueRewards:
+    """
+    Manages and calculates rewards for the Cat Rescue environment.
+    """
+    STEP_PENALTY = -0.1
+    WALL_HIT_PENALTY = -0.3
+    CAT_RESCUED_REWARD = 1.0
+    ALL_CATS_BONUS = 2.0
+
+    def calculate(self, event: str, context: dict = None) -> float:
+        """
+        Calculates the appropriate reward for an event.
+        
+        Args:
+            event (str): The name of the event ("step", "wall_hit", "cat_rescued", "all_cats_rescued").
+            context (dict, optional): Additional context for the event (e.g., cats_remaining). Defaults to None.
+            
+        Returns:
+            float: The reward value for the selected event. Returns 0.0 for unknown events.
+        """
+        if context is None:
+            context = {}
+            
+        if event == "step":
+            return self.STEP_PENALTY
+        elif event == "wall_hit":
+            return self.WALL_HIT_PENALTY
+        elif event == "cat_rescued":
+            return self.CAT_RESCUED_REWARD
+        elif event == "all_cats_rescued":
+            # If all cats rescued, return CAT_RESCUED_REWARD plus ALL_CATS_BONUS combined
+            return self.CAT_RESCUED_REWARD + self.ALL_CATS_BONUS
+        else:
+            return 0.0
+
+    def calculate_episode_total(self, events: list) -> float:
+        """
+        Calculates the total cumulative reward for a list of event strings.
+        
+        Args:
+            events (list of str): A list of event strings that occurred during an episode.
+            
+        Returns:
+            float: The total reward accumulated, rounded to 2 decimal places.
+        """
+        total_reward = 0.0
+        for event in events:
+            total_reward += self.calculate(event)
+        return round(total_reward, 2)
+
+    def get_reward_table(self) -> dict:
+        """
+        Retrieves a dictionary mapping of all reward constants.
+        
+        Returns:
+            dict: The configured reward values for display or debugging purposes.
+        """
+        return {
+            "STEP_PENALTY": self.STEP_PENALTY,
+            "WALL_HIT_PENALTY": self.WALL_HIT_PENALTY,
+            "CAT_RESCUED_REWARD": self.CAT_RESCUED_REWARD,
+            "ALL_CATS_BONUS": self.ALL_CATS_BONUS
+        }
+
+
+if __name__ == "__main__":
+    rewards = CatRescueRewards()
+    
+    print("--- Reward Table ---")
+    for key, value in rewards.get_reward_table().items():
+        print(f"{key}: {value:>5}")
+        
+    print("\n--- Single Event Calculations ---")
+    print(f"step:              {rewards.calculate('step')}")
+    print(f"wall_hit:          {rewards.calculate('wall_hit')}")
+    print(f"cat_rescued:       {rewards.calculate('cat_rescued', {'cats_remaining': 1})}")
+    print(f"all_cats_rescued:  {rewards.calculate('all_cats_rescued', {'cats_remaining': 0})}")
+    print(f"unknown_event:     {rewards.calculate('sleep')}")
+    
+    print("\n--- Episode Total Calculation ---")
+    sample_events = [
+        "step", "step", "wall_hit", "step", 
+        "cat_rescued", "step", "step", "all_cats_rescued"
+    ]
+    total = rewards.calculate_episode_total(sample_events)
+    print(f"Events: {sample_events}")
+    print(f"Total Cumulative Reward: {total}")