Metadata-Version: 2.4
Name: reactflow
Version: 0.1.0
Summary: A lightweight, observable ReAct Agent framework
Author-email: AI Agent Research Team <team@example.com>
License: MIT
Project-URL: Homepage, https://github.com/example/reactflow
Project-URL: Documentation, https://github.com/example/reactflow#readme
Project-URL: Repository, https://github.com/example/reactflow
Project-URL: Issues, https://github.com/example/reactflow/issues
Keywords: ai,agent,llm,react,openai
Classifier: Development Status :: 3 - Alpha
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: chromadb
Requires-Dist: chromadb>=0.4.0; extra == "chromadb"
Provides-Extra: all
Requires-Dist: reactflow[chromadb,dev]; extra == "all"
Dynamic: license-file

# ReActFlow

<p align="center">
  <strong>A lightweight, observable ReAct Agent framework</strong>
</p>

<p align="center">
  <a href="README_CN.md">中文文档</a> | <a href="README.md">English</a>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#documentation">Documentation</a> •
  <a href="#contributing">Contributing</a>
</p>

---

## Features

- 🚀 **5-minute setup** - Get started with minimal code
- 🔍 **Fully observable** - Track every thought, action, and observation
- 💰 **Cost transparent** - Real-time token usage and cost tracking
- 🛠 **Easy customization** - Define tools with simple decorators
- 🔄 **Loop detection** - Automatic detection of stuck agents
- 📦 **Zero dependencies core** - Minimal dependencies for maximum flexibility

## Installation

```bash
pip install reactflow
```

## Quick Start

### Basic Usage

```python
from reactflow import Agent, Tool

# Define a custom tool
@Tool.define
def search(query: str) -> str:
    """Search for information"""
    return f"Results for: {query}"

# Create an agent
agent = Agent(tools=[search])

# Run a task
result = agent.run("What is the capital of France?")
print(result.answer)
```

### CLI Usage

```bash
# Run a single task
reactflow run "Calculate 25 * 17"

# Start interactive mode
reactflow interactive

# Export trajectory
reactflow run "What is Python?" --export trajectory.json
```

## Built-in Tools

ReActFlow comes with several built-in tools:

| Tool | Description |
|------|-------------|
| `search` | Search for information |
| `calculator` | Evaluate mathematical expressions |
| `datetime` | Get current date and time |
| `text_analyzer` | Analyze text in various ways |

## Custom Tools

Create custom tools easily:

```python
from reactflow import Tool

@Tool.define
def my_tool(query: str, count: int = 5) -> str:
    """
    My custom tool description.

    Args:
        query: The search query
        count: Number of results

    Returns:
        The result string
    """
    return f"Found {count} results for '{query}'"

# Use it
agent = Agent(tools=[my_tool])
```

## Tracking Execution

Every execution generates a complete trajectory:

```python
result = agent.run("What is 2+2?")

# Get the trajectory
trajectory = agent.get_trajectory()

# Export as Markdown
trajectory.export("my_trajectory.md", format="markdown")

# Or as JSON
trajectory.export("my_trajectory.json", format="json")
```

## Configuration

```python
agent = Agent(
    tools=[search, calculator],
    model="gpt-4",           # LLM model
    max_steps=10,            # Maximum reasoning steps
    debug=True,              # Enable debug output
    temperature=0.7,         # LLM temperature
)
```

## Architecture

```
ReActFlow Architecture
│
├── Agent              # Main interface
│   ├── Engine         # ReAct execution loop
│   ├── Tools          # Tool registry and execution
│   ├── State          # Execution state tracking
│   └── Memory         # Conversation memory
│
└── CLI                # Command-line interface
```

## Why ReActFlow?

| ReActFlow | Other Frameworks |
|-----------|------------------|
| 5 lines to start | 20+ lines of setup |
| Full observability | Black box execution |
| Debug-friendly | Hard to trace issues |
| Cost transparent | Unknown token usage |
| Minimal dependencies | Heavy dependency chains |

## Academic Reference

This framework implements the **ReAct (Reasoning + Acting)** paradigm from the following paper:

> **ReAct: Synergizing Reasoning and Acting in Language Models**
>
> Shunyu Yao, Jeffrey Zhao, Dian Yu, Nan Du, Izhak Shafran, Karthik R. Narasimhan, Yuan Cao
>
> *ICLR 2023*
>
> Paper: https://arxiv.org/abs/2210.03629

```bibtex
@inproceedings{yao2023react,
  title={ReAct: Synergizing Reasoning and Acting in Language Models},
  author={Yao, Shunyu and Zhao, Jeffrey and Yu, Dian and Du, Nan and Shafran, Izhak and Narasimhan, Karthik R and Cao, Yuan},
  booktitle={International Conference on Learning Representations (ICLR)},
  year={2023}
}
```

## License

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

```
MIT License

Copyright (c) 2024 AI Agent Research Team

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.
```

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

---

<p align="center">
  Made with ❤️ by AI Agent Research Team
</p>
