cleveragents-core/README.md

# CleverAgents

A powerful, reactive Agent Framework using RxPy streams for complex AI agent orchestration and message routing.

## 🌊 What is CleverAgents?

CleverAgents is a **reactive agent orchestration framework** that combines the power of RxPy reactive streams with LangGraph stateful workflows to create sophisticated AI agent networks. It's designed for building complex, multi-agent systems that can handle real-time data processing, conversational AI, and workflow automation.

### Key Features

- **🌊 Reactive Architecture**: Built on RxPy streams for real-time data processing
- **🤖 Multiple Agent Types**: LLM agents, tool agents, composite agents, and more
- **🔄 Unified Routes**: Single configuration system for streams and graphs
- **🧠 Memory Management**: Conversation history and state persistence
- **🔗 LangGraph Integration**: Stateful workflows with conditional logic
- **⚡ Async Processing**: Full async/await support throughout
- **🎯 Template System**: Reusable agent and workflow templates

## 📦 Installation

### Prerequisites

- Python 3.9+ (recommended: Python 3.11+)
- pip package manager

### Install from Source (Recommended)

**For development (editable install):**
```bash
git clone https://git.cleverthis.com/cleveragents/cleveragents-core
cd cleveragents-core
pip install -e .
```
### Dependencies

CleverAgents automatically installs these dependencies:

- `click` - Command-line interface
- `rx>=3.2.0` - Reactive extensions for Python
- `jinja2` - Template engine
- `pystache` - Mustache template support
- `pyyaml` - YAML configuration parsing
- `langchain-core>=0.3.0` - LangChain integration
- `langchain-openai>=0.2.0` - OpenAI integration
- `langchain-anthropic>=0.2.0` - Anthropic integration
- `langchain-google-genai>=2.0.0` - Google Gemini integration
- `aiohttp` - Async HTTP client

## 🚀 Quick Start

### 1. Create a Configuration File

Create a `config.yaml` file:

```yaml
agents:
  chat_agent:
    type: llm
    config:
      provider: openai
      model: gpt-4
      temperature: 0.7
      memory_enabled: true

routes:
  chat_stream:
    type: stream
    stream_type: cold
    operators:
      - type: map
        params:
          agent: chat_agent
    publications:
      - __output__

merges:
  - sources: [__input__]
    target: chat_stream
```

### 2. Set Up API Keys

Configure your API keys via environment variables:

```bash
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GOOGLE_API_KEY="your-google-key"
```

Or include them directly in your configuration:

```yaml
agents:
  chat_agent:
    type: llm
    config:
      provider: openai
      model: gpt-4
      api_key: "your-openai-key"
```

### 3. Run CleverAgents

**Interactive Mode:**
```bash
cleveragents interactive -c config.yaml
```

**Single-Shot Mode:**
```bash
cleveragents run -c config.yaml -p "Hello, how are you?"
```

## 🛠️ Command Line Interface

### Main Commands

#### `cleveragents run`
Process a single prompt through the agent network.

```bash
cleveragents run -c config.yaml -p "Your prompt here"
```

**Options:**
- `-c, --config`: Path to configuration file(s) (can be used multiple times)
- `-p, --prompt`: The prompt to send to the agent network
- `-o, --output`: Optional file to write output to
- `-v, --verbose`: Enable verbose output
- `-u, --unsafe`: Enable unsafe mode for code execution

#### `cleveragents interactive`
Start an interactive chat session.

```bash
cleveragents interactive -c config.yaml
```

**Options:**
- `-c, --config`: Path to configuration file(s)
- `-h, --history`: Optional file to load/save conversation history
- `-v, --verbose`: Enable verbose output
- `-u, --unsafe`: Enable unsafe mode

#### `cleveragents generate-examples`
Generate example configuration files.

```bash
cleveragents generate-examples -o ./my-examples
```

**Options:**
- `-o, --output`: Directory to write example files to (default: `./examples`)

#### `cleveragents visualize`
Visualize the agent network.

```bash
cleveragents visualize -c config.yaml -f mermaid
```

**Options:**
- `-c, --config`: Path to configuration file(s)
- `-o, --output`: Output file for the diagram
- `-f, --format`: Output format (`mermaid`, `dot`, `ascii`)

### Interactive Session Commands

When in interactive mode, you can use these commands:

- `exit` - Exit the session
- `help` - Show available commands
- `/stream <name> <message>` - Send message to specific stream
- `/graph <name> <message>` - Execute a LangGraph with message

## 🔧 API Key Configuration

CleverAgents supports multiple LLM providers through LangChain. Configure API keys in two ways:

### Environment Variables (Recommended)

```bash
# OpenAI
export OPENAI_API_KEY="sk-your-key-here"

# Anthropic
export ANTHROPIC_API_KEY="your-anthropic-key"

# Google Gemini
export GOOGLE_API_KEY="your-google-key"
```

### Supported Models

**OpenAI:**
- GPT-4, GPT-4o, GPT-3.5-turbo
- o1-preview, o1-mini

**Anthropic:**
- Claude-3.5-Sonnet, Claude-3-Opus, Claude-3-Haiku

**Google:**
- Gemini-1.5-Pro, Gemini-1.5-Flash, Gemini-2.0-Flash

## 🏗️ Architecture

### Reactive Streams (RxPy)

CleverAgents uses RxPy for reactive programming:

- **Hot Streams**: Always active, replay last value
- **Cold Streams**: Start when subscribed
- **Replay Streams**: Replay all previous values
- **Operators**: map, filter, merge, split, buffer, throttle, debounce

### Agent Types

1. **LLM Agents**: Powered by large language models
2. **Tool Agents**: Execute functions and tools
3. **Composite Agents**: Combine multiple agents
4. **Chain Agents**: Sequential processing chains

### Unified Routes System

Single configuration system for different processing types:

- **Stream Routes**: Reactive, stateless processing
- **Graph Routes**: Stateful workflows with conditional logic
- **Bridge Routes**: Dynamic type conversion

## 📚 Examples

### Basic Chat
```bash
cleveragents interactive -c examples/basic_chat.yaml
```

### Scientific Paper Writer
```bash
cleveragents interactive -c examples/scientific_paper_writer.yaml
```

### Multi-Agent Collaboration
```bash
cleveragents interactive -c examples/collaboration_reactive.yaml
```

## 🧪 Development

### Running Tests

```bash
# Run all BDD tests
pip install behave
python -m behave tests/features

# Run with coverage
coverage run -m behave tests/features
coverage report
coverage html

# Run with tox for multiple environments
tox

# Run specific Python version
tox -e py39
tox -e py312

# Run tests with coverage
tox -e py312-cover

# Run without coverage (faster)
tox -e py312-nocov

# Integration test scripts (all tests passing):
bash tests/scripts/test_multi_agent_paper_writer_langgraph.sh      # Multi-agent paper writing with LangGraph
bash tests/scripts/test_legal_contract_analyzer_langgraph.sh       # Legal contract analysis with LangGraph
bash tests/scripts/test_paper_writer_section_by_section.sh         # Section-by-section paper writing
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## 📄 License

Apache License 2.0

## 🔗 Links

- **Documentation**: https://cleveragents.readthedocs.io/
- **PyPI**: https://pypi.org/project/cleveragents/
- **GitHub**: https://github.com/cleverthis/cleveragents
- **Issues**: https://github.com/cleverthis/cleveragents/issues

## 🤝 Support

For questions, issues, or contributions, please visit our [GitHub repository](https://github.com/cleverthis/cleveragents) or contact us at [dev@cleverthis.com](mailto:dev@cleverthis.com).