Metadata-Version: 2.4
Name: reflexion-agent
Version: 0.1.0
Summary: Language Agents with Verbal Reinforcement Learning - Implementation of Reflexion paper
Author-email: AI Agent Research Team <team@example.com>
License: MIT
Project-URL: Homepage, https://github.com/Carlos-Zen/reflexion-agent
Project-URL: Documentation, https://github.com/Carlos-Zen/reflexion-agent#readme
Project-URL: Repository, https://github.com/Carlos-Zen/reflexion-agent
Keywords: ai,agent,reflexion,llm,self-improvement,reinforcement-learning
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.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"
Dynamic: license-file

# Reflexion Agent

<p align="center">
  <strong>Language Agents with Verbal Reinforcement Learning</strong>
</p>

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

<p align="center">
  <a href="#architecture">Architecture</a> •
  <a href="#installation">Installation</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#api-reference">API Reference</a>
</p>

---

A Python implementation of **Reflexion**, a framework that equips language agents with the ability to reflect on their failures and learn from them.

## Architecture

```
Reflexion Architecture
│
├── ReflexionAgent (Main Agent)
│   ├── Solves tasks using solve function
│   ├── Evaluates results using evaluate function
│   └── Learns from failures via reflection
│
├── Reflector (Reflection Generator)
│   ├── Analyzes failed attempts
│   ├── Extracts key insights
│   └── Generates improvement suggestions
│
├── ReflexionMemory (Reflection Storage)
│   ├── Stores reflections by task
│   ├── Retrieves relevant reflections
│   └── Formats for prompt inclusion
│
└── Types (Data Structures)
    ├── Task - Problem to solve
    ├── Attempt - Single solution attempt
    ├── Reflection - Failure analysis
    └── EvaluationResult - Success/failure status
```

## Core Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                    Reflexion Execution Loop                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   Task ──▶ Solve ──▶ Evaluate ──▶ Success? ──▶ Return Answer    │
│               │            │                                     │
│               │            └── No ──▶ Reflect ──▶ Store Memory   │
│               │                                    │             │
│               └────────────────────────────────────┘             │
│                         (Retry with reflections)                 │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Installation

```bash
pip install reflexion-agent
```

## Quick Start

```python
from reflexion import ReflexionAgent, Task, EvaluationResult, EvaluationStatus

# Define your solve function (typically uses an LLM)
def solve_fn(task, reflections):
    context = ""
    if reflections:
        context = f"\nPrevious insights:\n{reflections[0].to_prompt()}"

    # Your LLM call here
    # response = llm.generate(f"{task.question}{context}")
    return "your_answer"

# Define your evaluation function
def evaluate_fn(task, answer):
    # Check if answer is correct
    if answer == "expected_answer":
        return EvaluationResult(status=EvaluationStatus.SUCCESS, score=1.0)
    return EvaluationResult(
        status=EvaluationStatus.FAILURE,
        score=0.0,
        feedback="Answer is incorrect"
    )

# Create and run agent
agent = ReflexionAgent(solve_fn, evaluate_fn, max_attempts=3)
result = agent.run(Task(question="What is 2+2?"))

print(f"Success: {result.success}")
print(f"Answer: {result.final_answer}")
print(f"Attempts: {result.total_attempts}")
```

## CLI Usage

```bash
# Run a single task
reflexion run "What is the capital of France?"

# Start interactive mode
reflexion interactive

# Export trajectory
reflexion run "Solve this" --export trajectory.json
```

## API Reference

### ReflexionAgent

| Method | Description |
|--------|-------------|
| `run(task)` | Run Reflexion process for a task |
| `run_with_context(question, context)` | Convenience method with string input |
| `get_memory()` | Get the reflection memory |
| `get_reflections(task_id)` | Get stored reflections |
| `clear_memory()` | Clear all stored reflections |

### EvaluationStatus

- `SUCCESS` - Task completed correctly
- `FAILURE` - Task failed
- `PARTIAL` - Partially correct

## Academic Reference

Implementation of the **Reflexion** paper:

> **Reflexion: Language Agents with Verbal Reinforcement Learning**
>
> Noah Shinn, Federico Cassano, Ashwin Gopinath, Karthik R. Narasimhan, Shunyu Yao
>
> *NeurIPS 2023*
>
> Paper: https://arxiv.org/abs/2303.11366

```bibtex
@inproceedings{shinn2023reflexion,
  title={Reflexion: Language Agents with Verbal Reinforcement Learning},
  author={Shinn, Noah and Cassano, Federico and Gopinath, Ashwin and Narasimhan, Karthik R and Yao, Shunyu},
  booktitle={Advances in Neural Information Processing Systems (NeurIPS)},
  year={2023}
}
```

## License

MIT License

---

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