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):

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:

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:

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:

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

3. Run CleverAgents

Interactive Mode:

cleveragents interactive -c config.yaml

Single-Shot Mode:

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.

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.

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.

cleveragents generate-examples -o ./my-examples

Options:

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

cleveragents visualize

Visualize the agent network.

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)

# 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

cleveragents interactive -c examples/basic_chat.yaml

Scientific Paper Writer

cleveragents interactive -c examples/scientific_paper_writer.yaml

Multi-Agent Collaboration

cleveragents interactive -c examples/collaboration_reactive.yaml

🧪 Development

Running Tests

# 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 or contact us at dev@cleverthis.com.