goapauto 0.1.0__tar.gz

goapauto-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,284 @@
+# 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.