goapauto 0.1.0__py3-none-any.whl

goapauto-0.1.0.dist-info/METADATA

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: goapauto
+Version: 0.1.0
+Summary: A flexible Goal-Oriented Action Planning (GOAP) system for game AI and planning problems, featuring A* search, efficient state management, and modular design.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# GOAP Planner
+
+A flexible Goal-Oriented Action Planning (GOAP) system designed for game AI, but applicable to any planning problem. This implementation provides a clean, modular architecture for defining actions, goals, and world states to create intelligent AI behaviors.
+
+## Features
+
+- 🎯 Goal-oriented planning with customizable actions and preconditions
+- 🧠 A* search algorithm for optimal plan generation
+- ⚡ Efficient state management and caching
+- 📊 Built-in planning statistics and debugging
+- 🧩 Modular design for easy extension
+- 🎮 Example implementations included
+
+## Installation
+
+### From PyPI
+```bash
+uv add goapauto
+```
+
+### From Source
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/IAmNo1Special/goapauto.git
+   cd goapauto
+   ```
+
+## Quick Start
+
+```python
+from models.goap_planner import Planner, PlanResult
+from models.goal import Goal
+from models.actions import Action, Actions
+from models.worldstate import WorldState
+
+# Define your initial state using WorldState for better type safety and validation
+initial_state = WorldState({
+    'is_open': False,
+    'is_focused': False,
+    'has_key': True,
+    'energy': 100
+})
+
+# Create actions collection
+actions = Actions()
+
+# Add actions with proper typing and validation
+try:
+    actions.add_action(
+        name="open_door",
+        preconditions={'is_open': False, 'has_key': True},
+        effects={'is_open': True},
+        cost=1.0
+    )
+    
+    actions.add_action(
+        name="consume_energy",
+        preconditions={'energy': (lambda x: x > 0)},
+        effects={'energy': (lambda x: x - 10)},
+        cost=1.0
+    )
+except (ValueError, TypeError) as e:
+    print(f"Error creating actions: {e}")
+    raise
+
+# Create a goal with validation
+try:
+    goal = Goal(
+        name="Open Door",
+        priority=1,
+        target_state={'is_open': True}
+    )
+except ValueError as e:
+    print(f"Invalid goal: {e}")
+    raise
+
+# Create and run the planner
+planner = Planner(actions)
+plan, message = planner.generate_plan(initial_state, goal)
+
+# The planner will automatically display the plan and statistics
+# You can access the plan and execute it if needed
+if plan is not None:
+    current_state = initial_state.copy()
+    for i, action_name in enumerate(plan, 1):
+        action = actions.get_action(action_name)
+        print(f"\nStep {i}: {action_name}")
+        current_state = action.apply(current_state)
+        print(f"New state: {current_state}")
+```
+
+## Project Structure
+
+- `/models` - Core GOAP implementation
+  - `goap_planner.py` - Main planner logic
+  - `goal.py` - Goal definition and management
+  - `actions.py` - Action definitions
+  - `worldstate.py` - World state management
+  - `node.py` - Search node implementation
+
+- `/examples` - Example implementations
+  - `example1.py` - Basic usage example
+  - `example2.py` - Advanced scenario
+
+## Advanced Usage
+
+### Working with WorldState
+
+```python
+from models.worldstate import WorldState
+
+# Create a state with validation
+state = WorldState({
+    'health': 100,
+    'has_weapon': True,
+    'enemy_visible': False
+})
+
+# Safe state updates
+state = state.merge({'health': 80})  # Returns new state
+state = state.copy()  # Create a deep copy
+
+# Check conditions
+if state.matches({'health': (lambda x: x > 50)}):
+    print("Health is above 50%")
+```
+
+### Creating Custom Actions
+
+Define actions using the `Action` class for better type safety and validation:
+
+```python
+from models.actions import Action, Actions
+
+# Create a single action
+open_door = Action(
+    name="open_door",
+    preconditions={'door_locked': False},
+    effects={'door_open': True},
+    cost=1.0
+)
+
+# Or use the Actions collection to manage multiple actions
+actions = Actions()
+actions.add_action(
+    name="unlock_door",
+    preconditions={'has_key': True},
+    effects={'door_locked': False},
+    cost=1.5
+)
+
+# Add multiple actions at once
+actions.add_actions([
+    ("pick_up_item", {"near_item": True}, {"has_item": True}, 1.0),
+    ("use_item", {"has_item": True}, {"effect_applied": True}, 1.0)
+])
+
+# Check if an action is applicable in a given state
+if open_door.is_applicable(current_state):
+    new_state = open_door.apply(current_state)
+```
+
+### Defininig Goals with target states and priorities
+
+```python
+from models.goal import Goal
+
+goal = Goal(
+    name="Achieve Objective",
+    priority=1,
+    target_state={
+        'objective_complete': True
+    }
+)
+```
+
+### Defining Goals with Conditions
+
+```python
+from models.goal import Goal
+
+# Simple goal
+goal = Goal(
+    name="Defeat Enemy",
+    priority=1,
+    target_state={
+        'enemy_defeated': True,
+        'health': (lambda x: x > 0)  # Must have health remaining
+    }
+)
+
+# Goal with custom validation
+try:
+    goal.validate()
+except ValueError as e:
+    print(f"Invalid goal: {e}")
+```
+
+### Working with Plan Results
+
+```python
+# After generating a plan
+if plan is not None:
+    print(f"Plan found with {len(plan)} actions")
+    print(f"Total cost: {planner.stats.total_cost}")
+    print(f"Nodes expanded: {planner.stats.nodes_expanded}")
+    print(f"Planning time: {planner.stats.execution_time:.4f}s")
+    
+    # Access individual plan steps
+    for i, action_name in enumerate(plan, 1):
+        action = actions.get_action(action_name)
+        print(f"{i}. {action_name} (cost: {action.cost})")
+    
+    # Execute the plan and track state changes
+    current_state = initial_state.copy()
+    for i, action_name in enumerate(plan, 1):
+        action = actions.get_action(action_name)
+        print(f"\nStep {i}: {action_name}")
+        current_state = action.apply(current_state)
+        print(f"State after action: {current_state}")
+```
+
+### Custom Heuristics
+
+```python
+from models.goap_planner import Planner
+
+def custom_heuristic(state, goal_state):
+    """Custom heuristic function for A* search."""
+    # Implement your heuristic logic here
+    # Lower values mean closer to goal
+    return 0  # Default to Dijkstra's algorithm
+
+planner = Planner(actions, heuristic=custom_heuristic)
+```
+
+## Performance Tips
+
+1. **State Design**:
+   - Keep state keys simple and consistent
+   - Use immutable state objects for better caching
+
+2. **Action Design**:
+   - Make preconditions as specific as possible
+   - Use lambda functions for dynamic conditions
+   - Keep effects minimal and focused
+
+3. **Debugging**:
+   - Enable debug logging for detailed planning info
+   - Check PlanResult.stats for performance metrics
+   - Use state validation to catch issues early
+
+## Troubleshooting
+
+### Common Issues
+
+1. **No Plan Found**
+   - Check if actions' preconditions are met
+   - Verify the goal is achievable
+   - Increase max_iterations if needed
+
+2. **Performance Problems**
+   - Check for infinite state spaces
+   - Add more specific preconditions
+   - Consider using a custom heuristic
+
+
+## Running Examples
+
+```bash
+# Run basic example
+python examples/example1.py
+
+# Run advanced example
+python examples/example2.py
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

goapauto-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+models/actions.py,sha256=3dMiKlkwD1wx6b3AulCHk3MJEW4fM52b56jXsvfxvr0,9118
+models/goal.py,sha256=IGrrFZoFSs4Ct0W-pjm8ZGYjPpJly5iis1BDECrJ76k,6275
+models/goap_planner.py,sha256=Gih0yDipsqehwTLb8m9mYm5JRoVLQAr6S5dgXbf_Fgc,10791
+models/node.py,sha256=w3A2Qk9queVNa4Bh9Vv2LsM2z-wx8Jodf8LnGXS-V1s,7558
+models/worldstate.py,sha256=FzTMtLE5Cxa3sLAst4qabehMb7MsEkaELU2vctbhuW8,9052
+goapauto-0.1.0.dist-info/METADATA,sha256=QTj-YkPf5CAwIsY3VrsuDgLFF-7931jhHd3muCAXl5Y,7711
+goapauto-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+goapauto-0.1.0.dist-info/top_level.txt,sha256=vH5ByFtkqB2bXlXOuK5zaaM_1GFEE9six0KgGIdPaU0,7
+goapauto-0.1.0.dist-info/RECORD,,

goapauto-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

goapauto-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+models

models/actions.py

@@ -0,0 +1,231 @@
+import copy
+import logging
+from typing import Any, Dict, List, Optional, Type, TypeVar, Union
+from dataclasses import dataclass
+
+from models.worldstate import WorldState
+
+logger = logging.getLogger(__name__)
+T = TypeVar('T', bound='Action')
+
+@dataclass
+class Action:
+    """Represents an action the agent can take.
+    
+    Attributes:
+        name: Unique identifier for the action
+        preconditions: Dictionary of state requirements that must be met for the action to be applicable
+        effects: Dictionary of state changes that result from applying this action
+        cost: The cost of executing this action (used for pathfinding)
+    """
+    name: str
+    preconditions: Dict[str, Any]
+    effects: Dict[str, Any]
+    cost: int = 1
+    
+    def __post_init__(self) -> None:
+        """Validate the action after initialization."""
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise ValueError("Action name must be a non-empty string")
+        if not isinstance(self.preconditions, dict):
+            raise TypeError("Preconditions must be a dictionary")
+        if not isinstance(self.effects, dict):
+            raise TypeError("Effects must be a dictionary")
+        if not isinstance(self.cost, (int, float)) or self.cost <= 0:
+            raise ValueError("Cost must be a positive number")
+
+    def is_applicable(self, state: Any) -> bool:
+        """Check if this action can be applied to the given state.
+        
+        Args:
+            state: The current world state to check against
+            
+        Returns:
+            bool: True if all preconditions are met, False otherwise
+        """
+        if not hasattr(state, '__dict__'):
+            raise TypeError("State must be an object with attributes")
+            
+        logger.debug('Checking applicability of action: %s', self.name)
+        try:
+            for attr, expected_value in self.preconditions.items():
+                if not hasattr(state, attr):
+                    logger.debug('State missing required attribute: %s', attr)
+                    return False
+                if getattr(state, attr) != expected_value:
+                    logger.debug('Precondition not met: %s != %s', 
+                               getattr(state, attr), expected_value)
+                    return False
+            return True
+        except Exception as e:
+            logger.error('Error checking action applicability: %s', str(e), exc_info=True)
+            return False
+
+    def apply(self, state: Any) -> Any:
+        """Apply this action to the current state and return a new state.
+        
+        Args:
+            state: The current world state to apply the action to
+            
+        Returns:
+            A new state with the action's effects applied
+            
+        Raises:
+            ValueError: If the action cannot be applied to the current state
+        """
+        if not self.is_applicable(state):
+            raise ValueError(f"Action {self.name} is not applicable to the current state")
+            
+        logger.info('Applying action: %s', self.name)
+        try:
+            # Create a deep copy to avoid modifying the original state
+            new_state = copy.deepcopy(state)
+            
+            # Apply each effect to the new state
+            for attr, value in self.effects.items():
+                setattr(new_state, attr, value)
+                
+            logger.debug('New state after %s: %s', self.name, new_state)
+            return new_state
+            
+        except Exception as e:
+            logger.error('Failed to apply action %s: %s', self.name, str(e), exc_info=True)
+            raise
+
+    def __str__(self) -> str:
+        """Return a string representation of the action."""
+        return (f"{self.__class__.__name__}('{self.name}', "
+                f"preconditions={self.preconditions}, "
+                f"effects={self.effects}, cost={self.cost})")
+                
+    def __repr__(self) -> str:
+        """Return the canonical string representation of the action."""
+        return str(self)
+
+class Actions:
+    """Manages a collection of available actions for the GOAP planner.
+    
+    This class provides methods to add, retrieve, and manage actions that can be
+    used by the planner to achieve goals. It ensures that all actions are valid
+    and provides efficient lookup and iteration capabilities.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize an empty collection of actions."""
+        self._actions: List[Action] = []
+
+    def add_action(self, name: str, preconditions: Dict[str, Any], 
+                  effects: Dict[str, Any], cost: int = 1) -> None:
+        """Add a single action to the collection.
+        
+        Args:
+            name: Unique identifier for the action
+            preconditions: Dictionary of state requirements for the action
+            effects: Dictionary of state changes caused by the action
+            cost: The cost of executing this action (default: 1)
+            
+        Raises:
+            ValueError: If an action with the same name already exists
+            TypeError: If any parameter has an invalid type
+        """
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("Action name must be a non-empty string")
+            
+        if self.get_action(name) is not None:
+            raise ValueError(f"Action with name '{name}' already exists")
+            
+        try:
+            action = Action(name, preconditions, effects, cost)
+            self._actions.append(action)
+            logger.debug('Added action: %s', name)
+        except Exception as e:
+            logger.error('Failed to add action %s: %s', name, str(e))
+            raise
+    
+    def add_actions(self, action_definitions: List[tuple]) -> None:
+        """Add multiple actions to the collection.
+        
+        Args:
+            action_definitions: List of action definitions where each definition is a tuple
+                in the format (name: str, preconditions: dict, effects: dict, cost: int)
+                
+        Example:
+            actions = Actions()
+            actions.add_actions([
+                ("open_door", {"door_locked": False}, {"door_open": True}, 1),
+                ("unlock_door", {"has_key": True}, {"door_locked": False}, 2)
+            ])
+        """
+        if not isinstance(action_definitions, (list, tuple)):
+            raise TypeError("action_definitions must be a list or tuple")
+            
+        for i, action_def in enumerate(action_definitions):
+            try:
+                if not isinstance(action_def, (list, tuple)) or len(action_def) != 4:
+                    raise ValueError(f"Action definition at index {i} must be a 4-tuple "
+                                    "(name, preconditions, effects, cost)")
+                self.add_action(*action_def)
+            except Exception as e:
+                logger.error('Error adding action at index %d: %s', i, str(e))
+                raise
+    
+    def get_action(self, name: str) -> Optional[Action]:
+        """Retrieve an action by its name.
+        
+        Args:
+            name: The name of the action to retrieve
+            
+        Returns:
+            The Action object if found, None otherwise
+        """
+        if not isinstance(name, str):
+            raise TypeError("Action name must be a string")
+            
+        for action in self._actions:
+            if action.name == name:
+                return action
+        return None
+    
+    def get_actions(self) -> List[Action]:
+        """Get a list of all actions in the collection.
+        
+        Returns:
+            A new list containing all Action objects
+        """
+        return self._actions.copy()
+    
+    def clear_actions(self) -> None:
+        """Remove all actions from the collection."""
+        self._actions.clear()
+        logger.info('Cleared all actions')
+    
+    def filter_actions(self, state: Any) -> List[Action]:
+        """Get a list of all actions that can be applied to the given state.
+        
+        Args:
+            state: The state to check against action preconditions
+            
+        Returns:
+            A list of applicable Action objects
+        """
+        return [action for action in self._actions if action.is_applicable(state)]
+    
+    def __iter__(self) -> 'Actions':
+        """Return an iterator over all actions."""
+        return iter(self._actions)
+    
+    def __len__(self) -> int:
+        """Return the number of actions in the collection."""
+        return len(self._actions)
+    
+    def __contains__(self, name: str) -> bool:
+        """Check if an action with the given name exists."""
+        return self.get_action(name) is not None
+    
+    def __str__(self) -> str:
+        """Return a string representation of the actions collection."""
+        return f"Actions({len(self._actions)} actions available)"
+    
+    def __repr__(self) -> str:
+        """Return a detailed string representation of the actions collection."""
+        return f"<{self.__class__.__name__} with {len(self._actions)} actions>"