Metadata-Version: 2.4
Name: abtree
Version: 0.3.2
Summary: High-performance asynchronous behavior tree framework with behavior forest collaboration,
Author-email: aipanda <iepanda@outlook.com>
License: MIT License
        
        Copyright (c) 2025 abtree
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/xiongwc/abtree
Project-URL: Repository, https://github.com/xiongwc/abtree
Project-URL: Documentation, https://abtree.readthedocs.io
Project-URL: Issues, https://github.com/xiongwc/abtree/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncio
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: lxml>=4.6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: safety>=2.0.0; extra == "dev"
Requires-Dist: pip-tools>=7.0.0; extra == "dev"
Provides-Extra: cli
Requires-Dist: click>=8.0.0; extra == "cli"
Requires-Dist: rich>=12.0.0; extra == "cli"
Dynamic: license-file

🚀 ABTree

**Asynchronous behavior tree framework built on Python asyncio, designed for intelligent decision systems with declarative programming paradigm**

[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/downloads/)[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Stars](https://img.shields.io/github/stars/xiongwc/abtree?style=social)](https://github.com/xiongwc/abtree/stargazers)[![Forks](https://img.shields.io/github/forks/xiongwc/abtree?style=social)](https://github.com/xiongwc/abtree/network/members)

[中文](README.CN.md) | **English**

---

## 📑 Table of Contents

- [✨ Core Features](#-core-features)
- [🎬 Quick Start](#-quick-start)
- [📖 Documentation](#-documentation)
- [🔧 Technology Stack](#-technology-stack)
- [🗺️ Roadmap](#️-roadmap)
- [🤝 Contributing](#-contributing)
- [📜 License](#-license)

---

## ✨ Core Features

| 🚀 **Async Engine** | 🎯 **Node System** | 💾 **Data Management** | 🌲 **Behavior Forest** |
|:---:|:---:|:---:|:---:|
| Based on asyncio
High Performance Concurrency | Rich Node Types
Dynamic Registration | Blackboard System
Event Driven | Multi-tree Collaboration
Internal Communication Modes |

### ⚡ Asynchronous Behavior Tree Engine
- **High Performance Async Execution** - Concurrent node scheduling based on Python asyncio
- **Smart Tick Management** - Automated execution cycle management and resource control
- **Event Driven Architecture** - Asynchronous event system supporting real-time response
- **Memory Optimization** - Efficient state management and garbage collection

### 🎯 Rich Node System
- **Composite Nodes** - Sequence, Selector, Parallel and other classic control flows
- **Decorator Nodes** - Inverter, Repeater, UntilSuccess and other behavior modifiers
- **Action Nodes** - Action, Log, Wait, SetBlackboard and other execution units
- **Condition Nodes** - Condition, CheckBlackboard, Compare and other judgment logic
- **Dynamic Registration** - Runtime node type registration and extension mechanism

### 💾 Smart Data Management
- **Blackboard System** - Cross-node data sharing and state persistence
- **Event System** - Asynchronous event listening, publishing and subscription mechanism
- **State Management** - Complete tracking of behavior tree execution state
- **Data Validation** - Type-safe data access and modification

### 🌲 Behavior Forest Collaboration
- **Multi-tree Coordination** - Multiple behavior trees working together as a forest
- **Communication Modes** - Pub/Sub, Req/Resp, Shared Blackboard, State Monitoring, Behavior Invocation, Task Board
- **Forest Management** - Centralized forest configuration and lifecycle management
- **Performance Monitoring** - Real-time performance analysis and optimization suggestions

---

## 🎬 Quick Start

### 🔧 Environment Setup

```bash
# Clone repository
git clone https://github.com/xiongwc/abtree.git
cd abtree

# Install dependencies
pip install -e .
```

### 📝 Basic Usage

#### 🚀 Method 1: Programmatic Building

```python
import asyncio
from abtree import BehaviorTree, Sequence, Selector, Action, Condition
from abtree.core import Status

# Define action nodes
class OpenDoor(Action):
    async def execute(self, blackboard):
        print("Opening door")
        return Status.SUCCESS

class CloseDoor(Action):
    async def execute(self, blackboard):
        print("Closing door")
        return Status.SUCCESS

# Define condition nodes
class IsDoorOpen(Condition):
    async def evaluate(self, blackboard):
        return blackboard.get("door_open", False)

# Build behavior tree
root = Selector("Robot Decision")
root.add_child(Sequence("Door Control Sequence"))
root.children[0].add_child(IsDoorOpen("Check Door Status"))
root.children[0].add_child(CloseDoor("Close Door"))

# Create behavior tree instance
tree = BehaviorTree()
tree.load_from_node(root)

# Execute
async def main():
    blackboard = tree.blackboard
    blackboard.set("door_open", True)
    
    result = await tree.tick()
    print(f"Execution result: {result}")

asyncio.run(main())
```

#### 📄 Method 2: Declarative XML Configuration

```python
import asyncio
from abtree import load_from_xml_string

# Declarative XML: Express behavior logic in a readable, structured format
xml_string = '''<BehaviorTree name="Robot Decision">
    <Selector name="Robot Decision">
        <Sequence name="Door Control Sequence">
            <CheckBlackboard name="Check Door Status" key="door_open" expected_value="true" />
            <Log name="Close Door Log" message="Door detected open, preparing to close" />
            <Wait name="Close Door Wait" duration="1.0" />
        </Sequence>
    </Selector>
</BehaviorTree>'''

# Load behavior tree from declarative XML configuration
tree = load_from_xml_string(xml_string)

# Execute
async def main():
    blackboard = tree.blackboard
    blackboard.set("door_open", True)
    
    result = await tree.tick()
    print(f"Execution result: {result}")

asyncio.run(main())
```

### 🌲 Behavior Forest Example

```python
import asyncio
from abtree import (
    BehaviorForest, ForestNode, ForestNodeType,
    PubSubMiddleware, SharedBlackboardMiddleware,
    BehaviorTree, Sequence, Selector, Action, Condition
)
from abtree.core import Status

# Simple robot action node
class RobotAction(Action):
    def __init__(self, name: str, action_type: str):
        super().__init__(name)
        self.action_type = action_type
    
    async def execute(self, blackboard):
        print(f"Robot {self.action_type}")
        if self.action_type == "cleaning":
            blackboard.set("cleaning_needed", False)
        return Status.SUCCESS

# Simple condition node
class SimpleCondition(Condition):
    def __init__(self, name: str, key: str, default: bool = True):
        super().__init__(name)
        self.key = key
        self.default = default
    
    async def evaluate(self, blackboard):
        return blackboard.get(self.key, self.default)

def create_robot_tree(robot_id: str) -> BehaviorTree:
    """Create a simple robot behavior tree"""
    root = Selector(f"Robot_{robot_id}")
    
    # Cleaning sequence
    cleaning_seq = Sequence("Cleaning")
    cleaning_seq.add_child(SimpleCondition("Check Cleaning", "cleaning_needed"))
    cleaning_seq.add_child(RobotAction("Clean", "cleaning"))
    cleaning_seq.add_child(RobotAction("Navigate", "navigating"))
    root.add_child(cleaning_seq)
    
    tree = BehaviorTree()
    tree.load_from_node(root)
    return tree

async def main():
    # Create behavior forest
    forest = BehaviorForest("Robot Forest")
    
    # Add middleware
    forest.add_middleware(PubSubMiddleware("PubSub"))
    forest.add_middleware(SharedBlackboardMiddleware("Shared Blackboard"))
    
    # Add robot nodes
    for robot_id in ["R1", "R2", "R3"]:
        tree = create_robot_tree(robot_id)
        node = ForestNode(
            name=f"Robot_{robot_id}",
            tree=tree,
            node_type=ForestNodeType.WORKER,
            capabilities={"cleaning", "navigation"}
        )
        forest.add_node(node)
    
    # Start forest
    await forest.start()
    
    # Execute ticks
    for i in range(3):
        results = await forest.tick()
        print(f"Tick {i+1}: {results}")
        await asyncio.sleep(0.5)
    
    await forest.stop()

if __name__ == "__main__":
    asyncio.run(main())
```

---

## 📖 Documentation

- **📚 Quick Start**: [examples/](examples/)
- **🔧 API Reference**: [docs/api.md](docs/api.md)
- **🛠️ CLI Tools**: [cli/](cli/)
- **🧪 Testing**: [tests/](tests/)

### 📁 Project Structure

```
abtree/
├── abtree/                     # 📦 Core package
│   ├── core/                   # 🔧 Core functionality
│   ├── engine/                 # ⚙️ Engine system
│   ├── forest/                 # 🌲 Behavior forest
│   ├── nodes/                  # 🎯 Node implementations
│   ├── parser/                 # 📝 Configuration parsing
│   ├── registry/               # 📋 Node registration
│   └── utils/                  # 🔧 Utilities
├── cli/                        # 🖥️ Command line tools
├── docs/                       # 📖 Documentation
├── examples/                   # 📚 Example code
├── tests/                      # 🧪 Test suite
├── scripts/                    # 📜 Script tools
├── test_reports/               # 📊 Test reports
└── pyproject.toml              # ⚙️ Build and dependency configuration
```

---

## 🔧 Technology Stack

| Component | Technology | Version |
|-----------|------------|---------|
| **Language** | Python | 3.8+ |
| **Async Framework** | asyncio | Built-in |
| **Data Validation** | Pydantic | 2.0+ |
| **XML Processing** | xml.etree | Built-in |
| **Testing** | pytest | 7.0+ |
| **Type Checking** | mypy | 1.0+ |

### 📋 Code Standards

- Follow **PEP 8** coding standards
- Use **Google style** docstrings
- Add **type annotations** for all functions
- Write **unit tests** for key functionality

---

## 🗺️ Roadmap

- [x] ✅ **v0.1** - Core asynchronous behavior tree framework
- [x] ✅ **v0.2** - XML configuration support
- [x] ✅ **v0.3** - Event system and blackboard optimization
- [ ] 🎯 **v0.4** - Advanced node types

---

## 🤝 Contributing

1. Fork the project repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 🙏 Acknowledgments

Inspiration from [BehaviorTree.CPP](https://github.com/BehaviorTree/BehaviorTree.CPP).

---

## 📜 License

This project is licensed under the [MIT License](LICENSE).

---

**⭐ If this project helps you, please give us a Star to support development! ⭐**

[![GitHub Discussions](https://img.shields.io/github/discussions/xiongwc/abtree?color=blue&logo=github)](https://github.com/xiongwc/abtree/discussions)[![GitHub Issues](https://img.shields.io/github/issues/xiongwc/abtree?color=green&logo=github)](https://github.com/xiongwc/abtree/issues)[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/xiongwc/abtree?color=orange&logo=github)](https://github.com/xiongwc/abtree/pulls)

