swarms/docs/llm.txt

# File: concepts/limitations.md

# Limitations of Individual Agents

This section explores the fundamental limitations of individual AI agents and why multi-agent systems are necessary for complex tasks. Understanding these limitations is crucial for designing effective multi-agent architectures.

## Overview

```mermaid
graph TD
    A[Individual Agent Limitations] --> B[Context Window Limits]
    A --> C[Hallucination]
    A --> D[Single Task Execution]
    A --> E[Lack of Collaboration]
    A --> F[Accuracy Issues]
    A --> G[Processing Speed]
```

## 1. Context Window Limits

### The Challenge
Individual agents are constrained by fixed context windows, limiting their ability to process large amounts of information simultaneously.

```mermaid
graph LR
    subgraph "Context Window Limitation"
        Input[Large Document] --> Truncation[Truncation]
        Truncation --> ProcessedPart[Processed Part]
        Truncation --> UnprocessedPart[Unprocessed Part]
    end
```

### Impact
- Limited understanding of large documents
- Fragmented processing of long conversations
- Inability to maintain extended context
- Loss of important information

## 2. Hallucination

### The Challenge
Individual agents may generate plausible-sounding but incorrect information, especially when dealing with ambiguous or incomplete data.

```mermaid
graph TD
    Input[Ambiguous Input] --> Agent[AI Agent]
    Agent --> Valid[Valid Output]
    Agent --> Hallucination[Hallucinated Output]
    style Hallucination fill:#ff9999
```

### Impact
- Unreliable information generation
- Reduced trust in system outputs
- Potential for misleading decisions
- Need for extensive verification

## 3. Single Task Execution

### The Challenge
Most individual agents are optimized for specific tasks and struggle with multi-tasking or adapting to new requirements.

```mermaid
graph LR
    Task1[Task A] --> Agent1[Agent A]
    Task2[Task B] --> Agent2[Agent B]
    Task3[Task C] --> Agent3[Agent C]
    Agent1 --> Output1[Output A]
    Agent2 --> Output2[Output B]
    Agent3 --> Output3[Output C]
```

### Impact
- Limited flexibility
- Inefficient resource usage
- Complex integration requirements
- Reduced adaptability

## 4. Lack of Collaboration

### The Challenge
Individual agents operate in isolation, unable to share insights or coordinate actions with other agents.

```mermaid
graph TD
    A1[Agent 1] --> O1[Output 1]
    A2[Agent 2] --> O2[Output 2]
    A3[Agent 3] --> O3[Output 3]
    style A1 fill:#f9f,stroke:#333
    style A2 fill:#f9f,stroke:#333
    style A3 fill:#f9f,stroke:#333
```

### Impact
- No knowledge sharing
- Duplicate effort
- Missed optimization opportunities
- Limited problem-solving capabilities

## 5. Accuracy Issues

### The Challenge
Individual agents may produce inaccurate results due to:
- Limited training data
- Model biases
- Lack of cross-validation
- Incomplete context understanding

```mermaid
graph LR
    Input[Input Data] --> Processing[Processing]
    Processing --> Accurate[Accurate Output]
    Processing --> Inaccurate[Inaccurate Output]
    style Inaccurate fill:#ff9999
```

## 6. Processing Speed Limitations

### The Challenge
Individual agents may experience:
- Slow response times
- Resource constraints
- Limited parallel processing
- Bottlenecks in complex tasks

```mermaid
graph TD
    Input[Input] --> Queue[Processing Queue]
    Queue --> Processing[Sequential Processing]
    Processing --> Delay[Processing Delay]
    Delay --> Output[Delayed Output]
```

## Best Practices for Mitigation

1. **Use Multi-Agent Systems**
   - Distribute tasks across agents
   - Enable parallel processing
   - Implement cross-validation
   - Foster collaboration

2. **Implement Verification**
   - Cross-check results
   - Use consensus mechanisms
   - Monitor accuracy metrics
   - Track performance

3. **Optimize Resource Usage**
   - Balance load distribution
   - Cache frequent operations
   - Implement efficient queuing
   - Monitor system health

## Conclusion

Understanding these limitations is crucial for:
- Designing robust multi-agent systems
- Implementing effective mitigation strategies
- Optimizing system performance
- Ensuring reliable outputs

The next section explores how [Multi-Agent Architecture](architecture.md) addresses these limitations through collaborative approaches and specialized agent roles. 

--------------------------------------------------

# File: contributors/docs.md

# Contributing to Swarms Documentation

---

The Swarms documentation serves as the primary gateway for developer and user engagement within the Swarms ecosystem. Comprehensive, clear, and consistently updated documentation accelerates adoption, reduces support requests, and helps maintain a thriving developer community. This guide offers an in-depth, actionable framework for contributing to the Swarms documentation site, covering the full lifecycle from initial setup to the implementation of our bounty-based rewards program. 

This guide is designed for first-time contributors, experienced engineers, and technical writers alike. It emphasizes professional standards, collaborative development practices, and incentivized participation through our structured rewards program. Contributors play a key role in helping us scale and evolve our ecosystem by improving the clarity, accessibility, and technical depth of our documentation.

---

## 1. Introduction

Documentation in the Swarms ecosystem is not simply static text. It is a living, breathing system that guides users, developers, and enterprises in effectively utilizing our frameworks, SDKs, APIs, and tools. Whether you are documenting a new feature, refining an API call, writing a tutorial, or correcting existing information, every contribution has a direct impact on the product’s usability and user satisfaction. 

**Objectives of this Guide:**


- Define a standardized contribution workflow for Swarms documentation.

- Clarify documentation roles, responsibilities, and submission expectations.

- Establish quality benchmarks, review procedures, and formatting rules.

- Introduce the Swarms Documentation Bounty Program to incentivize excellence.

---

## 2. Why Documentation Is a Strategic Asset

1. **Accelerates Onboarding**: Reduces friction for new users, enabling faster adoption and integration.
2. **Improves Support Efficiency**: Decreases dependency on live support and helps automate resolution of common queries.
3. **Builds Community Trust**: Transparent documentation invites feedback and fosters a sense of shared ownership.
4. **Enables Scalability**: As Swarms evolves, up-to-date documentation ensures that teams across the globe can keep pace.

By treating documentation as a core product component, we ensure continuity, scalability, and user satisfaction.

---

## 3. Understanding the Swarms Ecosystem

The Swarms ecosystem consists of multiple tightly integrated components that serve developers and enterprise clients alike:


- **Core Documentation Repository**: The main documentation hub for all Swarms technologies [GitHub](https://github.com/kyegomez/swarms).

- **Rust SDK (`swarms_rs`)**: Official documentation for the Rust implementation. [Repo](https://github.com/The-Swarm-Corporation/swarms-rs).

- **Tools Documentation (`swarms_tools`)**: Guides for CLI and GUI utilities.

- **Hosted API Reference**: Up-to-date REST API documentation: [Swarms API Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/).

- **Marketplace & Chat**: Web platforms and communication interfaces [swarms.world](https://swarms.world).

All contributions funnel through the `docs/` directory in the core repo and are structured via MkDocs.

---

## 4. Documentation Tools and Platforms

Swarms documentation is powered by [MkDocs](https://www.mkdocs.org/), an extensible static site generator tailored for project documentation. To contribute, you should be comfortable with:

- **Markdown**: For formatting structure, code snippets, lists, and links.

- **MkDocs Configuration**: `mkdocs.yml` manages structure, theme, and navigation.

- **Version Control**: GitHub for branching, version tracking, and collaboration.

**Recommended Tooling:**

- Markdown linters to enforce syntax consistency.

- Spellcheckers to ensure grammatical accuracy.

- Doc generators for automated API reference extraction.

---

## 5. Getting Started with Contributions

### 5.1 System Requirements


- **Git** v2.30 or higher

- **Node.js** and **npm** for related dependency management

- **MkDocs** and **Material for MkDocs** theme (`pip install mkdocs mkdocs-material`)

- A GitHub account with permissions to fork and submit pull requests

### 5.2 Forking the Swarms Repository

1. Visit: `https://github.com/kyegomez/swarms`

2. Click on **Fork** to create your version of the repository

### 5.3 Clone and Configure Locally

```bash
git clone https://github.com/<your-username>/swarms.git
cd swarms/docs
git checkout -b feature/docs-<short-description>
```

---

## 6. Understanding the Repository Structure

Explore the documentation directory:

```text
docs/
├── index.md
├── mkdocs.yml
├── swarms_rs/
│   ├── overview.md
│   └── ...
└── swarms_tools/
    ├── install.md
    └── ...
```

### 6.1 SDK/Tools Directories

- **Rust SDK (`docs/swarms_rs`)**: Guides, references, and API walkthroughs for the Rust-based implementation.

- **Swarms Tools (`docs/swarms_tools`)**: CLI guides, GUI usage instructions, and architecture documentation.


Add new `.md` files in the folder corresponding to your documentation type.

### 6.2 Configuring Navigation in MkDocs

Update `mkdocs.yml` to integrate your new document:

```yaml
nav:
  - Home: index.md
  - Swarms Rust:
      - Overview: swarms_rs/overview.md
      - Your Topic: swarms_rs/your_file.md
  - Swarms Tools:
      - Installation: swarms_tools/install.md
      - Your Guide: swarms_tools/your_file.md
```

---

## 7. Writing and Editing Documentation

### 7.1 Content Standards


- **Clarity**: Explain complex ideas in simple, direct language.

- **Style Consistency**: Match the tone and structure of existing docs.

- **Accuracy**: Validate all technical content and code snippets.

- **Accessibility**: Include alt text for images and use semantic Markdown.

### 7.2 Markdown Best Practices

- Sequential heading levels (`#`, `##`, `###`)

- Use fenced code blocks with language identifiers

- Create readable line spacing and avoid unnecessary line breaks


### 7.3 File Placement Protocol

Place `.md` files into the correct subdirectory:


- **Rust SDK Docs**: `docs/swarms_rs/`

- **Tooling Docs**: `docs/swarms_tools/`

---

## 8. Updating Navigation Configuration

After writing your content:

1. Open `mkdocs.yml`
2. Identify where your file belongs
3. Add it to the `nav` hierarchy
4. Preview changes:

```bash
mkdocs serve
# Open http://127.0.0.1:8000 to verify output
```

---

## 9. Workflow: Branches, Commits, Pull Requests

### 9.1 Branch Naming Guidelines

- Use prefix and description, e.g.:
  - `feature/docs-api-pagination`

  - `fix/docs-typo-tooling`

### 9.2 Writing Clear Commits

Follow [Conventional Commits](https://www.conventionalcommits.org/):

```bash
docs(swarms_rs): add stream API tutorial
docs(swarms_tools): correct CLI usage example
```

### 9.3 Submitting a Pull Request

1. Push your feature branch
2. Open a new PR to the main repository
3. Use a descriptive title and include:
   - Summary of changes
   - Justification
   - Screenshots or previews
4. Tag relevant reviewers and apply labels (`documentation`, `bounty-eligible`)

---

## 10. Review, QA, and Merging

Every PR undergoes automated and human review:

- **CI Checks**: Syntax validation, link checking, and formatting

- **Manual Review**: Maintain clarity, completeness, and relevance

- **Iteration**: Collaborate through feedback and finalize changes

Once approved, maintainers will merge and deploy the updated documentation.

---

## 11. Swarms Documentation Bounty Initiative

To foster continuous improvement, we offer structured rewards for eligible contributions:

### 11.1 Contribution Types


- Creating comprehensive new tutorials and deep dives

- Updating outdated references and examples

- Fixing typos, grammar, and formatting errors

- Translating existing content

### 11.2 Reward Structure

| Tier     | Description                                            | Payout (USD)     |
|----------|--------------------------------------------------------|------------------|
| Bronze   | Typos or minor enhancements (< 100 words)             | $1 - $5        |
| Silver   | Small tutorials, API examples (100–500 words)         | $5 - $20       |
| Gold     | Major updates or guides (> 500 words)                 | $20 - $50      |
| Platinum | Multi-part guides or new documentation verticals      | $50 - 300          |

### 11.3 Claiming Bounties

1. Label your PR `bounty-eligible`
2. Describe expected tier and rationale
3. Review team assesses scope and assigns reward
4. Rewards paid post-merge via preferred method (PayPal, crypto, or wire)

---

## 12. Best Practices for Efficient Contribution

- **Stay Updated**: Sync your fork weekly to avoid merge conflicts

- **Atomic PRs**: Submit narrowly scoped changes for faster review

- **Use Visuals**: Support documentation with screenshots or diagrams

- **Cross-Reference**: Link to related documentation for completeness

- **Version Awareness**: Specify SDK/tool versions in code examples

---

## 13. Style Guide Snapshot


- **Voice**: Informative, concise, and respectful

- **Terminology**: Use standardized terms (`Swarm`, `Swarms`) consistently

- **Code**: Format snippets using language-specific linters

- **Accessibility**: Include alt attributes and avoid ambiguous links

---

## 14. Monitoring & Improving Documentation Health

We use analytics and community input to prioritize improvements:

- **Traffic Reports**: Track most/least visited pages

- **Search Logs**: Detect content gaps from common search terms

- **Feedback Forms**: Collect real-world user input

Schedule quarterly audits to refine structure and content across all repositories.

---

## 15. Community Promotion & Engagement

Promote your contributions via:


- **Swarms Discord**: https://discord.gg/EamjgSaEQf

- **Swarms Telegram**: https://t.me/swarmsgroupchat

- **Swarms Twitter**: https://x.com/swarms_corp

- **Startup Program Showcases**: https://www.swarms.xyz/programs/startups

Active contributors are often spotlighted for leadership roles and community awards.

---

## 16. Resource Index

- Core GitHub Repo: https://github.com/kyegomez/swarms

- Rust SDK Repo: https://github.com/The-Swarm-Corporation/swarms-rs

- Swarms API Docs: https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/

- Marketplace: https://swarms.world

Join our monthly Documentation Office Hours for real-time mentorship and Q&A.

---

## 17. Frequently Asked Questions

**Q1: Is MkDocs required to contribute?**  
A: It's recommended but not required; Markdown knowledge is sufficient to get started.

**Q2: Can I rework existing sections?**  
A: Yes, propose changes via issues first, or submit PRs with clear descriptions.

**Q3: When are bounties paid?**  
A: Within 30 days of merge, following internal validation.

---

## 18. Final Thoughts

The Swarms documentation is a critical piece of our technology stack. As a contributor, your improvements—big or small—directly impact adoption, user retention, and developer satisfaction. This guide aims to equip you with the tools, practices, and incentives to make meaningful contributions. Your work helps us deliver a more usable, scalable, and inclusive platform.

We look forward to your pull requests, feedback, and ideas.

---


--------------------------------------------------

# File: contributors/environment_setup.md

# Environment Setup Guide for Swarms Contributors

Welcome to the Swarms development environment setup guide! This comprehensive guide will walk you through setting up your development environment from scratch, whether you're a first-time contributor or an experienced developer.

!!! success "🚀 One-Click Setup (Recommended)"
    **New!** Use our automated setup script that handles everything:
    ```bash
    git clone https://github.com/kyegomez/swarms.git
    cd swarms
    chmod +x scripts/setup.sh
    ./scripts/setup.sh
    ```
    This script automatically installs Poetry, creates a virtual environment, installs all dependencies, sets up pre-commit hooks, and more!

!!! info "Manual Setup"
    **Alternative**: For manual control, install Python 3.10+, Git, and Poetry, then run:
    ```bash
    git clone https://github.com/kyegomez/swarms.git
    cd swarms
    poetry install --with dev
    ```

---

## :material-list-status: Prerequisites

Before setting up your development environment, ensure you have the following installed:

### System Requirements

| Tool | Version | Purpose |
|------|---------|---------|
| **Python** | 3.10+ | Core runtime |
| **Git** | 2.30+ | Version control |
| **Poetry** | 1.4+ | Dependency management (recommended) |
| **Node.js** | 16+ | Documentation tools (optional) |

### Operating System Support

=== "macOS"
    
    ```bash
    # Install Homebrew if not already installed
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    
    # Install prerequisites
    brew install python@3.10 git poetry node
    ```

=== "Ubuntu/Debian"
    
    ```bash
    # Update package list
    sudo apt update
    
    # Install Python 3.10 and pip
    sudo apt install python3.10 python3.10-venv python3-pip git curl
    
    # Install Poetry
    curl -sSL https://install.python-poetry.org | python3 -
    
    # Add Poetry to PATH
    export PATH="$HOME/.local/bin:$PATH"
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
    ```

=== "Windows"
    
    1. **Install Python 3.10+** from [python.org](https://python.org/downloads/)
    2. **Install Git** from [git-scm.com](https://git-scm.com/download/win)
    3. **Install Poetry** using PowerShell:
    ```powershell
    (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -
    ```

---

## :material-auto-fix: Automated Setup (Recommended)

We provide a comprehensive setup script that automates the entire development environment setup process. This is the **recommended approach** for new contributors.

### What the Setup Script Does

The `scripts/setup.sh` script automatically handles:

- ✅ **Python Version Check**: Verifies Python 3.10+ is installed
- ✅ **Poetry Installation**: Installs Poetry if not present
- ✅ **Virtual Environment**: Creates and configures a project-specific virtual environment
- ✅ **Dependencies**: Installs all main, development, lint, and test dependencies
- ✅ **Pre-commit Hooks**: Sets up and installs pre-commit hooks for code quality
- ✅ **Environment Template**: Creates a `.env` file template with common variables
- ✅ **Verification**: Runs initial setup verification checks
- ✅ **Helpful Output**: Provides colored output and next steps

### Running the Automated Setup

```bash
# Clone the repository
git clone https://github.com/kyegomez/swarms.git
cd swarms

# Make the script executable and run it
chmod +x scripts/setup.sh
./scripts/setup.sh
```

### Script Features

=== "🎯 Smart Detection"
    The script intelligently detects your system state:
    - Checks if Poetry is already installed
    - Verifies Python version compatibility
    - Detects existing virtual environments
    - Checks for Git repository status

=== "🔧 Comprehensive Setup"
    Installs everything you need:
    ```bash
    # All dependency groups
    poetry install --with dev,lint,test
    
    # Pre-commit hooks
    pre-commit install
    pre-commit install --hook-type commit-msg
    
    # Initial verification run
    pre-commit run --all-files
    ```

=== "📋 Environment Template"
    Creates a starter `.env` file:
    ```bash
    # Generated .env template
    OPENAI_API_KEY=your_openai_api_key_here
    ANTHROPIC_API_KEY=your_anthropic_key_here
    LOG_LEVEL=INFO
    DEVELOPMENT=true
    ```

=== "💡 Helpful Guidance"
    Provides next steps and useful commands:
    - How to activate the virtual environment
    - Essential Poetry commands
    - Testing and development workflow
    - Troubleshooting tips

### When to Use Manual Setup

Use the manual setup approach if you:
- Want full control over each step
- Have specific system requirements
- Are troubleshooting installation issues
- Prefer to understand each component

---

## :material-git: Repository Setup

### Step 1: Fork and Clone

1. **Fork the repository** on GitHub: [github.com/kyegomez/swarms](https://github.com/kyegomez/swarms)

2. **Clone your fork**:
```bash
git clone https://github.com/YOUR_USERNAME/swarms.git
cd swarms
```

3. **Add upstream remote**:
```bash
git remote add upstream https://github.com/kyegomez/swarms.git
```

4. **Verify remotes**:
```bash
git remote -v
# origin    https://github.com/YOUR_USERNAME/swarms.git (fetch)
# origin    https://github.com/YOUR_USERNAME/swarms.git (push)
# upstream  https://github.com/kyegomez/swarms.git (fetch)
# upstream  https://github.com/kyegomez/swarms.git (push)
```

---

## :material-package-variant: Dependency Management

Choose your preferred method for managing dependencies:

=== "Poetry (Recommended)"
    
    Poetry provides superior dependency resolution and virtual environment management.

    ### Installation
    
    ```bash
    # Navigate to project directory
    cd swarms
    
    # Install all dependencies including development tools
    poetry install --with dev,lint,test
    
    # Activate the virtual environment
    poetry shell
    ```

    ### Useful Poetry Commands
    
    ```bash
    # Add a new dependency
    poetry add package_name
    
    # Add a development dependency
    poetry add --group dev package_name
    
    # Update dependencies
    poetry update
    
    # Show dependency tree
    poetry show --tree
    
    # Run commands in the virtual environment
    poetry run python your_script.py
    ```

=== "pip + venv"
    
    Traditional pip-based setup with virtual environments.

    ### Installation
    
    ```bash
    # Navigate to project directory
    cd swarms
    
    # Create virtual environment
    python -m venv venv
    
    # Activate virtual environment
    # On macOS/Linux:
    source venv/bin/activate
    # On Windows:
    venv\Scripts\activate
    
    # Upgrade pip
    pip install --upgrade pip
    
    # Install core dependencies
    pip install -r requirements.txt
    
    # Install documentation dependencies (optional)
    pip install -r docs/requirements.txt
    ```

---

## :material-tools: Development Tools Setup

### Code Quality Tools

Swarms uses several tools to maintain code quality:

=== "Formatting"
    
    **Black** - Code formatter
    ```bash
    # Format code
    poetry run black swarms/
    # or with pip:
    black swarms/
    
    # Check formatting without making changes
    black swarms/ --check --diff
    ```

=== "Linting"
    
    **Ruff** - Fast Python linter
    ```bash
    # Run linter
    poetry run ruff check swarms/
    # or with pip:
    ruff check swarms/
    
    # Auto-fix issues
    ruff check swarms/ --fix
    ```

=== "Type Checking"
    
    **MyPy** - Static type checker
    ```bash
    # Run type checking
    poetry run mypy swarms/
    # or with pip:
    mypy swarms/
    ```

### Pre-commit Hooks (Optional but Recommended)

Set up pre-commit hooks to automatically run quality checks:

```bash
# Install pre-commit
poetry add --group dev pre-commit
# or with pip:
pip install pre-commit

# Install git hooks
pre-commit install

# Run on all files
pre-commit run --all-files
```

The project uses the latest ruff-pre-commit configuration with separate hooks for linting and formatting:

- **ruff-check**: Runs the linter with automatic fixes (`--fix` flag)
- **ruff-format**: Runs the formatter for code styling
- **types_or: [python, pyi]**: Excludes Jupyter notebooks from processing

This configuration ensures consistent code quality and style across the project while avoiding conflicts with Jupyter notebook files.

---

## :material-test-tube: Testing Setup

### Running Tests

```bash
# Run all tests
poetry run pytest
# or with pip:
pytest

# Run tests with coverage
poetry run pytest --cov=swarms tests/

# Run specific test file
poetry run pytest tests/test_specific_file.py

# Run tests matching a pattern
poetry run pytest -k "test_agent"
```

### Test Structure

The project uses pytest with the following structure:
```
tests/
├── agents/          # Agent-related tests
├── structs/         # Multi-agent structure tests
├── tools/           # Tool tests
├── utils/           # Utility tests
└── conftest.py      # Test configuration
```

### Writing Tests

```python
# Example test file: tests/test_example.py
import pytest
from swarms import Agent

def test_agent_creation():
    """Test that an agent can be created successfully."""
    agent = Agent(
        agent_name="test_agent",
        system_prompt="You are a helpful assistant"
    )
    assert agent.agent_name == "test_agent"

@pytest.mark.parametrize("input_val,expected", [
    ("hello", "HELLO"),
    ("world", "WORLD"),
])
def test_uppercase(input_val, expected):
    """Example parametrized test."""
    assert input_val.upper() == expected
```

---

## :material-book-open-page-variant: Documentation Setup

### Building Documentation Locally

```bash
# Install documentation dependencies
pip install -r docs/requirements.txt

# Navigate to docs directory
cd docs

# Serve documentation locally
mkdocs serve
# Documentation will be available at http://127.0.0.1:8000
```

### Documentation Structure

```
docs/
├── index.md              # Homepage
├── mkdocs.yml           # MkDocs configuration
├── swarms/              # Core documentation
├── examples/            # Examples and tutorials
├── contributors/        # Contributor guides
└── assets/              # Images and static files
```

### Writing Documentation

Use Markdown with MkDocs extensions:

```markdown
# Page Title

!!! tip "Pro Tip"
    Use admonitions to highlight important information.

=== "Python"
    ```python
    from swarms import Agent
    agent = Agent()
    ```

=== "CLI"
    ```bash
    swarms create-agent --name myagent
    ```
```

---

## :material-application-variable: Environment Variables

Create a `.env` file for local development:

```bash
# Copy example environment file
cp .env.example .env  # if it exists

# Or create your own .env file
touch .env
```

Common environment variables:
```bash
# .env file
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GROQ_API_KEY=your_groq_api_key_here

# Development settings
DEBUG=true
LOG_LEVEL=INFO

# Optional: Database settings
DATABASE_URL=sqlite:///swarms.db
```

---

## :material-check-circle: Verification Steps

!!! tip "Automated Verification"
    If you used the automated setup script (`./scripts/setup.sh`), most verification steps are handled automatically. The script runs verification checks and reports any issues.

For manual setups, verify your setup is working correctly:

### 1. Basic Import Test
```bash
poetry run python -c "from swarms import Agent; print('✅ Import successful')"
```

### 2. Run a Simple Agent
```python
# test_setup.py
from swarms import Agent

agent = Agent(
    agent_name="setup_test",
    system_prompt="You are a helpful assistant for testing setup.",
    max_loops=1
)

response = agent.run("Say hello!")
print(f"✅ Agent response: {response}")
```

### 3. Code Quality Check
```bash
# Run all quality checks
poetry run black swarms/ --check
poetry run ruff check swarms/
poetry run pytest tests/ -x
```

### 4. Documentation Build
```bash
cd docs
mkdocs build
echo "✅ Documentation built successfully"
```

---

## :material-rocket-launch: Development Workflow

### Creating a Feature Branch

```bash
# Sync with upstream
git fetch upstream
git checkout master
git rebase upstream/master

# Create feature branch
git checkout -b feature/your-feature-name

# Make your changes...
# Add and commit
git add .
git commit -m "feat: add your feature description"

# Push to your fork
git push origin feature/your-feature-name
```

### Daily Development Commands

```bash
# Start development session
cd swarms
poetry shell  # or source venv/bin/activate

# Pull latest changes
git fetch upstream
git rebase upstream/master

# Run tests during development
poetry run pytest tests/ -v

# Format and lint before committing
poetry run black swarms/
poetry run ruff check swarms/ --fix

# Run a quick smoke test
poetry run python -c "from swarms import Agent; print('✅ All good')"
```

---

## :material-bug: Troubleshooting

!!! tip "First Step: Try the Automated Setup"
    If you're experiencing setup issues, try running our automated setup script first:
    ```bash
    chmod +x scripts/setup.sh
    ./scripts/setup.sh
    ```
    This script handles most common setup problems automatically and provides helpful error messages.

### Common Issues and Solutions

=== "Poetry Issues"
    
    **Problem**: Poetry command not found
    ```bash
    # Solution: Add Poetry to PATH
    export PATH="$HOME/.local/bin:$PATH"
    # Add to your shell profile (.bashrc, .zshrc, etc.)
    ```
    
    **Problem**: Poetry install fails
    ```bash
    # Solution: Clear cache and reinstall
    poetry cache clear --all pypi
    poetry install --with dev
    ```

=== "Python Version Issues"
    
    **Problem**: Wrong Python version
    ```bash
    # Check Python version
    python --version
    
    # Use pyenv to manage Python versions
    curl https://pyenv.run | bash
    pyenv install 3.10.12
    pyenv local 3.10.12
    ```

=== "Import Errors"
    
    **Problem**: Cannot import swarms modules
    ```bash
    # Ensure you're in the virtual environment
    poetry shell
    # or
    source venv/bin/activate
    
    # Install in development mode
    poetry install --with dev
    # or
    pip install -e .
    ```

=== "Test Failures"
    
    **Problem**: Tests fail due to missing dependencies
    ```bash
    # Install test dependencies
    poetry install --with test
    # or
    pip install pytest pytest-cov pytest-mock
    ```

### Getting Help

If you encounter issues:

1. **Check the FAQ** in the main documentation
2. **Search existing issues** on GitHub
3. **Ask in the Discord community**: [discord.gg/jM3Z6M9uMq](https://discord.gg/EamjgSaEQf)
4. **Create a GitHub issue** with:
   - Your operating system
   - Python version
   - Error messages
   - Steps to reproduce

---

## :material-next-step: Next Steps

Now that your environment is set up:

1. **Read the Contributing Guide**: [contributors/main.md](main.md)
2. **Explore the Codebase**: Start with `swarms/structs/agent.py`
3. **Run Examples**: Check out `examples/` directory
4. **Pick an Issue**: Look for `good-first-issue` labels on GitHub
5. **Join the Community**: Discord, Twitter, and GitHub discussions

!!! success "You're Ready!"
    Your Swarms development environment is now set up! You're ready to contribute to the most important technology for multi-agent collaboration.

---

## :material-bookmark-outline: Quick Reference

### Essential Commands

```bash
# Setup (choose one)
./scripts/setup.sh                   # Automated setup (recommended)
poetry install --with dev            # Manual dependency install

# Daily workflow
poetry shell                          # Activate environment
poetry run pytest                    # Run tests
poetry run black swarms/             # Format code
poetry run ruff check swarms/        # Lint code

# Git workflow
git fetch upstream                    # Get latest changes
git rebase upstream/master           # Update your branch
git checkout -b feature/name         # Create feature branch
git push origin feature/name         # Push your changes

# Documentation
cd docs && mkdocs serve              # Serve docs locally
mkdocs build                         # Build docs
```

### Project Structure

```
swarms/
├── swarms/              # Core package
│   ├── agents/         # Agent implementations
│   ├── structs/        # Multi-agent structures
│   ├── tools/          # Agent tools
│   └── utils/          # Utilities
├── examples/           # Usage examples
├── tests/              # Test suite
├── docs/               # Documentation
├── pyproject.toml      # Poetry configuration
└── requirements.txt    # Pip dependencies
```

Happy coding! 🚀 

--------------------------------------------------

# File: contributors/main.md

# Contribute to Swarms

Our mission is to accelerate the transition to a fully autonomous world economy by providing enterprise-grade, production-ready infrastructure that enables seamless deployment and orchestration of millions of autonomous agents. We are creating the operating system for the agent economy, and we need your help to achieve this goal.

Swarms is built by the community, for the community. We believe that collaborative development is the key to pushing the boundaries of what's possible with multi-agent AI. Your contributions are not only welcome—they are essential to our mission. [Learn more about why you should contribute to Swarms](https://docs.swarms.world/en/latest/contributors/main/)

### Why Contribute?

By joining us, you have the opportunity to:

* **Work on the Frontier of Agents:** Shape the future of autonomous agent technology and help build a production-grade, open-source framework.

* **Join a Vibrant Community:** Collaborate with a passionate and growing group of agent developers, researchers, and agent enthusasits.

* **Make a Tangible Impact:** Whether you're fixing a bug, adding a new feature, or improving documentation, your work will be used in real-world applications.

* **Learn and Grow:** Gain hands-on experience with advanced AI concepts and strengthen your software engineering skills.

Discover more about our mission and the benefits of becoming a contributor in our official [**Contributor's Guide**](https://docs.swarms.world/en/latest/contributors/main/).

### How to Get Started

We've made it easy to start contributing. Here's how you can help:

1. **Find an Issue to Tackle:** The best way to begin is by visiting our [**contributing project board**](https://github.com/users/kyegomez/projects/1). Look for issues tagged with `good first issue`—these are specifically selected for new contributors.

2. **Report a Bug or Request a Feature:** Have a new idea or found something that isn't working right? We'd love to hear from you. Please [**file a Bug Report or Feature Request**](https://github.com/kyegomez/swarms/issues) on our GitHub Issues page.

3. **Understand Our Workflow and Standards:** Before submitting your work, please review our complete [**Contribution Guidelines**](https://github.com/kyegomez/swarms/blob/master/CONTRIBUTING.md). To help maintain code quality, we also encourage you to read our guide on [**Code Cleanliness**](https://docs.swarms.world/en/latest/swarms/framework/code_cleanliness/).

4. **Join the Discussion:** To participate in roadmap discussions and connect with other developers, join our community on [**Discord**](https://discord.gg/EamjgSaEQf).


### ✨ Our Valued Contributors

Thank you for contributing to swarms. Your work is extremely appreciated and recognized.

<a href="https://github.com/kyegomez/swarms/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=kyegomez/swarms" />
</a>

--------------------------------------------------

# File: contributors/tools.md

# Contributing Tools and Plugins to the Swarms Ecosystem

## Introduction

The Swarms ecosystem is a modular, intelligent framework built to support the seamless integration, execution, and orchestration of dynamic tools that perform specific functions. These tools form the foundation for how autonomous agents operate, enabling them to retrieve data, communicate with APIs, conduct computational tasks, and respond intelligently to real-world requests. By contributing to Swarms Tools, developers can empower agents with capabilities that drive practical, enterprise-ready applications.

This guide provides a comprehensive roadmap for contributing tools and plugins to the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools). It is written for software engineers, data scientists, platform architects, and technologists who seek to develop modular, production-grade functionality within the Swarms agent framework.

Whether your expertise lies in finance, security, machine learning, or developer tooling, this documentation outlines the essential standards, workflows, and integration patterns to make your contributions impactful and interoperable.

## Repository Architecture

The Swarms Tools GitHub repository is meticulously organized to maintain structure, scalability, and domain-specific clarity. Each folder within the repository represents a vertical where tools can be contributed and extended over time. These folders include:

- `finance/`: Market analytics, stock price retrievers, blockchain APIs, etc.

- `social/`: Sentiment analysis, engagement tracking, and media scraping utilities.

- `health/`: Interfaces for EHR systems, wearable device APIs, or health informatics.

- `ai/`: Model-serving utilities, embedding services, and prompt engineering functions.

- `security/`: Encryption libraries, risk scoring tools, penetration test interfaces.

- `devtools/`: Build tools, deployment utilities, code quality analyzers.

- `misc/`: General-purpose helpers or utilities that serve multiple domains.

Each tool inside these directories is implemented as a single, self-contained function. These functions are expected to adhere to Swarms-wide standards for clarity, typing, documentation, and API key handling.

## Tool Development Specifications

To ensure long-term maintainability and smooth agent-tool integration, each contribution must strictly follow the specifications below.

### 1. Function Structure and API Usage

```python
import requests
import os

def fetch_data(symbol: str, date_range: str) -> str:
    """
    Fetch financial data for a given symbol and date range.

    Args:
        symbol (str): Ticker symbol of the asset.
        date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y').

    Returns:
        str: A string containing financial data or an error message.
    """
    api_key = os.getenv("FINANCE_API_KEY")
    url = f"https://api.financeprovider.com/data?symbol={symbol}&range={date_range}&apikey={api_key}"
    response = requests.get(url)
    if response.status_code == 200:
        return response.text
    return "Error fetching data."
```

All logic must be encapsulated inside a single callable function, written using pure Python. Where feasible, network requests should be stateless, side-effect-free, and gracefully handle errors or timeouts.

### 2. Type Hints and Input Validation

All function parameters must be typed using Python's type hinting system. Use built-in primitives where possible (e.g., `str`, `int`, `float`, `bool`) and make use of `Optional` or `Union` types when dealing with nullable parameters or multiple formats. This aids LLMs and type checkers in understanding expected input ranges.

### 3. Standardized Output Format

Regardless of internal logic or complexity, tools must return outputs in a consistent string format. This string can contain plain text or a serialized JSON object (as a string), but must not return raw objects, dictionaries, or binary blobs. This standardization ensures all downstream agents can interpret tool output predictably.

### 4. API Key Management Best Practices

Security and environment isolation are paramount. Never hardcode API keys or sensitive credentials inside source code. Always retrieve them dynamically using the `os.getenv("ENV_VAR")` approach. If a tool requires credentials, clearly document the required environment variable names in the function docstring.

### 5. Documentation Guidelines

Every tool must include a detailed docstring that describes:

- The function's purpose and operational scope

- All parameter types and formats

- A clear return type

- Usage examples or sample inputs/outputs

Example usage:
```python
result = fetch_data("AAPL", "1m")
print(result)
```

Well-documented code accelerates adoption and improves LLM interpretability.

## Contribution Workflow

To submit a tool, follow the workflow below. This ensures your code integrates cleanly and is easy for maintainers to review.

### Step 1: Fork the Repository
Navigate to the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools) and fork it to your personal or organization’s GitHub account.

### Step 2: Clone Your Fork
```bash
git clone https://github.com/YOUR_USERNAME/swarms-tools.git
cd swarms-tools
```

### Step 3: Create a Feature Branch

```bash
git checkout -b feature/add-tool-<tool-name>
```

Use descriptive branch names. This is especially helpful when collaborating in teams or maintaining audit trails.

### Step 4: Build Your Tool
Navigate into the appropriate category folder (e.g., `finance/`, `ai/`, etc.) and implement your tool according to the defined schema.

If your tool belongs in a new category, you may create a new folder with a clear, lowercase name.

### Step 5: Run Local Tests (if applicable)
Ensure the function executes correctly and does not throw runtime errors. If feasible, test edge cases and verify consistent behavior across platforms.

### Step 6: Commit Your Changes

```bash
git add .
git commit -m "Add <tool_name> under <folder_name>: API-based tool for X"
```

### Step 7: Push to GitHub

```bash
git push origin feature/add-tool-<tool-name>
```

### Step 8: Submit a Pull Request

On GitHub, open a pull request from your fork to the main Swarms Tools repository. Your PR description should:
- Summarize the tool’s functionality
- Reference any related issues or enhancements
- Include usage notes or setup instructions (e.g., required API keys)

---

## Integration with Swarms Agents

Once your tool has been merged into the official repository, it can be utilized by Swarms agents as part of their available capabilities.

The example below illustrates how to embed a newly added tool into an autonomous agent:

```python
from swarms import Agent
from finance.stock_price import get_stock_price

agent = Agent(
    agent_name="Devin",
    system_prompt=(
        "Autonomous agent that can interact with humans and other agents."
        " Be helpful and kind. Use the tools provided to assist the user."
        " Return all code in markdown format."
    ),
    llm=llm,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    interactive=True,
    tools=[get_stock_price, terminal, browser, file_editor, create_file],
    metadata_output_type="json",
    function_calling_format_type="OpenAI",
    function_calling_type="json",
)

agent.run("Create a new file for a plan to take over the world.")
```

By registering tools in the `tools` parameter during agent creation, you enable dynamic function calling. The agent interprets natural language input, selects the appropriate tool, and invokes it with valid arguments.

This agent-tool paradigm enables highly flexible and responsive behavior across workflows involving research, automation, financial analysis, social listening, and more.

---

## Tool Maintenance and Long-Term Ownership

Contributors are expected to uphold the quality of their tools post-merge. This includes:

- Monitoring for issues or bugs reported by the community

- Updating tools when APIs deprecate or modify their behavior

- Improving efficiency, error handling, or documentation over time

If a tool becomes outdated or unsupported, maintainers may archive or revise it to maintain ecosystem integrity.

Contributors whose tools receive wide usage or demonstrate excellence in design may be offered elevated privileges or invited to maintain broader tool categories.

---

## Best Practices for Enterprise-Grade Contributions

To ensure your tool is production-ready and enterprise-compliant, observe the following practices:


- Run static type checking with `mypy`

- Use formatters like `black` and linters such as `flake8`

- Avoid unnecessary external dependencies

- Keep functions modular and readable

- Prefer named parameters over positional arguments for clarity

- Handle API errors gracefully and return user-friendly messages

- Document limitations or assumptions in the docstring

Optional but encouraged:
- Add unit tests to validate function output

- Benchmark performance if your tool operates on large datasets

---

## Conclusion

The Swarms ecosystem is built on the principle of extensibility through community-driven contributions. By submitting modular, typed, and well-documented tools to the Swarms Tools repository, you directly enhance the problem-solving power of intelligent agents.

This documentation serves as your blueprint for contributing high-quality, reusable functionality. From idea to implementation to integration, your efforts help shape the future of collaborative, agent-powered software.

We encourage all developers, data scientists, and domain experts to contribute meaningfully. Review existing tools for inspiration, or create something entirely novel.

To begin, fork the [Swarms Tools repository](https://github.com/The-Swarm-Corporation/swarms-tools) and start building impactful, reusable tools that can scale across agents and use cases.



--------------------------------------------------

# File: deployment_solutions/fastapi_agent_api.md

# FastAPI Agent API

This guide shows you how to deploy your Swarms agents as REST APIs using FastAPI and Uvicorn. This is the fastest way to expose your agents via HTTP endpoints.

## Overview

FastAPI is a modern, fast web framework for building APIs with Python. Combined with Uvicorn (ASGI server), it provides excellent performance and automatic API documentation.

**Benefits:**

| Feature        | Description                                      |
|----------------|--------------------------------------------------|
| **Fast**       | Built on Starlette and Pydantic                  |
| **Auto-docs**  | Automatic OpenAPI/Swagger documentation          |
| **Type-safe**  | Full type hints and validation                   |
| **Easy**       | Minimal boilerplate code                         |
| **Monitoring** | Built-in logging and metrics                     |

## Quick Start

### 1. Install Dependencies

```bash
pip install fastapi uvicorn swarms
```

### 2. Create Your Agent API

Create a file called `agent_api.py`:

```python
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from swarms import Agent
import uvicorn
from typing import Optional, Dict, Any

# Initialize FastAPI app
app = FastAPI(
    title="Swarms Agent API",
    description="REST API for Swarms agents",
    version="1.0.0"
)

# Pydantic models for request/response
class AgentRequest(BaseModel):
    """Request model for agent tasks"""
    task: str
    agent_name: Optional[str] = "default"
    max_loops: Optional[int] = 1
    temperature: Optional[float] = None

class AgentResponse(BaseModel):
    """Response model for agent tasks"""
    success: bool
    result: str
    agent_name: str
    task: str
    execution_time: Optional[float] = None

# Initialize your agent (you can customize this)
def create_agent(agent_name: str = "default") -> Agent:
    """Create and return a configured agent"""
    return Agent(
        agent_name=agent_name,
        agent_description="Versatile AI agent for various tasks",
        system_prompt="""You are a helpful AI assistant that can handle a wide variety of tasks.
        You provide clear, accurate, and helpful responses while maintaining a professional tone.
        Always strive to be thorough and accurate in your responses.""",
        model_name="claude-sonnet-4-20250514",
        dynamic_temperature_enabled=True,
        max_loops=1,
        dynamic_context_window=True,
    )

# API endpoints
@app.get("/")
async def root():
    """Health check endpoint"""
    return {"message": "Swarms Agent API is running!", "status": "healthy"}

@app.get("/health")
async def health_check():
    """Detailed health check"""
    return {
        "status": "healthy",
        "service": "Swarms Agent API",
        "version": "1.0.0"
    }

@app.post("/agent/run", response_model=AgentResponse)
async def run_agent(request: AgentRequest):
    """Run an agent with the specified task"""
    try:
        import time
        start_time = time.time()
        
        # Create agent instance
        agent = create_agent(request.agent_name)
        
        # Run the agent
        result = agent.run(
            task=request.task,
            max_loops=request.max_loops
        )
        
        execution_time = time.time() - start_time
        
        return AgentResponse(
            success=True,
            result=str(result),
            agent_name=request.agent_name,
            task=request.task,
            execution_time=execution_time
        )
        
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Agent execution failed: {str(e)}")

@app.post("/agent/chat")
async def chat_with_agent(request: AgentRequest):
    """Chat with an agent (conversational mode)"""
    try:
        agent = create_agent(request.agent_name)
        
        # For chat, you might want to maintain conversation history
        # This is a simple implementation
        result = agent.run(
            task=request.task,
            max_loops=request.max_loops
        )
        
        return {
            "success": True,
            "response": str(result),
            "agent_name": request.agent_name
        }
        
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Chat failed: {str(e)}")

@app.get("/agents/available")
async def list_available_agents():
    """List available agent configurations"""
    return {
        "agents": [
            {
                "name": "default",
                "description": "Versatile AI agent for various tasks",
                "model": "claude-sonnet-4-20250514"
            },
            {
                "name": "quantitative-trading",
                "description": "Advanced quantitative trading and algorithmic analysis agent",
                "model": "claude-sonnet-4-20250514"
            }
        ]
    }

# Custom agent endpoint example
@app.post("/agent/quantitative-trading")
async def run_quantitative_trading_agent(request: AgentRequest):
    """Run the quantitative trading agent specifically"""
    try:
        # Create specialized quantitative trading agent
        agent = Agent(
            agent_name="Quantitative-Trading-Agent",
            agent_description="Advanced quantitative trading and algorithmic analysis agent",
            system_prompt="""You are an expert quantitative trading agent with deep expertise in:
            - Algorithmic trading strategies and implementation
            - Statistical arbitrage and market making
            - Risk management and portfolio optimization
            - High-frequency trading systems
            - Market microstructure analysis
            - Quantitative research methodologies
            - Financial mathematics and stochastic processes
            - Machine learning applications in trading""",
            model_name="claude-sonnet-4-20250514",
            dynamic_temperature_enabled=True,
            max_loops=request.max_loops,
            dynamic_context_window=True,
        )
        
        result = agent.run(task=request.task)
        
        return {
            "success": True,
            "result": str(result),
            "agent_name": "Quantitative-Trading-Agent",
            "task": request.task
        }
        
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Quantitative trading agent failed: {str(e)}")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

### 3. Run Your API

```bash
python agent_api.py
```

Or with uvicorn directly:

```bash
uvicorn agent_api:app --host 0.0.0.0 --port 8000 --reload
```

### 4. Test Your API

Your API will be available at:

- **API**: http://localhost:8000

- **Documentation**: http://localhost:8000/docs

- **Alternative docs**: http://localhost:8000/redoc

## Usage Examples

### Using curl

```bash
# Basic agent task
curl -X POST "http://localhost:8000/agent/run" \
     -H "Content-Type: application/json" \
     -d '{"task": "What are the best top 3 ETFs for gold coverage?"}'

# Quantitative trading agent
curl -X POST "http://localhost:8000/agent/quantitative-trading" \
     -H "Content-Type: application/json" \
     -d '{"task": "Analyze the current market conditions for gold ETFs"}'
```

### Using Python requests

```python
import requests

# Run basic agent
response = requests.post(
    "http://localhost:8000/agent/run",
    json={"task": "Explain quantum computing in simple terms"}
)
print(response.json())

# Run quantitative trading agent
response = requests.post(
    "http://localhost:8000/agent/quantitative-trading",
    json={"task": "What are the key factors affecting gold prices today?"}
)
print(response.json())
```

## Advanced Configuration

### Environment Variables

Create a `.env` file for configuration:

```bash
# .env
AGENT_MODEL_NAME=claude-sonnet-4-20250514
AGENT_MAX_LOOPS=3
API_HOST=0.0.0.0
API_PORT=8000
LOG_LEVEL=info
```

### Enhanced Agent Factory

```python
import os
from typing import Dict, Type
from swarms import Agent

class AgentFactory:
    """Factory for creating different types of agents"""
    
    AGENT_CONFIGS = {
        "default": {
            "agent_name": "Default-Agent",
            "agent_description": "Versatile AI agent for various tasks",
            "system_prompt": "You are a helpful AI assistant...",
            "model_name": "claude-sonnet-4-20250514"
        },
        "quantitative-trading": {
            "agent_name": "Quantitative-Trading-Agent",
            "agent_description": "Advanced quantitative trading agent",
            "system_prompt": "You are an expert quantitative trading agent...",
            "model_name": "claude-sonnet-4-20250514"
        },
        "research": {
            "agent_name": "Research-Agent",
            "agent_description": "Academic research and analysis agent",
            "system_prompt": "You are an expert research agent...",
            "model_name": "claude-sonnet-4-20250514"
        }
    }
    
    @classmethod
    def create_agent(cls, agent_type: str = "default", **kwargs) -> Agent:
        """Create an agent of the specified type"""
        if agent_type not in cls.AGENT_CONFIGS:
            raise ValueError(f"Unknown agent type: {agent_type}")
        
        config = cls.AGENT_CONFIGS[agent_type].copy()
        config.update(kwargs)
        
        return Agent(**config)
```

### Authentication & Rate Limiting

```python
from fastapi import Depends, HTTPException, status
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
import time

# Rate limiting
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

# Security
security = HTTPBearer()

def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)):
    """Verify API token"""
    # Implement your token verification logic here
    if credentials.credentials != "your-secret-token":
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid token"
        )
    return credentials.credentials

@app.post("/agent/run", response_model=AgentResponse)
@limiter.limit("10/minute")
async def run_agent(
    request: AgentRequest,
    token: str = Depends(verify_token)
):
    """Run an agent with authentication and rate limiting"""
    # ... existing code ...
```

## Production Deployment

### Using Gunicorn

```bash
pip install gunicorn
gunicorn agent_api:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
```

### Using Docker

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "agent_api:app", "--host", "0.0.0.0", "--port", "8000"]
```

### Using Docker Compose

```yaml
version: '3.8'
services:
  agent-api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - AGENT_MODEL_NAME=claude-sonnet-4-20250514
    volumes:
      - ./logs:/app/logs
```

## Monitoring & Logging

### Structured Logging

```python
import logging
import json
from datetime import datetime

# Configure logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.middleware("http")
async def log_requests(request, call_next):
    """Log all requests and responses"""
    start_time = time.time()
    
    # Log request
    logger.info(f"Request: {request.method} {request.url}")
    
    response = await call_next(request)
    
    # Log response
    process_time = time.time() - start_time
    logger.info(f"Response: {response.status_code} - {process_time:.2f}s")
    
    return response
```

### Health Checks

```python
@app.get("/health/detailed")
async def detailed_health_check():
    """Detailed health check with agent status"""
    try:
        # Test agent creation
        agent = create_agent()
        
        return {
            "status": "healthy",
            "timestamp": datetime.utcnow().isoformat(),
            "agent_status": "available",
            "model_status": "connected"
        }
    except Exception as e:
        return {
            "status": "unhealthy",
            "timestamp": datetime.utcnow().isoformat(),
            "error": str(e)
        }
```

## Best Practices

| Best Practice         | Description                                               |
|----------------------|-----------------------------------------------------------|
| **Error Handling**   | Always wrap agent execution in try-catch blocks           |
| **Validation**       | Use Pydantic models for request validation                |
| **Rate Limiting**    | Implement rate limiting for production APIs               |
| **Authentication**   | Add proper authentication for sensitive endpoints         |
| **Logging**          | Log all requests and responses for debugging              |
| **Monitoring**       | Add health checks and metrics                             |
| **Testing**          | Write tests for your API endpoints                        |
| **Documentation**    | Keep your API documentation up to date                    |

## Troubleshooting

### Common Issues

1. **Port already in use**: Change the port in the uvicorn command
2. **Agent initialization fails**: Check your API keys and model configuration
3. **Memory issues**: Reduce `max_loops` or implement streaming responses
4. **Timeout errors**: Increase timeout settings for long-running tasks

### Performance Tips

| Performance Tip           | Description                                         |
|--------------------------|-----------------------------------------------------|
| **Connection pooling**    | Reuse agent instances when possible                |
| **Async operations**      | Use async/await for I/O operations                 |
| **Caching**               | Cache frequently requested responses               |
| **Load balancing**        | Use multiple worker processes for high traffic     |


Your FastAPI agent API is now ready to handle requests and scale with your needs!


--------------------------------------------------

# File: deployment_solutions/overview.md

# Deployment Solutions Overview

This section covers various deployment strategies for Swarms agents and multi-agent systems, from simple local deployments to enterprise-grade cloud solutions.

## Deployment Types Comparison & Documentation

| Deployment Type         | Use Case            | Complexity | Scalability | Cost      | Best For                        | Documentation Link                                                          | Status     |
|------------------------|---------------------|------------|-------------|-----------|----------------------------------|-----------------------------------------------------------------------------|------------|
| **FastAPI + Uvicorn**  | REST API endpoints  | Low        | Medium      | Low       | Quick prototypes, internal tools | [FastAPI Agent API Guide](fastapi_agent_api.md)                             | Available  |
| **Cron Jobs**          | Scheduled tasks     | Low        | Low         | Very Low  | Batch processing, periodic tasks | [Cron Job Examples](../../examples/deployment_solutions/cron_job_examples/) | Available  |


## Quick Start Guide

### 1. FastAPI + Uvicorn (Recommended for APIs)

- **Best for**: Creating REST APIs for your agents

- **Setup time**: 5-10 minutes

- **Documentation**: [FastAPI Agent API](fastapi_agent_api.md)

- **Example Code**: [FastAPI Example](../../examples/deployment_solutions/fastapi_agent_api_example.py)


### 2. Cron Jobs (Recommended for scheduled tasks)

- **Best for**: Running agents on a schedule

- **Setup time**: 2-5 minutes

- **Examples**: [Cron Job Examples](../../examples/deployment_solutions/cron_job_examples/)



## Deployment Considerations

### Performance

- **FastAPI**: Excellent for high-throughput APIs

- **Cron Jobs**: Good for batch processing

- **Docker**: Consistent performance across environments

- **Kubernetes**: Best for complex, scalable systems


### Security

- **FastAPI**: Built-in security features, easy to add authentication

- **Cron Jobs**: Runs with system permissions

- **Docker**: Isolated environment, security best practices

- **Kubernetes**: Advanced security policies and RBAC


### Monitoring & Observability

- **FastAPI**: Built-in logging, easy to integrate with monitoring tools

- **Cron Jobs**: Basic logging, requires custom monitoring setup

- **Docker**: Container-level monitoring, easy to integrate

- **Kubernetes**: Comprehensive monitoring and alerting


### Cost Optimization

- **FastAPI**: Pay for compute resources

- **Cron Jobs**: Minimal cost, runs on existing infrastructure

- **Docker**: Efficient resource utilization

- **Kubernetes**: Advanced resource management and auto-scaling


## Choosing the Right Deployment

### For Development & Testing

- **FastAPI + Uvicorn**: Quick setup, easy debugging

- **Cron Jobs**: Simple scheduled tasks


### For Production APIs

- **FastAPI + Docker**: Reliable, scalable

- **Cloud Run**: Auto-scaling, managed infrastructure


### For Enterprise Systems

- **Kubernetes**: Full control, advanced features

- **Hybrid approach**: Mix of deployment types based on use case


### For Cost-Sensitive Projects

- **Cron Jobs**: Minimal infrastructure cost

- **Cloud Functions**: Pay-per-use model

- **FastAPI**: Efficient resource utilization


## Next Steps

1. **Start with FastAPI** if you need an API endpoint
2. **Use Cron Jobs** for scheduled tasks
3. **Move to Docker** when you need consistency
4. **Consider Kubernetes** for complex, scalable systems

Each deployment solution includes detailed examples and step-by-step guides to help you get started quickly.


--------------------------------------------------

# File: docs_structure.md

# Class/function

Brief description
↓

↓  
## Overview
↓
## Architecture (Mermaid diagram)
↓
## Class Reference (Constructor + Methods)

table of parameters for every method and example

↓
## Examples

↓

## Conclusion
Benefits of class/structure, and more



--------------------------------------------------

# File: examples/agent_stream.md

# Agent with Streaming

The Swarms framework provides powerful real-time streaming capabilities for agents, allowing you to see responses being generated token by token as they're produced by the language model. This creates a more engaging and interactive experience, especially useful for long-form content generation, debugging, or when you want to provide immediate feedback to users.

## Installation

Install the swarms package using pip:

```bash
pip install -U swarms
```

## Basic Setup

1. First, set up your environment variables:

```python
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
```

## Step by Step

- Install and put your keys in `.env`

- Turn on streaming in `Agent()` with `streaming_on=True`

- Optional: If you want to pretty print it, you can do `print_on=True`; if not, it will print normally

## Code

```python
from swarms import Agent

# Enable real-time streaming
agent = Agent(
    agent_name="StoryAgent",
    model_name="gpt-4o-mini",
    streaming_on=True,  # 🔥 This enables real streaming!
    max_loops=1,
    print_on=True,  # By default, it's False for raw streaming!
)

# This will now stream in real-time with a beautiful UI!
response = agent.run("Tell me a detailed story about humanity colonizing the stars")
print(response)
```

## Connect With Us

If you'd like technical support, join our Discord below and stay updated on our Twitter for new updates!

| Platform | Link | Description |
|----------|------|-------------|
| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides |
| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles |
| 💬 Discord | [Join Discord](https://discord.gg/EamjgSaEQf) | Live chat and community support |
| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements |
| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates |
| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos |
| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events |



--------------------------------------------------

# File: examples/community_resources.md

# Community Resources

Welcome to the Community Resources page! Here you'll find a curated collection of articles, tutorials, and guides created by the Swarms community and core contributors. 

These resources cover a wide range of topics, including building your first agent, advanced multi-agent architectures, API integrations, and using Swarms with both Python and Rust. Whether you're a beginner or an experienced developer, these links will help you deepen your understanding and accelerate your development with the Swarms framework.


## Swarms Python

| Title | Description | Link |
|-------|-------------|------|
| **Build Your First Swarms Agent in Under 10 Minutes** | Step-by-step beginner guide to creating your first Swarms agent quickly. | [Read Article](https://medium.com/@devangvashistha/build-your-first-swarms-agent-in-under-10-minutes-ddff23b6c703) |
| **Building Multi-Agent Systems with GPT-5 and The Swarms Framework** | Learn how to leverage GPT-5 with Swarms for advanced multi-agent system design. | [Read Article](https://medium.com/@kyeg/building-multi-agent-systems-with-gpt-5-and-the-swarms-framework-e52ffaf0fa4f) |
| **Learn How to Build Production-Grade Agents with OpenAI’s Latest Model: GPT-OSS Locally and in the Cloud** | Guide to building robust agents using OpenAI’s GPT-OSS, both locally and in cloud environments. | [Read Article](https://medium.com/@kyeg/learn-how-to-build-production-grade-agents-with-openais-latest-model-gpt-oss-locally-and-in-the-c5826c7cca7c) |
| **Building Gemini 2.5 Agents with Swarms Framework** | Tutorial on integrating Gemini 2.5 models into Swarms agents for enhanced capabilities. | [Read Article](https://medium.com/@kyeg/building-gemini-2-5-agents-with-swarms-framework-20abdcf82cac) |
| **Enterprise Developer Guide: Leveraging OpenAI’s o3 and o4-mini Models with The Swarms Framework** | Enterprise-focused guide to using OpenAI’s o3 and o4-mini models within Swarms. | [Read Article](https://medium.com/@kyeg/enterprise-developer-guide-leveraging-openais-o3-and-o4-mini-models-with-the-swarms-framework-89490c57820a) |
| **Enneagram of Thoughts Using the Swarms Framework: A Multi-Agent Approach to Holistic Problem Solving** | Explores using Swarms for holistic, multi-perspective problem solving via the Enneagram model. | [Read Article](https://medium.com/@kyeg/enneagram-of-thoughts-using-the-swarms-framework-a-multi-agent-approach-to-holistic-problem-c26c7df5e7eb) |
| **Building Production-Grade Financial Agents with tickr-agent: An Enterprise Solution for Comprehensive Stock Analysis** | How to build advanced financial analysis agents using tickr-agent and Swarms. | [Read Article](https://medium.com/@kyeg/building-production-grade-financial-agents-with-tickr-agent-an-enterprise-solution-for-db867ec93193) |
| **Automating Your Startup’s Financial Analysis Using AI Agents: A Comprehensive Guide** | Comprehensive guide to automating your startup’s financial analysis with AI agents using Swarms. | [Read Article](https://medium.com/@kyeg/automating-your-startups-financial-analysis-using-ai-agents-a-comprehensive-guide-b2fa0e2c09d5) |
| **Managing Thousands of Agent Outputs at Scale with The Spreadsheet Swarm: All-New Multi-Agent Architecture** | Learn how to manage and scale thousands of agent outputs efficiently using the Spreadsheet Swarm architecture. | [Read Article](https://medium.com/@kyeg/managing-thousands-of-agent-outputs-at-scale-with-the-spreadsheet-swarm-all-new-multi-agent-f16f5f40fd5a) |
| **Introducing GPT-4o Mini: The Future of Cost-Efficient AI Intelligence** | Discover the capabilities and advantages of GPT-4o Mini for building cost-effective, intelligent agents. | [Read Article](https://medium.com/@kyeg/introducing-gpt-4o-mini-the-future-of-cost-efficient-ai-intelligence-a3e3fe78d939) |
| **Introducing Swarm's GraphWorkflow: A Faster, Simpler, and Superior Alternative to LangGraph** | Learn about Swarms' GraphWorkflow, a powerful alternative to LangGraph that offers improved performance and simplicity for building complex agent workflows. | [Read Article](https://medium.com/@kyeg/introducing-swarms-graphworkflow-a-faster-simpler-and-superior-alternative-to-langgraph-5c040225a4f1) |


### Swarms API

| Title | Description | Link |
|-------|-------------|------|
| **Specialized Healthcare Agents with Swarms Agent Completions API** | Guide to building healthcare-focused agents using the Swarms API. | [Read Article](https://medium.com/@kyeg/specialized-healthcare-agents-with-swarms-agent-completions-api-b56d067e3b11) |
| **Building Multi-Agent Systems for Finance & Accounting with the Swarms API: A Technical Guide** | Technical walkthrough for creating finance and accounting multi-agent systems with the Swarms API. | [Read Article](https://medium.com/@kyeg/building-multi-agent-systems-for-finance-accounting-with-the-swarms-api-a-technical-guide-bf6f7005b708) |

### Swarms Rust

| Title | Description | Link |
|-------|-------------|------|
| **Building Medical Multi-Agent Systems with Swarms Rust: A Comprehensive Tutorial** | Comprehensive tutorial for developing medical multi-agent systems using Swarms Rust. | [Read Article](https://medium.com/@kyeg/building-medical-multi-agent-systems-with-swarms-rust-a-comprehensive-tutorial-1e8e060601f9) |
| **Building Production-Grade Agentic Applications with Swarms Rust: A Comprehensive Tutorial** | Learn to build robust, production-ready agentic applications with Swarms Rust. | [Read Article](https://medium.com/@kyeg/building-production-grade-agentic-applications-with-swarms-rust-a-comprehensive-tutorial-bb567c02340f) |


### Youtube Videos

- [Swarms Playlist by Swarms Founder Kye Gomez](https://www.youtube.com/watch?v=FzbBRbaqsG8&list=PLphplB7PcU1atnmrUl7lJ5bmGXR7R4lhA)

--------------------------------------------------

# File: examples/cookbook_index.md

# Swarms Cookbook Examples Index

This index provides a categorized list of examples and tutorials for using the Swarms Framework across different industries. Each example demonstrates practical applications and implementations using the framework.

## Finance & Trading

| Name | Description | Link |
|------|-------------|------|
| Tickr-Agent | Financial analysis agent for stock market data using multithreaded processing and AI integration | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/Swarms_Cookbook_Tickr_Agent.ipynb) |
| CryptoAgent | Real-time cryptocurrency data analysis and insights using CoinGecko integration | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/Swarms_Cookbook_CryptoAgent.ipynb) |
| 10-K Analysis (Custom) | Detailed analysis of SEC 10-K reports using specialized agents | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/swarms_finance_10k_analysis_custom.ipynb) |
| 10-K Analysis (AgentRearrange) | Mixed sequential and parallel analysis of 10-K reports | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/finance/multi_agent/swarms_finance_10k_analysis_agentrearrange.ipynb) |

## Healthcare & Medical

| Name | Description | Link |
|------|-------------|------|
| MedInsight Pro | Medical research summarization and analysis using AI-driven agents | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/medical/physical_therapy/Swarms_Cookbook_MedInsight_Pro.ipynb) |
| Athletics Diagnosis | Diagnosis and treatment system for extreme athletics using AgentRearrange | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/medical/physical_therapy/swarms_diagnosis_treatment_extreme_athletics.ipynb) |

## Marketing & Content

| Name | Description | Link |
|------|-------------|------|
| NewsAgent | Real-time news aggregation and summarization for business intelligence | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/marketing/news/Swarms_Cookbook_NewsAgent.ipynb) |
| Social Media Marketing | Spreadsheet-based content generation for multi-platform marketing | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/marketing/content_generation/swarms_spreadsheet_analysis_walkthrough.ipynb) |

## Accounting & Finance Operations

| Name | Description | Link |
|------|-------------|------|
| Accounting Agents | Multi-agent system for financial projections and risk assessment | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/enterprise/accounting/multi_agent/accounting_agents_for_moa.ipynb) |

## Workshops & Tutorials

| Name | Description | Link |
|------|-------------|------|
| GPTuesday Event | Example of creating promotional content for tech events | [View Example](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/cookbook/workshops/sep_6_workshop/gptuesday_swarm.py) |

## Additional Resources

| Platform | Link | Description |
|----------|------|-------------|
| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides |
| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles |
| 💬 Discord | [Join Discord](https://discord.gg/EamjgSaEQf) | Live chat and community support |
| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements |
| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates |
| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos |
| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events |

## Contributing

We welcome contributions! If you have an example or tutorial you'd like to add, please check our [contribution guidelines](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/CONTRIBUTING.md).

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/The-Swarm-Corporation/Cookbook/blob/main/LICENSE) file for details. 

--------------------------------------------------

# File: examples/index.md

# Swarms Examples Index

Welcome to the comprehensive Swarms Examples Index! This curated collection showcases the power and versatility of the Swarms framework for building intelligent multi-agent systems. Whether you're a beginner looking to get started or an advanced developer seeking complex implementations, you'll find practical examples to accelerate your AI development journey.

## What is Swarms?

Swarms is a cutting-edge framework for creating sophisticated multi-agent AI systems that can collaborate, reason, and solve complex problems together. From single intelligent agents to coordinated swarms of specialized AI workers, Swarms provides the tools and patterns you need to build the next generation of AI applications.

## What You'll Find Here

This index organizes **100+ production-ready examples** from our [Swarms Examples Repository](https://github.com/The-Swarm-Corporation/swarms-examples) and the main Swarms repository, covering:


- **Single Agent Systems**: From basic implementations to advanced reasoning agents

- **Multi-Agent Architectures**: Collaborative swarms, hierarchical systems, and experimental topologies

- **Industry Applications**: Real-world use cases across finance, healthcare, security, and more

- **Integration Examples**: Connect with popular AI models, tools, and frameworks

- **Advanced Patterns**: RAG systems, function calling, MCP integration, and more

## Getting Started

**New to Swarms?** Start with the [Easy Example](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/easy_example.py) under Single Agent Examples → Core Agents.

**Looking for comprehensive tutorials?** Check out [The Swarms Cookbook](https://github.com/The-Swarm-Corporation/Cookbook) for detailed walkthroughs and advanced patterns.

**Want to see real-world applications?** Explore the Industry Applications section to see how Swarms solves practical problems.

## Quick Navigation


- [Single Agent Examples](#single-agent-examples) - Individual AI agents with various capabilities

- [Multi-Agent Examples](#multi-agent-examples) - Collaborative systems and swarm architectures

- [Additional Resources](#additional-resources) - Community links and support channels

## Single Agent Examples

### Core Agents
| Category | Example | Description |
|----------|---------|-------------|
| Basic | [Easy Example](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/easy_example.py) | Basic agent implementation demonstrating core functionality and setup |
| Settings | [Agent Settings](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/agent_settings.py) | Comprehensive configuration options for customizing agent behavior and capabilities |
| YAML | [Agents from YAML](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/agents_from_yaml_example.py) | Creating and configuring agents using YAML configuration files for easy deployment |
| Memory | [Agent with Long-term Memory](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/memory/agents_and_memory/agent_with_longterm_memory.py) | Implementation of persistent memory capabilities for maintaining context across sessions |

### Model Integrations
| Category | Example | Description |
|----------|---------|-------------|
| Azure | [Azure OpenAI Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/settings/various_models/basic_agent_with_azure_openai.py) | Integration with Azure OpenAI services for enterprise-grade AI capabilities |
| Groq | [Groq Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/settings/various_models/groq_agent.py) | High-performance inference using Groq's accelerated computing platform |
| Custom | [Custom Model Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/settings/various_models/custom_model_with_agent.py) | Framework for integrating custom ML models into the agent architecture |
| Cerebras | [Cerebras Example](https://github.com/kyegomez/swarms/blob/master/examples/models/cerebas_example.py) | Integration with Cerebras AI platform for high-performance model inference |
| Claude | [Claude 4 Example](https://github.com/kyegomez/swarms/blob/master/examples/models/claude_4_example.py) | Anthropic Claude 4 model integration for advanced reasoning capabilities |
| Swarms Claude | [Swarms Claude Example](https://github.com/kyegomez/swarms/blob/master/examples/models/swarms_claude_example.py) | Optimized Claude integration within the Swarms framework |
| Lumo | [Lumo Example](https://github.com/kyegomez/swarms/blob/master/examples/models/lumo_example.py) | Lumo AI model integration for specialized tasks |
| VLLM | [VLLM Example](https://github.com/kyegomez/swarms/blob/master/examples/models/vllm_example.py) | High-performance inference using VLLM for large language models |
| Llama4 | [LiteLLM Example](https://github.com/kyegomez/swarms/blob/master/examples/models/llama4_examples/litellm_example.py) | Llama4 model integration using LiteLLM for efficient inference |

### Tools and Function Calling
| Category | Example | Description |
|----------|---------|-------------|
| Basic Tools | [Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent.py) | Basic tool-using agent demonstrating external tool integration capabilities |
| Advanced Tools | [Agent with Many Tools](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/agent_with_many_tools.py) | Advanced agent utilizing multiple tools for complex task execution |
| OpenAI Functions | [OpenAI Function Caller](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/function_calling/openai_function_caller_example.py) | Integration with OpenAI's function calling API for structured outputs |
| Command Line | [Command Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent/command_r_tool_agent.py) | Command-line interface tool integration |
| Jamba | [Jamba Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent/jamba_tool_agent.py) | Integration with Jamba framework for enhanced tool capabilities |
| Pydantic | [Pydantic Tool Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/tools/tool_agent/tool_agent_pydantic.py) | Tool validation and schema enforcement using Pydantic |
| Function Caller | [Function Caller Example](https://github.com/kyegomez/swarms/blob/master/examples/demos/spike/function_caller_example.py) | Advanced function calling capabilities with dynamic tool execution |
| LiteLLM Tools | [LiteLLM Tool Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/tools/litellm_tool_example.py) | Tool integration using LiteLLM for model-agnostic function calling |
| Swarms Tools | [Swarms Tools Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/tools/swarms_tools_example.py) | Native Swarms tool ecosystem integration |
| Structured Outputs | [Structured Outputs Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/tools/structured_outputs/structured_outputs_example.py) | Structured data output capabilities for consistent responses |
| Schema Validation | [Schema Validation Example](https://github.com/kyegomez/swarms/blob/master/examples/tools/base_tool_examples/schema_validation_example.py) | Tool schema validation and error handling |

### MCP (Model Context Protocol) Integration
| Category | Example | Description |
|----------|---------|-------------|
| Agent Tools | [Agent Tools Dict Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_examples/agent_use/agent_tools_dict_example.py) | MCP integration for dynamic tool management |
| MCP Execute | [MCP Execute Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_examples/utils/mcp_execute_example.py) | MCP command execution and response handling |
| MCP Load Tools | [MCP Load Tools Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_examples/utils/mcp_load_tools_example.py) | Dynamic tool loading through MCP protocol |
| Multiple Servers | [MCP Multiple Servers Example](https://github.com/kyegomez/swarms/blob/master/examples/mcp/mcp_utils/mcp_multiple_servers_example.py) | Multi-server MCP configuration and management |

### RAG and Memory
| Category | Example | Description |
|----------|---------|-------------|
| Full RAG | [Full Agent RAG Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/rag/full_agent_rag_example.py) | Complete RAG implementation with retrieval and generation |
| Pinecone | [Pinecone Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/rag/pinecone_example.py) | Vector database integration using Pinecone for semantic search |

### Reasoning and Decision Making
| Category | Example | Description |
|----------|---------|-------------|
| Agent Judge | [Agent Judge Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/reasoning_agent_examples/agent_judge_example.py) | Agent-based decision making and evaluation system |
| MALT | [MALT Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/reasoning_agent_examples/malt_example.py) | Multi-agent logical reasoning framework |
| Reasoning Duo | [Reasoning Duo Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/reasoning_agent_examples/reasoning_duo_example.py) | Collaborative reasoning between two specialized agents |

### Vision and Multimodal
| Category | Example | Description |
|----------|---------|-------------|
| Image Batch | [Image Batch Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/vision/image_batch_example.py) | Batch processing of multiple images with vision capabilities |
| Multimodal | [Multimodal Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/vision/multimodal_example.py) | Multi-modal agent supporting text, image, and audio inputs |

### Utilities and Output Formats
| Category | Example | Description |
|----------|---------|-------------|
| XML Output | [XML Output Example](https://github.com/kyegomez/swarms/blob/master/examples/single_agent/utils/xml_output_example.py) | Structured XML output formatting for agent responses |
| CSV Agent | [CSV Agent Example](https://github.com/kyegomez/swarms/blob/master/examples/misc/csvagent_example.py) | CSV data processing and manipulation agent |
| Swarm Matcher | [Swarm Matcher Example](https://github.com/kyegomez/swarms/blob/master/examples/misc/swarm_matcher_example.py) | Agent matching and selection system |

### Third-Party Integrations
| Category | Example | Description |
|----------|---------|-------------|
| Microsoft | [AutoGen Integration](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/auto_gen.py) | Integration with Microsoft's AutoGen framework for autonomous agents |
| LangChain | [LangChain Integration](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/langchain.py) | Combining LangChain's capabilities with Swarms for enhanced functionality |
| Browser | [Multion Integration](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/multion_agent.py) | Web automation and browsing capabilities using Multion |
| Team AI | [Crew AI](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/crew_ai.py) | Team-based AI collaboration using Crew AI framework |
| Development | [Griptape](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/3rd_party_agents/griptape.py) | Integration with Griptape for structured AI application development |

### Industry-Specific Agents
| Category | Example | Description |
|----------|---------|-------------|
| Finance | [401k Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/finance/401k_agent.py) | Retirement planning assistant with investment strategy recommendations |
| Finance | [Estate Planning](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/finance/estate_planning_agent.py) | Comprehensive estate planning and wealth management assistant |
| Security | [Perimeter Defense](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/security/perimeter_defense_agent.py) | Security monitoring and threat detection system |
| Research | [Perplexity Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/research/perplexity_agent.py) | Advanced research automation using Perplexity AI integration |
| Legal | [Alberto Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/law/alberto_agent.py) | Legal research and document analysis assistant |
| Healthcare | [Pharma Agent](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/agents/use_cases/pharma/pharma_agent_two.py) | Pharmaceutical research and drug interaction analysis |

## Multi-Agent Examples

### Core Architectures
| Category | Example | Description |
|----------|---------|-------------|
| Basic | [Build a Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/base_swarm/build_a_swarm.py) | Foundation for creating custom swarm architectures with multiple agents |
| Auto Swarm | [Auto Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/auto_swarm/auto_swarm_example.py) | Self-organizing swarm with automatic task distribution and management |
| Concurrent | [Concurrent Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/concurrent_swarm/concurrent_swarm_example.py) | Parallel execution of tasks across multiple agents for improved performance |
| Star | [Star Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/different_architectures/star_swarm.py) | Centralized architecture with a hub agent coordinating peripheral agents |
| Circular | [Circular Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/different_architectures/circular_swarm.py) | Ring topology for cyclic information flow between agents |
| Graph Workflow | [Graph Workflow Basic](https://github.com/kyegomez/swarms/blob/main/examples/structs/graph_workflow_basic.py) | Minimal graph workflow with two agents and one task |

### Concurrent and Parallel Processing
| Category | Example | Description |
|----------|---------|-------------|
| Concurrent | [Concurrent Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/concurrent_examples/concurrent_example.py) | Basic concurrent execution of multiple agents |
| Concurrent Swarm | [Concurrent Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/concurrent_examples/concurrent_swarm_example.py) | Advanced concurrent swarm with parallel task processing |

### Hierarchical and Sequential Workflows
| Category | Example | Description |
|----------|---------|-------------|
| Hierarchical | [Hierarchical Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/hiearchical_swarm/hiearchical_examples/hierarchical_swarm_example.py) | Multi-level hierarchical agent organization |
| Hierarchical Basic | [Hierarchical Swarm Basic](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/hiearchical_swarm/hiearchical_swarm-example.py) | Simplified hierarchical swarm implementation |
| Hierarchical Advanced | [Hierarchical Advanced](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/hiearchical_swarm/hierarchical_swarm_example.py) | Advanced hierarchical swarm with complex agent relationships |
| Sequential Workflow | [Sequential Workflow Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/sequential_workflow/sequential_workflow_example.py) | Linear workflow with agents processing tasks in sequence |
| Sequential Swarm | [Sequential Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/sequential_workflow/sequential_swarm_example.py) | Sequential swarm with coordinated task execution |

### Group Chat and Interactive Systems
| Category | Example | Description |
|----------|---------|-------------|
| Group Chat | [Group Chat Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/groupchat_examples/group_chat_example.py) | Multi-agent group chat system with turn-based communication |
| Group Chat Advanced | [Group Chat Advanced](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/groupchat_examples/groupchat_example.py) | Advanced group chat with enhanced interaction capabilities |
| Mortgage Panel | [Mortgage Tax Panel](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/groupchat_examples/mortgage_tax_panel_example.py) | Specialized panel for mortgage and tax discussions |
| Interactive Group Chat | [Interactive Group Chat](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/interactive_groupchat_example.py) | Interactive group chat with real-time user participation |
| Dynamic Speaker | [Random Dynamic Speaker](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/groupchat/random_dynamic_speaker_example.py) | Dynamic speaker selection in group conversations |
| Interactive Speaker | [Interactive Speaker Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/interactive_groupchat_examples/interactive_groupchat_speaker_example.py) | Interactive speaker management in group chats |
| Medical Panel | [Medical Panel Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/interactive_groupchat_examples/medical_panel_example.py) | Medical expert panel for healthcare discussions |
| Stream Example | [Stream Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/interactive_groupchat_examples/stream_example.py) | Streaming capabilities in interactive group chats |

### Research and Deep Analysis
| Category | Example | Description |
|----------|---------|-------------|
| Advanced Research | [Advanced Research System](https://github.com/The-Swarm-Corporation/AdvancedResearch) | Multi-agent research system inspired by Anthropic's research methodology with orchestrator-worker architecture |
| Deep Research | [Deep Research Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/deep_research_examples/deep_research_example.py) | Comprehensive research system with multiple specialized agents |
| Deep Research Swarm | [Deep Research Swarm](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/deep_research_examples/deep_research_swarm_example.py) | Swarm-based deep research with collaborative analysis |
| Scientific Agents | [Deep Research Swarm Example](https://github.com/kyegomez/swarms/blob/master/examples/demos/scient_agents/deep_research_swarm_example.py) | Scientific research swarm for academic and research applications |

### Routing and Decision Making
| Category | Example | Description |
|----------|---------|-------------|
| Model Router | [Model Router Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/model_router_example.py) | Intelligent routing of tasks to appropriate model agents |
| Multi-Agent Router | [Multi-Agent Router Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/multi_agent_router_example.py) | Advanced routing system for multi-agent task distribution |
| Swarm Router | [Swarm Router Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/swarm_router/swarm_router_example.py) | Swarm-specific routing and load balancing |
| Majority Voting | [Majority Voting Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/majority_voting/majority_voting_example.py) | Consensus-based decision making using majority voting |

### Council and Collaborative Systems
| Category | Example | Description |
|----------|---------|-------------|
| Council Judge | [Council Judge Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/council/council_judge_example.py) | Council-based decision making with expert judgment |

### Advanced Collaboration
| Category | Example | Description |
|----------|---------|-------------|
| Enhanced Collaboration | [Enhanced Collaboration Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/enhanced_collaboration_example.py) | Advanced collaboration patterns between multiple agents |
| Mixture of Agents | [Mixture of Agents Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mixture_of_agents_example.py) | Heterogeneous agent mixture for diverse task handling |
| Aggregate | [Aggregate Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/aggregate_example.py) | Aggregation of results from multiple agents |

### API and Integration
| Category | Example | Description |
|----------|---------|-------------|
| Swarms API | [Swarms API Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/swarms_api_examples/swarms_api_example.py) | API integration for Swarms multi-agent systems |

### Utilities and Batch Processing
| Category | Example | Description |
|----------|---------|-------------|
| Batch Agent | [Batch Agent Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/utils/batch_agent_example.py) | Batch processing capabilities for multiple agents |

### Experimental Architectures
| Category | Example | Description |
|----------|---------|-------------|
| Monte Carlo | [Monte Carlo Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/monte_carlo_swarm.py) | Probabilistic decision-making using Monte Carlo simulation across agents |
| Federated | [Federated Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/federated_swarm.py) | Distributed learning system with privacy-preserving agent collaboration |
| Ant Colony | [Ant Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/ant_swarm.py) | Bio-inspired optimization using ant colony algorithms for agent coordination |
| Matrix | [Agent Matrix](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/agent_matrix.py) | Grid-based agent organization for complex problem-solving |
| DFS | [DFS Search Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/dfs_search_swarm.py) | Depth-first search swarm for complex problem exploration |
| Pulsar | [Pulsar Swarm](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/experimental/pulsar_swarm.py) | Pulsar-based coordination for synchronized agent behavior |

### Collaboration Patterns
| Category | Example | Description |
|----------|---------|-------------|
| Delegation | [Agent Delegation](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/agent_delegation.py) | Task delegation and management system |
| Communication | [Message Pool](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/message_pool.py) | Shared communication system for efficient agent interaction |
| Scheduling | [Round Robin](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/round_robin_example.py) | Round-robin task scheduling and execution |
| Load Balancing | [Load Balancer](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/load_balancer_example.py) | Dynamic task distribution system for optimal resource utilization |
| Consensus | [Majority Voting](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/structs/swarms/multi_agent_collaboration/majority_voting.py) | Consensus-building system using democratic voting among agents |

### Industry Applications
| Category | Example | Description |
|----------|---------|-------------|
| Finance | [Accountant Team](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/accountant_team/account_team2_example.py) | Multi-agent system for financial analysis, bookkeeping, and tax planning |
| Marketing | [Ad Generation](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/ad_gen/ad_gen_example.py) | Collaborative ad creation with copywriting and design agents |
| Aerospace | [Space Traffic Control](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/agentic_space_traffic_control/game.py) | Complex simulation of space traffic management with multiple coordinating agents |
| Agriculture | [Plant Biology](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/plant_biologist_swarm/agricultural_swarm.py) | Agricultural analysis and optimization using specialized biology agents |
| Urban Dev | [Urban Planning](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/urban_planning/urban_planning_example.py) | City development planning with multiple specialized urban development agents |
| Education | [Education System](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/education/education_example.py) | Personalized learning system with multiple teaching and assessment agents |
| Security | [Email Phishing Detection](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/email_phiser/email_swarm.py) | Multi-agent security analysis and threat detection |
| Fashion | [Personal Stylist](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/personal_stylist/personal_stylist_example.py) | Fashion recommendation system with style analysis and matching agents |
| Healthcare | [Healthcare Assistant](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/positive_med/positive_med_example.py) | Medical diagnosis and treatment planning with specialist consultation agents |
| Security Ops | [Security Team](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/security_team/security_team_example.py) | Comprehensive security operations with threat detection and response agents |
| Medical | [X-Ray Analysis](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/demos/xray/xray_example.py) | Multi-agent medical imaging analysis and diagnosis |
| Business | [Business Strategy](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/business_strategy/business_strategy_graph/growth_agent.py) | Strategic planning and business development swarm |
| Research | [Astronomy Research](https://github.com/The-Swarm-Corporation/swarms-examples/blob/main/examples/applications/astronomy/multiversal_detection/test.py) | Collaborative space research and astronomical analysis |

## Additional Resources

- [Github](https://github.com/kyegomez/swarms)

- Discord (https://t.co/zlLe07AqUX)

- Telegram (https://t.co/dSRy143zQv)

- X Community (https://x.com/i/communities/1875452887414804745)

--------------------------------------------------

# File: examples/paper_implementations.md

# Multi-Agent Paper Implementations

At Swarms, we are passionate about democratizing access to cutting-edge multi-agent research and making advanced agent collaboration accessible to everyone. 

Our mission is to bridge the gap between academic research and practical implementation by providing production-ready, open-source implementations of the most impactful multi-agent research papers.

### Why Multi-Agent Research Matters

Multi-agent systems represent the next evolution in artificial intelligence, moving beyond single-agent limitations to harness the power of collective intelligence. These systems can:

- **Overcome Individual Agent Constraints**: Address memory limitations, hallucinations, and single-task focus through collaborative problem-solving
- **Achieve Superior Performance**: Combine specialized expertise across multiple agents to tackle complex, multifaceted challenges
- **Enable Scalable Solutions**: Distribute computational load and scale efficiently across multiple agents
- **Foster Innovation**: Create novel approaches through agent interaction and knowledge sharing

### Our Research Implementation Philosophy

We believe that the best way to advance the field is through practical implementation and real-world validation. Our approach includes:

- **Faithful Reproduction**: Implementing research papers with high fidelity to original methodologies

- **Production Enhancement**: Adding enterprise-grade features like error handling, monitoring, and scalability

- **Open Source Commitment**: Making all implementations freely available to the research community

- **Continuous Improvement**: Iterating on implementations based on community feedback and new research

### What You'll Find Here

This documentation showcases our comprehensive collection of multi-agent research implementations, including:


- **Academic Paper Implementations**: Direct implementations of published research papers

- **Enhanced Frameworks**: Production-ready versions with additional features and optimizations

- **Research Compilations**: Curated lists of influential multi-agent papers and resources

- **Practical Examples**: Ready-to-use code examples and tutorials

Whether you're a researcher looking to validate findings, a developer building production systems, or a student learning about multi-agent AI, you'll find valuable resources here to advance your work.

## Implemented Research Papers

| Paper Name | Description | Original Paper | Implementation | Status | Key Features |
|------------|-------------|----------------|----------------|--------|--------------|
| **MALT (Multi-Agent Learning Task)** | A sophisticated orchestration framework that coordinates multiple specialized AI agents to tackle complex tasks through structured conversations. | [arXiv:2412.01928](https://arxiv.org/pdf/2412.01928) | [`swarms.structs.malt`](https://docs.swarms.world/en/latest/swarms/structs/malt/) | ✅ Complete | Creator-Verifier-Refiner architecture, structured conversations, reliability guarantees |
| **[MAI-DxO (MAI Diagnostic Orchestrator)](https://arxiv.org/abs/2506.22405)** | An open-source implementation of Microsoft Research's "[Sequential Diagnosis with Language Models](https://arxiv.org/abs/2506.22405)" paper, simulating a virtual panel of physician-agents for iterative medical diagnosis. | Microsoft Research Paper | [GitHub Repository](https://github.com/The-Swarm-Corporation/Open-MAI-Dx-Orchestrator) | ✅ Complete | Cost-effective medical diagnosis, physician-agent panel, iterative refinement |
| **[AI-CoScientist](https://storage.googleapis.com/coscientist_paper/ai_coscientist.pdf)** | A multi-agent AI framework for collaborative scientific research, implementing the "Towards an AI Co-Scientist" methodology with tournament-based hypothesis evolution. | "Towards an AI Co-Scientist" Paper | [GitHub Repository](https://github.com/The-Swarm-Corporation/AI-CoScientist) | ✅ Complete | Tournament-based selection, peer review systems, hypothesis evolution, Elo rating system |
| **[Mixture of Agents (MoA)](https://arxiv.org/abs/2406.04692)** | A sophisticated multi-agent architecture that implements parallel processing with iterative refinement, combining diverse expert agents for comprehensive analysis. | Multi-agent collaboration concepts | [`swarms.structs.moa`](https://docs.swarms.world/en/latest/swarms/structs/moa/) | ✅ Complete | Parallel processing, expert agent combination, iterative refinement, state-of-the-art performance |
| **Deep Research Swarm** | A production-grade research system that conducts comprehensive analysis across multiple domains using parallel processing and advanced AI agents. | Research methodology | [`swarms.structs.deep_research_swarm`](https://docs.swarms.world/en/latest/swarms/structs/deep_research_swarm/) | ✅ Complete | Parallel search processing, multi-agent coordination, information synthesis, concurrent execution |
| **Agent-as-a-Judge** | An evaluation framework that uses agents to evaluate other agents, implementing the "Agent-as-a-Judge: Evaluate Agents with Agents" methodology. | [arXiv:2410.10934](https://arxiv.org/abs/2410.10934) | [`swarms.agents.agent_judge`](https://docs.swarms.world/en/latest/swarms/agents/agent_judge/) | ✅ Complete | Agent evaluation, quality assessment, automated judging, performance metrics |
| **Advanced Research System** | An enhanced implementation of the orchestrator-worker pattern from Anthropic's paper "How we built our multi-agent research system", featuring parallel execution, LLM-as-judge evaluation, and professional report generation. | [Anthropic Paper](https://www.anthropic.com/engineering/built-multi-agent-research-system) | [GitHub Repository](https://github.com/The-Swarm-Corporation/AdvancedResearch) | ✅ Complete | Orchestrator-worker architecture, parallel execution, Exa API integration, export capabilities |

### Multi-Agent Papers Compilation

We maintain a comprehensive list of multi-agent research papers at: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers)



## Contributing

We welcome contributions to implement additional research papers! If you'd like to contribute:

1. **Identify a paper**: Choose a relevant multi-agent research paper
2. **Propose implementation**: Submit an issue with your proposal
3. **Implement**: Create the implementation following our guidelines
4. **Document**: Add comprehensive documentation and examples
5. **Test**: Ensure robust testing and validation

## Citation

If you use any of these implementations in your research, please cite the original papers and the Swarms framework:

```bibtex
@misc{SWARMS_2022,
  author  = {Gomez, Kye and Pliny and More, Harshal and Swarms Community},
  title   = {{Swarms: Production-Grade Multi-Agent Infrastructure Platform}},
  year    = {2022},
  howpublished = {\url{https://github.com/kyegomez/swarms}},
  note    = {Documentation available at \url{https://docs.swarms.world}},
  version = {latest}
}
```

## Community

Join our community to stay updated on the latest multi-agent research implementations:

- **Discord**: [Join our community](https://discord.gg/EamjgSaEQf)

- **Documentation**: [docs.swarms.world](https://docs.swarms.world)

- **GitHub**: [kyegomez/swarms](https://github.com/kyegomez/swarms)

- **Research Papers**: [awesome-multi-agent-papers](https://github.com/kyegomez/awesome-multi-agent-papers)




--------------------------------------------------

# File: examples/smart_database.md

# Smart Database Powered by Hierarchical Multi-Agent Workflow

This module implements a fully autonomous database management system using a hierarchical multi-agent architecture. The system includes specialized agents for different database operations coordinated by a Database Director agent.

## Features

| Feature                              | Description                                                                                   |
|---------------------------------------|-----------------------------------------------------------------------------------------------|
| Autonomous Database Management        | Complete database lifecycle management, including setup and ongoing management of databases.   |
| Intelligent Task Distribution         | Automatic assignment of tasks to appropriate specialist agents.                                |
| Table Creation with Schema Validation | Ensures tables are created with correct structure, schema enforcement, and data integrity.     |
| Data Insertion and Updates            | Handles adding new data and updating existing records efficiently, supporting JSON input.      |
| Complex Query Execution               | Executes advanced and optimized queries for data retrieval and analysis.                       |
| Schema Modifications                  | Supports altering table structures and database schemas as needed.                             |
| Hierarchical Agent Coordination       | Utilizes a multi-agent system for orchestrated, intelligent task execution.                    |
| Security                              | Built-in SQL injection prevention and query validation for data protection.                    |
| Performance Optimization              | Query optimization and efficient data operations for high performance.                         |
| Comprehensive Error Handling          | Robust error management and reporting throughout all operations.                               |
| Multi-format Data Support             | Flexible query parameters and support for JSON-based data insertion.                           |

## Architecture

### Multi-Agent Architecture

```
Database Director (Coordinator)
├── Database Creator (Creates databases)
├── Table Manager (Manages table schemas)
├── Data Operations (Handles data insertion/updates)
└── Query Specialist (Executes queries and retrieval)
```

### Agent Specializations

| Agent             | Description                                                                                   |
|------------------------|-----------------------------------------------------------------------------------------------|
| **Database Director**  | Orchestrates all database operations and coordinates specialist agents                        |
| **Database Creator**   | Specializes in creating and initializing databases                                            |
| **Table Manager**      | Expert in table creation, schema design, and structure management                             |
| **Data Operations**    | Handles data insertion, updates, and manipulation                                             |
| **Query Specialist**   | Manages database queries, data retrieval, and optimization                                    |


## Agent Tools

| Function | Description |
|----------|-------------|
| **`create_database(database_name, database_path)`** | Creates new SQLite databases |
| **`create_table(database_path, table_name, schema)`** | Creates tables with specified schemas |
| **`insert_data(database_path, table_name, data)`** | Inserts data into tables |
| **`query_database(database_path, query, params)`** | Executes SELECT queries |
| **`update_table_data(database_path, table_name, update_data, where_clause)`** | Updates existing data |
| **`get_database_schema(database_path)`** | Retrieves comprehensive schema information |

## Install

```bash
pip install -U swarms sqlite3 loguru
```

## ENV

```
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY=""
OPENAI_API_KEY=""
```

## Code 

- Make a file called `smart_database_swarm.py`

```python
import sqlite3
import json
from pathlib import Path
from loguru import logger

from swarms import Agent, HierarchicalSwarm


# =============================================================================
# DATABASE TOOLS - Core Functions for Database Operations
# =============================================================================


def create_database(
    database_name: str, database_path: str = "./databases"
) -> str:
    """
    Create a new SQLite database file.

    Args:
        database_name (str): Name of the database to create (without .db extension)
        database_path (str, optional): Directory path where database will be created.
                                     Defaults to "./databases".

    Returns:
        str: JSON string containing operation result and database information

    Raises:
        OSError: If unable to create database directory or file
        sqlite3.Error: If database connection fails

    Example:
        >>> result = create_database("company_db", "/data/databases")
        >>> print(result)
        {"status": "success", "database": "company_db.db", "path": "/data/databases/company_db.db"}
    """
    try:
        # Validate input parameters
        if not database_name or not database_name.strip():
            raise ValueError("Database name cannot be empty")

        # Clean database name
        db_name = database_name.strip().replace(" ", "_")
        if not db_name.endswith(".db"):
            db_name += ".db"

        # Create database directory if it doesn't exist
        db_path = Path(database_path)
        db_path.mkdir(parents=True, exist_ok=True)

        # Full database file path
        full_db_path = db_path / db_name

        # Create database connection (creates file if doesn't exist)
        conn = sqlite3.connect(str(full_db_path))

        # Create a metadata table to track database info
        conn.execute(
            """
            CREATE TABLE IF NOT EXISTS _database_metadata (
                key TEXT PRIMARY KEY,
                value TEXT,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
            )
        """
        )

        # Insert database metadata
        conn.execute(
            "INSERT OR REPLACE INTO _database_metadata (key, value) VALUES (?, ?)",
            ("database_name", database_name),
        )

        conn.commit()
        conn.close()

        result = {
            "status": "success",
            "message": f"Database '{database_name}' created successfully",
            "database": db_name,
            "path": str(full_db_path),
            "size_bytes": full_db_path.stat().st_size,
        }

        logger.info(f"Database created: {db_name}")
        return json.dumps(result, indent=2)

    except ValueError as e:
        return json.dumps({"status": "error", "error": str(e)})
    except sqlite3.Error as e:
        return json.dumps(
            {"status": "error", "error": f"Database error: {str(e)}"}
        )
    except Exception as e:
        return json.dumps(
            {
                "status": "error",
                "error": f"Unexpected error: {str(e)}",
            }
        )


def create_table(
    database_path: str, table_name: str, schema: str
) -> str:
    """
    Create a new table in the specified database with the given schema.

    Args:
        database_path (str): Full path to the database file
        table_name (str): Name of the table to create
        schema (str): SQL schema definition for the table columns
                     Format: "column1 TYPE constraints, column2 TYPE constraints, ..."
                     Example: "id INTEGER PRIMARY KEY, name TEXT NOT NULL, age INTEGER"

    Returns:
        str: JSON string containing operation result and table information

    Raises:
        sqlite3.Error: If table creation fails
        FileNotFoundError: If database file doesn't exist

    Example:
        >>> schema = "id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT UNIQUE"
        >>> result = create_table("/data/company.db", "employees", schema)
        >>> print(result)
        {"status": "success", "table": "employees", "columns": 3}
    """
    try:
        # Validate inputs
        if not all([database_path, table_name, schema]):
            raise ValueError(
                "Database path, table name, and schema are required"
            )

        # Check if database exists
        if not Path(database_path).exists():
            raise FileNotFoundError(
                f"Database file not found: {database_path}"
            )

        # Clean table name
        clean_table_name = table_name.strip().replace(" ", "_")

        # Connect to database
        conn = sqlite3.connect(database_path)
        cursor = conn.cursor()

        # Check if table already exists
        cursor.execute(
            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
            (clean_table_name,),
        )

        if cursor.fetchone():
            conn.close()
            return json.dumps(
                {
                    "status": "warning",
                    "message": f"Table '{clean_table_name}' already exists",
                    "table": clean_table_name,
                }
            )

        # Create table with provided schema
        create_sql = f"CREATE TABLE {clean_table_name} ({schema})"
        cursor.execute(create_sql)

        # Get table info
        cursor.execute(f"PRAGMA table_info({clean_table_name})")
        columns = cursor.fetchall()

        # Update metadata
        cursor.execute(
            """
            INSERT OR REPLACE INTO _database_metadata (key, value) 
            VALUES (?, ?)
        """,
            (f"table_{clean_table_name}_created", "true"),
        )

        conn.commit()
        conn.close()

        result = {
            "status": "success",
            "message": f"Table '{clean_table_name}' created successfully",
            "table": clean_table_name,
            "columns": len(columns),
            "schema": [
                {
                    "name": col[1],
                    "type": col[2],
                    "nullable": not col[3],
                }
                for col in columns
            ],
        }

        return json.dumps(result, indent=2)

    except ValueError as e:
        return json.dumps({"status": "error", "error": str(e)})
    except FileNotFoundError as e:
        return json.dumps({"status": "error", "error": str(e)})
    except sqlite3.Error as e:
        return json.dumps(
            {"status": "error", "error": f"SQL error: {str(e)}"}
        )
    except Exception as e:
        return json.dumps(
            {
                "status": "error",
                "error": f"Unexpected error: {str(e)}",
            }
        )


def insert_data(
    database_path: str, table_name: str, data: str
) -> str:
    """
    Insert data into a specified table.

    Args:
        database_path (str): Full path to the database file
        table_name (str): Name of the target table
        data (str): JSON string containing data to insert
                   Format: {"columns": ["col1", "col2"], "values": [[val1, val2], ...]}
                   Or: [{"col1": val1, "col2": val2}, ...]

    Returns:
        str: JSON string containing operation result and insertion statistics

    Example:
        >>> data = '{"columns": ["name", "age"], "values": [["John", 30], ["Jane", 25]]}'
        >>> result = insert_data("/data/company.db", "employees", data)
        >>> print(result)
        {"status": "success", "table": "employees", "rows_inserted": 2}
    """
    try:
        # Validate inputs
        if not all([database_path, table_name, data]):
            raise ValueError(
                "Database path, table name, and data are required"
            )

        # Check if database exists
        if not Path(database_path).exists():
            raise FileNotFoundError(
                f"Database file not found: {database_path}"
            )

        # Parse data
        try:
            parsed_data = json.loads(data)
        except json.JSONDecodeError:
            raise ValueError("Invalid JSON format for data")

        conn = sqlite3.connect(database_path)
        cursor = conn.cursor()

        # Check if table exists
        cursor.execute(
            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
            (table_name,),
        )

        if not cursor.fetchone():
            conn.close()
            raise ValueError(f"Table '{table_name}' does not exist")

        rows_inserted = 0

        # Handle different data formats
        if isinstance(parsed_data, list) and all(
            isinstance(item, dict) for item in parsed_data
        ):
            # Format: [{"col1": val1, "col2": val2}, ...]
            for row in parsed_data:
                columns = list(row.keys())
                values = list(row.values())
                placeholders = ", ".join(["?" for _ in values])
                columns_str = ", ".join(columns)

                insert_sql = f"INSERT INTO {table_name} ({columns_str}) VALUES ({placeholders})"
                cursor.execute(insert_sql, values)
                rows_inserted += 1

        elif (
            isinstance(parsed_data, dict)
            and "columns" in parsed_data
            and "values" in parsed_data
        ):
            # Format: {"columns": ["col1", "col2"], "values": [[val1, val2], ...]}
            columns = parsed_data["columns"]
            values_list = parsed_data["values"]

            placeholders = ", ".join(["?" for _ in columns])
            columns_str = ", ".join(columns)

            insert_sql = f"INSERT INTO {table_name} ({columns_str}) VALUES ({placeholders})"

            for values in values_list:
                cursor.execute(insert_sql, values)
                rows_inserted += 1
        else:
            raise ValueError(
                "Invalid data format. Expected list of dicts or dict with columns/values"
            )

        conn.commit()
        conn.close()

        result = {
            "status": "success",
            "message": f"Data inserted successfully into '{table_name}'",
            "table": table_name,
            "rows_inserted": rows_inserted,
        }

        return json.dumps(result, indent=2)

    except (ValueError, FileNotFoundError) as e:
        return json.dumps({"status": "error", "error": str(e)})
    except sqlite3.Error as e:
        return json.dumps(
            {"status": "error", "error": f"SQL error: {str(e)}"}
        )
    except Exception as e:
        return json.dumps(
            {
                "status": "error",
                "error": f"Unexpected error: {str(e)}",
            }
        )


def query_database(
    database_path: str, query: str, params: str = "[]"
) -> str:
    """
    Execute a SELECT query on the database and return results.

    Args:
        database_path (str): Full path to the database file
        query (str): SQL SELECT query to execute
        params (str, optional): JSON string of query parameters for prepared statements.
                               Defaults to "[]".

    Returns:
        str: JSON string containing query results and metadata

    Example:
        >>> query = "SELECT * FROM employees WHERE age > ?"
        >>> params = "[25]"
        >>> result = query_database("/data/company.db", query, params)
        >>> print(result)
        {"status": "success", "results": [...], "row_count": 5}
    """
    try:
        # Validate inputs
        if not all([database_path, query]):
            raise ValueError("Database path and query are required")

        # Check if database exists
        if not Path(database_path).exists():
            raise FileNotFoundError(
                f"Database file not found: {database_path}"
            )

        # Validate query is SELECT only (security)
        if not query.strip().upper().startswith("SELECT"):
            raise ValueError("Only SELECT queries are allowed")

        # Parse parameters
        try:
            query_params = json.loads(params)
        except json.JSONDecodeError:
            raise ValueError("Invalid JSON format for parameters")

        conn = sqlite3.connect(database_path)
        conn.row_factory = sqlite3.Row  # Enable column access by name
        cursor = conn.cursor()

        # Execute query
        if query_params:
            cursor.execute(query, query_params)
        else:
            cursor.execute(query)

        # Fetch results
        rows = cursor.fetchall()

        # Convert to list of dictionaries
        results = [dict(row) for row in rows]

        # Get column names
        column_names = (
            [description[0] for description in cursor.description]
            if cursor.description
            else []
        )

        conn.close()

        result = {
            "status": "success",
            "message": "Query executed successfully",
            "results": results,
            "row_count": len(results),
            "columns": column_names,
        }

        return json.dumps(result, indent=2)

    except (ValueError, FileNotFoundError) as e:
        return json.dumps({"status": "error", "error": str(e)})
    except sqlite3.Error as e:
        return json.dumps(
            {"status": "error", "error": f"SQL error: {str(e)}"}
        )
    except Exception as e:
        return json.dumps(
            {
                "status": "error",
                "error": f"Unexpected error: {str(e)}",
            }
        )


def update_table_data(
    database_path: str,
    table_name: str,
    update_data: str,
    where_clause: str = "",
) -> str:
    """
    Update existing data in a table.

    Args:
        database_path (str): Full path to the database file
        table_name (str): Name of the table to update
        update_data (str): JSON string with column-value pairs to update
                          Format: {"column1": "new_value1", "column2": "new_value2"}
        where_clause (str, optional): WHERE condition for the update (without WHERE keyword).
                                    Example: "id = 1 AND status = 'active'"

    Returns:
        str: JSON string containing operation result and update statistics

    Example:
        >>> update_data = '{"salary": 50000, "department": "Engineering"}'
        >>> where_clause = "id = 1"
        >>> result = update_table_data("/data/company.db", "employees", update_data, where_clause)
        >>> print(result)
        {"status": "success", "table": "employees", "rows_updated": 1}
    """
    try:
        # Validate inputs
        if not all([database_path, table_name, update_data]):
            raise ValueError(
                "Database path, table name, and update data are required"
            )

        # Check if database exists
        if not Path(database_path).exists():
            raise FileNotFoundError(
                f"Database file not found: {database_path}"
            )

        # Parse update data
        try:
            parsed_updates = json.loads(update_data)
        except json.JSONDecodeError:
            raise ValueError("Invalid JSON format for update data")

        if not isinstance(parsed_updates, dict):
            raise ValueError("Update data must be a dictionary")

        conn = sqlite3.connect(database_path)
        cursor = conn.cursor()

        # Check if table exists
        cursor.execute(
            "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
            (table_name,),
        )

        if not cursor.fetchone():
            conn.close()
            raise ValueError(f"Table '{table_name}' does not exist")

        # Build UPDATE query
        set_clauses = []
        values = []

        for column, value in parsed_updates.items():
            set_clauses.append(f"{column} = ?")
            values.append(value)

        set_clause = ", ".join(set_clauses)

        if where_clause:
            update_sql = f"UPDATE {table_name} SET {set_clause} WHERE {where_clause}"
        else:
            update_sql = f"UPDATE {table_name} SET {set_clause}"

        # Execute update
        cursor.execute(update_sql, values)
        rows_updated = cursor.rowcount

        conn.commit()
        conn.close()

        result = {
            "status": "success",
            "message": f"Table '{table_name}' updated successfully",
            "table": table_name,
            "rows_updated": rows_updated,
            "updated_columns": list(parsed_updates.keys()),
        }

        return json.dumps(result, indent=2)

    except (ValueError, FileNotFoundError) as e:
        return json.dumps({"status": "error", "error": str(e)})
    except sqlite3.Error as e:
        return json.dumps(
            {"status": "error", "error": f"SQL error: {str(e)}"}
        )
    except Exception as e:
        return json.dumps(
            {
                "status": "error",
                "error": f"Unexpected error: {str(e)}",
            }
        )


def get_database_schema(database_path: str) -> str:
    """
    Get comprehensive schema information for all tables in the database.

    Args:
        database_path (str): Full path to the database file

    Returns:
        str: JSON string containing complete database schema information

    Example:
        >>> result = get_database_schema("/data/company.db")
        >>> print(result)
        {"status": "success", "database": "company.db", "tables": {...}}
    """
    try:
        if not database_path:
            raise ValueError("Database path is required")

        if not Path(database_path).exists():
            raise FileNotFoundError(
                f"Database file not found: {database_path}"
            )

        conn = sqlite3.connect(database_path)
        cursor = conn.cursor()

        # Get all tables
        cursor.execute(
            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE '_%'"
        )
        tables = cursor.fetchall()

        schema_info = {
            "database": Path(database_path).name,
            "table_count": len(tables),
            "tables": {},
        }

        for table in tables:
            table_name = table[0]

            # Get table schema
            cursor.execute(f"PRAGMA table_info({table_name})")
            columns = cursor.fetchall()

            # Get row count
            cursor.execute(f"SELECT COUNT(*) FROM {table_name}")
            row_count = cursor.fetchone()[0]

            schema_info["tables"][table_name] = {
                "columns": [
                    {
                        "name": col[1],
                        "type": col[2],
                        "nullable": not col[3],
                        "default": col[4],
                        "primary_key": bool(col[5]),
                    }
                    for col in columns
                ],
                "column_count": len(columns),
                "row_count": row_count,
            }

        conn.close()

        result = {
            "status": "success",
            "message": "Database schema retrieved successfully",
            "schema": schema_info,
        }

        return json.dumps(result, indent=2)

    except (ValueError, FileNotFoundError) as e:
        return json.dumps({"status": "error", "error": str(e)})
    except sqlite3.Error as e:
        return json.dumps(
            {"status": "error", "error": f"SQL error: {str(e)}"}
        )
    except Exception as e:
        return json.dumps(
            {
                "status": "error",
                "error": f"Unexpected error: {str(e)}",
            }
        )


# =============================================================================
# DATABASE CREATION SPECIALIST AGENT
# =============================================================================
database_creator_agent = Agent(
    agent_name="Database-Creator",
    agent_description="Specialist agent responsible for creating and initializing databases with proper structure and metadata",
    system_prompt="""You are the Database Creator, a specialist agent responsible for database creation and initialization. Your expertise includes:

    DATABASE CREATION & SETUP:
    - Creating new SQLite databases with proper structure
    - Setting up database metadata and tracking systems
    - Initializing database directories and file organization
    - Ensuring database accessibility and permissions
    - Creating database backup and recovery procedures

    DATABASE ARCHITECTURE:
    - Designing optimal database structures for different use cases
    - Planning database organization and naming conventions
    - Setting up database configuration and optimization settings
    - Implementing database security and access controls
    - Creating database documentation and specifications

    Your responsibilities:
    - Create new databases when requested
    - Set up proper database structure and metadata
    - Ensure database is properly initialized and accessible
    - Provide database creation status and information
    - Handle database creation errors and provide solutions

    You work with precise technical specifications and always ensure databases are created correctly and efficiently.""",
    model_name="claude-sonnet-4-20250514",
    max_loops=1,
    temperature=0.3,
    dynamic_temperature_enabled=True,
    tools=[create_database, get_database_schema],
)

# =============================================================================
# TABLE MANAGEMENT SPECIALIST AGENT
# =============================================================================
table_manager_agent = Agent(
    agent_name="Table-Manager",
    agent_description="Specialist agent for table creation, schema design, and table structure management",
    system_prompt="""You are the Table Manager, a specialist agent responsible for table creation, schema design, and table structure management. Your expertise includes:

    TABLE CREATION & DESIGN:
    - Creating tables with optimal schema design
    - Defining appropriate data types and constraints
    - Setting up primary keys, foreign keys, and indexes
    - Designing normalized table structures
    - Creating tables that support efficient queries and operations

    SCHEMA MANAGEMENT:
    - Analyzing schema requirements and designing optimal structures
    - Validating schema definitions and data types
    - Ensuring schema consistency and integrity
    - Managing schema modifications and updates
    - Optimizing table structures for performance

    DATA INTEGRITY:
    - Implementing proper constraints and validation rules
    - Setting up referential integrity between tables
    - Ensuring data consistency across table operations
    - Managing table relationships and dependencies
    - Creating tables that support data quality requirements

    Your responsibilities:
    - Create tables with proper schema definitions
    - Validate table structures and constraints
    - Ensure optimal table design for performance
    - Handle table creation errors and provide solutions
    - Provide detailed table information and metadata

    You work with precision and always ensure tables are created with optimal structure and performance characteristics.""",
    model_name="claude-sonnet-4-20250514",
    max_loops=1,
    temperature=0.3,
    dynamic_temperature_enabled=True,
    tools=[create_table, get_database_schema],
)

# =============================================================================
# DATA OPERATIONS SPECIALIST AGENT
# =============================================================================
data_operations_agent = Agent(
    agent_name="Data-Operations",
    agent_description="Specialist agent for data insertion, updates, and data manipulation operations",
    system_prompt="""You are the Data Operations specialist, responsible for all data manipulation operations including insertion, updates, and data management. Your expertise includes:

    DATA INSERTION:
    - Inserting data with proper validation and formatting
    - Handling bulk data insertions efficiently
    - Managing data type conversions and formatting
    - Ensuring data integrity during insertion operations
    - Validating data before insertion to prevent errors

    DATA UPDATES:
    - Updating existing data with precision and safety
    - Creating targeted update operations with proper WHERE clauses
    - Managing bulk updates and data modifications
    - Ensuring data consistency during update operations
    - Validating update operations to prevent data corruption

    DATA VALIDATION:
    - Validating data formats and types before operations
    - Ensuring data meets schema requirements and constraints
    - Checking for data consistency and integrity
    - Managing data transformation and cleaning operations
    - Providing detailed feedback on data operation results

    ERROR HANDLING:
    - Managing data operation errors gracefully
    - Providing clear error messages and solutions
    - Ensuring data operations are atomic and safe
    - Rolling back operations when necessary
    - Maintaining data integrity throughout all operations

    Your responsibilities:
    - Execute data insertion operations safely and efficiently
    - Perform data updates with proper validation
    - Ensure data integrity throughout all operations
    - Handle data operation errors and provide solutions
    - Provide detailed operation results and statistics

    You work with extreme precision and always prioritize data integrity and safety in all operations.""",
    model_name="claude-sonnet-4-20250514",
    max_loops=1,
    temperature=0.3,
    dynamic_temperature_enabled=True,
    tools=[insert_data, update_table_data],
)

# =============================================================================
# QUERY SPECIALIST AGENT
# =============================================================================
query_specialist_agent = Agent(
    agent_name="Query-Specialist",
    agent_description="Expert agent for database querying, data retrieval, and query optimization",
    system_prompt="""You are the Query Specialist, an expert agent responsible for database querying, data retrieval, and query optimization. Your expertise includes:

    QUERY EXECUTION:
    - Executing complex SELECT queries efficiently
    - Handling parameterized queries for security
    - Managing query results and data formatting
    - Ensuring query performance and optimization
    - Providing comprehensive query results with metadata

    QUERY OPTIMIZATION:
    - Analyzing query performance and optimization opportunities
    - Creating efficient queries that minimize resource usage
    - Understanding database indexes and query planning
    - Optimizing JOIN operations and complex queries
    - Managing query timeouts and performance monitoring

    DATA RETRIEVAL:
    - Retrieving data with proper formatting and structure
    - Handling large result sets efficiently
    - Managing data aggregation and summarization
    - Creating reports and data analysis queries
    - Ensuring data accuracy and completeness in results

    SECURITY & VALIDATION:
    - Ensuring queries are safe and secure
    - Validating query syntax and parameters
    - Preventing SQL injection and security vulnerabilities
    - Managing query permissions and access controls
    - Ensuring queries follow security best practices

    Your responsibilities:
    - Execute database queries safely and efficiently
    - Optimize query performance for best results
    - Provide comprehensive query results and analysis
    - Handle query errors and provide solutions
    - Ensure query security and data protection

    You work with expertise in SQL optimization and always ensure queries are secure, efficient, and provide accurate results.""",
    model_name="claude-sonnet-4-20250514",
    max_loops=1,
    temperature=0.3,
    dynamic_temperature_enabled=True,
    tools=[query_database, get_database_schema],
)

# =============================================================================
# DATABASE DIRECTOR AGENT (COORDINATOR)
# =============================================================================
database_director_agent = Agent(
    agent_name="Database-Director",
    agent_description="Senior database director who orchestrates comprehensive database operations across all specialized teams",
    system_prompt="""You are the Database Director, the senior executive responsible for orchestrating comprehensive database operations and coordinating a team of specialized database experts. Your role is to:

    STRATEGIC COORDINATION:
    - Analyze complex database tasks and break them down into specialized operations
    - Assign tasks to the most appropriate specialist based on their unique expertise
    - Ensure comprehensive coverage of all database operations (creation, schema, data, queries)
    - Coordinate between specialists to avoid conflicts and ensure data integrity
    - Synthesize results from multiple specialists into coherent database solutions
    - Ensure all database operations align with user requirements and best practices

    TEAM LEADERSHIP:
    - Lead the Database Creator in setting up new databases and infrastructure
    - Guide the Table Manager in creating optimal table structures and schemas
    - Direct the Data Operations specialist in data insertion and update operations
    - Oversee the Query Specialist in data retrieval and analysis operations
    - Ensure all team members work collaboratively toward unified database goals
    - Provide strategic direction and feedback to optimize team performance

    DATABASE ARCHITECTURE:
    - Design comprehensive database solutions that meet user requirements
    - Ensure database operations follow best practices and standards
    - Plan database workflows that optimize performance and reliability
    - Balance immediate operational needs with long-term database health
    - Ensure database operations are secure, efficient, and maintainable
    - Optimize database operations for scalability and performance

    OPERATION ORCHESTRATION:
    - Monitor database operations across all specialists and activities
    - Analyze results to identify optimization opportunities and improvements
    - Ensure database operations deliver reliable and accurate results
    - Provide strategic recommendations based on operation outcomes
    - Coordinate complex multi-step database operations across specialists
    - Ensure continuous improvement and optimization in database management

    Your expertise includes:
    - Database architecture and design strategy
    - Team leadership and cross-functional coordination
    - Database performance analysis and optimization
    - Strategic planning and requirement analysis
    - Operation workflow management and optimization
    - Database security and best practices implementation

    You deliver comprehensive database solutions that leverage the full expertise of your specialized team, ensuring all database operations work together to provide reliable, efficient, and secure data management.""",
    model_name="claude-sonnet-4-20250514",
    max_loops=1,
    temperature=0.5,
    dynamic_temperature_enabled=True,
)

# =============================================================================
# HIERARCHICAL DATABASE SWARM
# =============================================================================
# Create list of specialized database agents
database_specialists = [
    database_creator_agent,
    table_manager_agent,
    data_operations_agent,
    query_specialist_agent,
]

# Initialize the hierarchical database swarm
smart_database_swarm = HierarchicalSwarm(
    name="Smart-Database-Swarm",
    description="A comprehensive database management system with specialized agents for creation, schema management, data operations, and querying, coordinated by a database director",
    director_model_name="gpt-4.1",
    agents=database_specialists,
    max_loops=1,
    verbose=True,
)

# =============================================================================
# EXAMPLE USAGE AND DEMONSTRATIONS
# =============================================================================
if __name__ == "__main__":
    # Configure logging
    logger.info("Starting Smart Database Swarm demonstration")

    # Example 1: Create a complete e-commerce database system
    print("=" * 80)
    print("SMART DATABASE SWARM - E-COMMERCE SYSTEM EXAMPLE")
    print("=" * 80)

    task1 = """Create a comprehensive e-commerce database system with the following requirements:
    
    1. Create a database called 'ecommerce_db' 
    2. Create tables for:
       - customers (id, name, email, phone, address, created_at)
       - products (id, name, description, price, category, stock_quantity, created_at)
       - orders (id, customer_id, order_date, total_amount, status)
       - order_items (id, order_id, product_id, quantity, unit_price)
    
    3. Insert sample data:
       - Add 3 customers
       - Add 5 products in different categories
       - Create 2 orders with multiple items
    
    4. Query the database to:
       - Show all customers with their order history
       - Display products by category with stock levels
       - Calculate total sales by product
    
    Ensure all operations are executed properly and provide comprehensive results."""

    result1 = smart_database_swarm.run(task=task1)
    print("\nE-COMMERCE DATABASE RESULT:")
    print(result1)

    # print("\n" + "=" * 80)
    # print("SMART DATABASE SWARM - EMPLOYEE MANAGEMENT SYSTEM")
    # print("=" * 80)

    # # Example 2: Employee management system
    # task2 = """Create an employee management database system:

    # 1. Create database 'company_hr'
    # 2. Create tables for:
    #    - departments (id, name, budget, manager_id)
    #    - employees (id, name, email, department_id, position, salary, hire_date)
    #    - projects (id, name, description, start_date, end_date, budget)
    #    - employee_projects (employee_id, project_id, role, hours_allocated)

    # 3. Add sample data for departments, employees, and projects
    # 4. Query for:
    #    - Employee count by department
    #    - Average salary by position
    #    - Projects with their assigned employees
    #    - Department budgets vs project allocations

    # Coordinate the team to build this system efficiently."""

    # result2 = smart_database_swarm.run(task=task2)
    # print("\nEMPLOYEE MANAGEMENT RESULT:")
    # print(result2)

    # print("\n" + "=" * 80)
    # print("SMART DATABASE SWARM - DATABASE ANALYSIS")
    # print("=" * 80)

    # # Example 3: Database analysis and optimization
    # task3 = """Analyze and optimize the existing databases:

    # 1. Get schema information for all created databases
    # 2. Analyze table structures and relationships
    # 3. Suggest optimizations for:
    #    - Index creation for better query performance
    #    - Data normalization improvements
    #    - Constraint additions for data integrity

    # 4. Update data in existing tables:
    #    - Increase product prices by 10% for electronics category
    #    - Update employee salaries based on performance criteria
    #    - Modify order statuses for completed orders

    # 5. Create comprehensive reports showing:
    #    - Database statistics and health metrics
    #    - Data distribution and patterns
    #    - Performance optimization recommendations

    # Coordinate all specialists to provide a complete database analysis."""

    # result3 = smart_database_swarm.run(task=task3)
    # print("\nDATABASE ANALYSIS RESULT:")
    # print(result3)

    # logger.info("Smart Database Swarm demonstration completed successfully")
```


- Run the file with `smart_database_swarm.py`

--------------------------------------------------

# File: examples/templates.md

# Templates & Applications Documentation

The Swarms framework is a powerful multi-agent orchestration platform that enables developers to build sophisticated AI agent systems. This documentation showcases the extensive ecosystem of templates, applications, and tools built on the Swarms framework, organized by industry and application type.

🔗 **Main Repository**: [Swarms Framework](https://github.com/kyegomez/swarms)

---

## 🏥 Healthcare & Medical Applications

### Medical Diagnosis & Analysis

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [MRI-Swarm](https://github.com/The-Swarm-Corporation/MRI-Swarm) | Multi-agent system for MRI image analysis and diagnosis | Medical Imaging | Healthcare |
| [DermaSwarm](https://github.com/The-Swarm-Corporation/DermaSwarm) | Dermatology-focused agent swarm for skin condition analysis | Medical Diagnosis | Healthcare |
| [Multi-Modal-XRAY-Diagnosis](https://github.com/The-Swarm-Corporation/Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template) | X-ray diagnosis using multi-modal AI agents | Medical Imaging | Healthcare |
| [Open-MAI-Dx-Orchestrator](https://github.com/The-Swarm-Corporation/Open-MAI-Dx-Orchestrator) | Medical AI diagnosis orchestration platform | Medical Platform | Healthcare |
| [radiology-swarm](https://github.com/The-Swarm-Corporation/radiology-swarm) | Radiology-focused multi-agent system | Medical Imaging | Healthcare |

### Medical Operations & Administration

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [MedicalCoderSwarm](https://github.com/The-Swarm-Corporation/MedicalCoderSwarm) | Medical coding automation using agent swarms | Medical Coding | Healthcare |
| [pharma-swarm](https://github.com/The-Swarm-Corporation/pharma-swarm) | Pharmaceutical research and development agents | Pharmaceutical | Healthcare |
| [MedGuard](https://github.com/The-Swarm-Corporation/MedGuard) | Medical data security and compliance system | Medical Security | Healthcare |
| [MedInsight-Pro](https://github.com/The-Swarm-Corporation/MedInsight-Pro) | Advanced medical insights and analytics platform | Medical Analytics | Healthcare |

---

## 💰 Financial Services & Trading

### Trading & Investment

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [automated-crypto-fund](https://github.com/The-Swarm-Corporation/automated-crypto-fund) | Automated cryptocurrency trading fund management | Crypto Trading | Finance |
| [CryptoAgent](https://github.com/The-Swarm-Corporation/CryptoAgent) | Cryptocurrency analysis and trading agent | Crypto Trading | Finance |
| [AutoHedge](https://github.com/The-Swarm-Corporation/AutoHedge) | Automated hedging strategies implementation | Risk Management | Finance |
| [BackTesterAgent](https://github.com/The-Swarm-Corporation/BackTesterAgent) | Trading strategy backtesting automation | Trading Tools | Finance |
| [ForexTreeSwarm](https://github.com/The-Swarm-Corporation/ForexTreeSwarm) | Forex trading decision tree swarm system | Forex Trading | Finance |
| [HTX-Swarm](https://github.com/The-Swarm-Corporation/HTX-Swarm) | HTX exchange integration and trading automation | Crypto Exchange | Finance |

### Financial Analysis & Management

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [TickrAgent](https://github.com/The-Swarm-Corporation/TickrAgent) | Stock ticker analysis and monitoring agent | Stock Analysis | Finance |
| [Open-Aladdin](https://github.com/The-Swarm-Corporation/Open-Aladdin) | Open-source financial risk management system | Risk Management | Finance |
| [CryptoTaxSwarm](https://github.com/The-Swarm-Corporation/CryptoTaxSwarm) | Cryptocurrency tax calculation and reporting | Tax Management | Finance |

### Insurance & Lending

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [InsuranceSwarm](https://github.com/The-Swarm-Corporation/InsuranceSwarm) | Insurance claim processing and underwriting | Insurance | Finance |
| [MortgageUnderwritingSwarm](https://github.com/The-Swarm-Corporation/MortgageUnderwritingSwarm) | Automated mortgage underwriting system | Lending | Finance |

---

## 🔬 Research & Development

### Scientific Research

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [AI-CoScientist](https://github.com/The-Swarm-Corporation/AI-CoScientist) | AI research collaboration platform | Research Platform | Science |
| [auto-ai-research-team](https://github.com/The-Swarm-Corporation/auto-ai-research-team) | Automated AI research team coordination | Research Automation | Science |
| [Research-Paper-Writer-Swarm](https://github.com/The-Swarm-Corporation/Research-Paper-Writer-Swarm) | Automated research paper writing system | Academic Writing | Science |

### Mathematical & Analytical

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [Generalist-Mathematician-Swarm](https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm) | Mathematical problem-solving agent swarm | Mathematics | Science |

---

## 💼 Business & Marketing

### Marketing & Content

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [Marketing-Swarm-Template](https://github.com/The-Swarm-Corporation/Marketing-Swarm-Template) | Marketing campaign automation template | Marketing Automation | Business |
| [Multi-Agent-Marketing-Course](https://github.com/The-Swarm-Corporation/Multi-Agent-Marketing-Course) | Educational course on multi-agent marketing | Marketing Education | Business |
| [NewsAgent](https://github.com/The-Swarm-Corporation/NewsAgent) | News aggregation and analysis agent | News Analysis | Business |

### Legal Services

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [Legal-Swarm-Template](https://github.com/The-Swarm-Corporation/Legal-Swarm-Template) | Legal document processing and analysis | Legal Technology | Business |

---

## 🛠️ Development Tools & Platforms

### Core Platforms & Operating Systems

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [AgentOS](https://github.com/The-Swarm-Corporation/AgentOS) | Operating system for AI agents | Agent Platform | Development |
| [swarm-ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) | Complete ecosystem for swarm development | Ecosystem Platform | Development |
| [AgentAPIProduction](https://github.com/The-Swarm-Corporation/AgentAPIProduction) | Production-ready agent API system | API Platform | Development |

### Development Tools & Utilities

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [DevSwarm](https://github.com/The-Swarm-Corporation/DevSwarm) | Development-focused agent swarm | Development Tools | Development |
| [FluidAPI](https://github.com/The-Swarm-Corporation/FluidAPI) | Dynamic API generation and management | API Tools | Development |
| [OmniParse](https://github.com/The-Swarm-Corporation/OmniParse) | Universal document parsing system | Document Processing | Development |
| [doc-master](https://github.com/The-Swarm-Corporation/doc-master) | Documentation generation and management | Documentation Tools | Development |

### Templates & Examples

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [Multi-Agent-Template-App](https://github.com/The-Swarm-Corporation/Multi-Agent-Template-App) | Template application for multi-agent systems | Template | Development |
| [swarms-examples](https://github.com/The-Swarm-Corporation/swarms-examples) | Collection of Swarms framework examples | Examples | Development |
| [Phala-Deployment-Template](https://github.com/The-Swarm-Corporation/Phala-Deployment-Template) | Deployment template for Phala Network | Deployment Template | Development |

---

## 📚 Educational Resources

### Courses & Guides

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [Enterprise-Grade-Agents-Course](https://github.com/The-Swarm-Corporation/Enterprise-Grade-Agents-Course) | Comprehensive course on enterprise AI agents | Educational Course | Education |
| [Agents-Beginner-Guide](https://github.com/The-Swarm-Corporation/Agents-Beginner-Guide) | Beginner's guide to AI agents | Educational Guide | Education |

### Testing & Evaluation

| Name | Description | Type | Repository |
|------|-------------|------|------------|
| [swarms-evals](https://github.com/The-Swarm-Corporation/swarms-evals) | Evaluation framework for swarm systems | Testing Framework | Development |

---

## 🚀 Getting Started

### Prerequisites

- Python 3.8+

- Basic understanding of AI agents and multi-agent systems

- Familiarity with the Swarms framework


### Installation

```bash
pip install swarms
```

### Quick Start

1. Choose a template from the categories above

2. Clone the repository

3. Follow the setup instructions in the README

4. Customize the agents for your specific use case

---

## 🤝 Contributing

The Swarms ecosystem is constantly growing. To contribute:

1. Fork the main [Swarms repository](https://github.com/kyegomez/swarms)
2. Create your feature branch
3. Submit a pull request
4. Join the community discussions

---

## 📞 Support & Community

Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights!

| Platform | Description | Link |
|----------|-------------|------|
| 🏠 Main Repository | Swarms Framework | [GitHub](https://github.com/kyegomez/swarms) |
| 🏢 Organization | The Swarm Corporation | [GitHub Org](https://github.com/The-Swarm-Corporation) |
| 🌐 Website | Official project website | [swarms.ai](https://swarms.ai) |
| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) |
| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) |
| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/EamjgSaEQf) |
| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) |
| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) |
| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) |
| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |

---

## 📊 Statistics

- **Total Projects**: 35+

- **Industries Covered**: Healthcare, Finance, Research, Business, Development

- **Project Types**: Templates, Applications, Tools, Educational Resources

- **Active Development**: Continuous updates and new additions


---


--------------------------------------------------

# File: governance/bounty_program.md

# Swarms Bounty Program

The Swarms Bounty Program is an initiative designed to incentivize contributors to help us improve and expand the Swarms framework. With an impressive $150,000 allocated for bounties, contributors have the unique opportunity to earn generous rewards while gaining prestigious recognition in the Swarms community of over 9,000 agent engineers. This program offers more than just financial benefits; it allows contributors to play a pivotal role in advancing the field of multi-agent collaboration and AI automation, while also growing their professional skills and network. By joining the Swarms Bounty Program, you become part of an innovative movement shaping the future of technology.

## Why Contribute?

1. **Generous Rewards**: The bounty pool totals $150,000, ensuring that contributors are fairly compensated for their valuable work on successfully completed tasks. Each task comes with its own reward, reflecting its complexity and impact.

2. **Community Status**: Gain coveted recognition as a valued and active contributor within the thriving Swarms community. This status not only highlights your contributions but also builds your reputation among a network of AI engineers.

3. **Skill Development**: Collaborate on cutting-edge AI projects, hone your expertise in agent engineering, and learn practical skills that can be applied to real-world challenges in the AI domain.

4. **Networking Opportunities**: Work side-by-side with over 9,000 agent engineers in our active and supportive community. This network fosters collaboration, knowledge sharing, and mentorship opportunities that can significantly boost your career.

## How It Works

1. **Explore Issues and Tasks**:
   - Visit the [Swarms GitHub Issues](https://github.com/kyegomez/swarms/issues) to find a comprehensive list of open tasks requiring attention. These issues range from coding challenges to documentation improvements, offering opportunities for contributors with various skill sets.
   - Check the [Swarms Project Board](https://github.com/users/kyegomez/projects/1) for prioritized tasks and ongoing milestones. This board provides a clear view of project priorities and helps contributors align their efforts with the project's immediate goals.

2. **Claim a Bounty**:
   - Identify a task that aligns with your interests and expertise.
   - Comment on the issue to indicate your intent to work on it and describe your approach if necessary.
   - Await approval from the Swarms team before commencing work. Approval ensures clarity and avoids duplication of efforts by other contributors.

3. **Submit Your Work**:
   - Complete the task as per the outlined requirements in the issue description. Pay close attention to details to ensure your submission meets the expectations.
   - Submit your pull request (PR) on GitHub with all the required elements, including documentation, test cases, or any relevant files that demonstrate your work.
   - Engage with reviewers to refine your submission if requested.

4. **Earn Rewards**:
   - Once your PR is reviewed, accepted, and merged into the main project, you will receive the bounty payment associated with the task.
   - Your contributor status in the Swarms community will be updated, showcasing your involvement and accomplishments.

## Contribution Guidelines
To ensure high-quality contributions and streamline the process, please adhere to the following guidelines:
- Familiarize yourself with the [Swarms Contribution Guidelines](https://github.com/kyegomez/swarms/blob/main/CONTRIBUTING.md). These guidelines outline coding standards, best practices, and procedures for contributing effectively.

- Ensure your code is clean, modular, and well-documented. Contributions that adhere to the project's standards are more likely to be accepted.

- Actively communicate with the Swarms team and other contributors. Clear communication helps resolve uncertainties, avoids duplication, and fosters collaboration within the community.

## Get Involved

1. **Join the Community**:
   - Become an active member of the Swarms community by joining our Discord server: [Join Now](https://discord.gg/EamjgSaEQf). The Discord server serves as a hub for discussions, updates, and support.

2. **Stay Updated**:
   - Keep track of the latest updates, announcements, and bounty opportunities by regularly checking the Discord channel and the GitHub repository.

3. **Start Contributing**:
   - Dive into the Swarms GitHub repository: [Swarms GitHub](https://github.com/kyegomez/swarms). Explore the codebase, familiarize yourself with the project structure, and identify areas where you can make an impact.

## Additional Benefits

Beyond monetary rewards, contributors gain intangible benefits that elevate their professional journey:

- **Recognition**: Your contributions will be showcased to a community of over 9,000 engineers, increasing your visibility and credibility in the AI field.

- **Portfolio Building**: Add high-impact contributions to your portfolio, demonstrating your skills and experience to potential employers or collaborators.

- **Knowledge Sharing**: Learn from and collaborate with experts in agent engineering, gaining insights into the latest advancements and best practices in the field.

## Contact Us
For any questions, support, or clarifications, reach out to the Swarms team:

- **Discord**: Engage directly with the team and fellow contributors in our active channels.

- **GitHub**: Open an issue for specific questions or suggestions related to the project. We’re here to guide and assist you at every step of your contribution journey.

---

Join us in building the future of multi-agent collaboration and AI automation. With your contributions, we can create something truly extraordinary and transformative. Together, let’s pave the way for groundbreaking advancements in technology and innovation!



--------------------------------------------------

# File: governance/main.md

# 🔗 Links & Resources

Welcome to the Swarms ecosystem. Click any tile below to explore our products, community, documentation, and social platforms.

---

<style>
.resource-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
  gap: 1rem;
  margin-top: 1.5rem;
}

.resource-card {
  display: block;
  padding: 1.2rem;
  border-radius: 12px;
  background: #000000;
  color: #ff0000;
  text-decoration: none;
  text-align: center;
  font-weight: 600;
  transition: transform 0.2s ease, background 0.3s ease;
  box-shadow: 0 4px 20px rgba(0,0,0,0.2);
}

.resource-card:hover {
  transform: translateY(-4px);
  background: #1a0000;
}
</style>

<div class="resource-grid">

<a class="resource-card" href="https://swarms.world/platform/chat" target="_blank">🗣️ Swarms Chat</a>

<a class="resource-card" href="https://swarms.world" target="_blank">🛍️ Swarms Marketplace</a>

<a class="resource-card" href="https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/" target="_blank">📚 Swarms API Docs</a>

<a class="resource-card" href="https://www.swarms.xyz/programs/startups" target="_blank">🚀 Swarms Startup Program</a>

<a class="resource-card" href="https://github.com/kyegomez/swarms" target="_blank">💻 GitHub: Swarms (Python)</a>

<a class="resource-card" href="https://github.com/The-Swarm-Corporation/swarms-rs" target="_blank">🦀 GitHub: Swarms (Rust)</a>

<a class="resource-card" href="https://discord.gg/EamjgSaEQf" target="_blank">💬 Join Our Discord</a>

<a class="resource-card" href="https://t.me/swarmsgroupchat" target="_blank">📱 Telegram Group</a>

<a class="resource-card" href="https://x.com/swarms_corp" target="_blank">🐦 Twitter / X</a>

<a class="resource-card" href="https://medium.com/@kyeg" target="_blank">✍️ Swarms Blog on Medium</a>

</div>

---

## 💡 Quick Summary

| Category     | Link                                                                 |
|--------------|----------------------------------------------------------------------|
| API Docs     | [docs.swarms.world](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) |
| GitHub       | [kyegomez/swarms](https://github.com/kyegomez/swarms)               |
| GitHub (Rust)| [The-Swarm-Corporation/swarms-rs](https://github.com/The-Swarm-Corporation/swarms-rs) |
| Chat UI      | [swarms.world/platform/chat](https://swarms.world/platform/chat)     |
| Marketplace  | [swarms.world](https://swarms.world)                                 |
| Startup App  | [Apply Here](https://www.swarms.xyz/programs/startups)               |
| Discord      | [Join Now](https://discord.gg/EamjgSaEQf)                            |
| Telegram     | [Group Chat](https://t.me/swarmsgroupchat)                           |
| Twitter/X    | [@swarms_corp](https://x.com/swarms_corp)                            |
| Blog         | [medium.com/@kyeg](https://medium.com/@kyeg)                         |

---

> 🐝 Swarms is building the agentic internet. Join the movement and build the future with us.


--------------------------------------------------

# File: guides/agent_evals.md

### Understanding Agent Evaluation Mechanisms

Agent evaluation mechanisms play a crucial role in ensuring that autonomous agents, particularly in multi-agent systems, perform their tasks effectively and efficiently. This blog delves into the intricacies of agent evaluation, the importance of accuracy tracking, and the methodologies used to measure and visualize agent performance. We'll use Mermaid graphs to provide clear visual representations of these processes.

#### 1. Introduction to Agent Evaluation Mechanisms

Agent evaluation mechanisms refer to the processes and criteria used to assess the performance of agents within a system. These mechanisms are essential for:

- **Ensuring Reliability:** Agents must consistently perform their designated tasks correctly.
- **Improving Performance:** Evaluation helps in identifying areas where agents can improve.
- **Maintaining Accountability:** It provides a way to hold agents accountable for their actions.

### 2. Key Components of Agent Evaluation

To effectively evaluate agents, several components and metrics are considered:

#### a. Performance Metrics

These are quantitative measures used to assess how well an agent is performing. Common performance metrics include:

- **Accuracy:** The percentage of correct actions or decisions made by the agent.
- **Precision and Recall:** Precision measures the number of true positive results divided by the number of all positive results, while recall measures the number of true positive results divided by the number of positives that should have been retrieved.
- **F1 Score:** The harmonic mean of precision and recall.
- **Response Time:** How quickly an agent responds to a given task or query.

#### b. Evaluation Criteria

Evaluation criteria define the standards or benchmarks against which agent performance is measured. These criteria are often task-specific and may include:

- **Task Completion Rate:** The percentage of tasks successfully completed by the agent.
- **Error Rate:** The frequency of errors made by the agent during task execution.
- **Resource Utilization:** How efficiently an agent uses resources such as memory and CPU.

### 3. The Process of Agent Evaluation

The evaluation process involves several steps, which can be visualized using Mermaid graphs:

#### a. Define Evaluation Metrics

The first step is to define the metrics that will be used to evaluate the agent. This involves identifying the key performance indicators (KPIs) relevant to the agent's tasks.

```mermaid
graph TD
    A[Define Evaluation Metrics] --> B[Identify KPIs]
    B --> C[Accuracy]
    B --> D[Precision and Recall]
    B --> E[F1 Score]
    B --> F[Response Time]
```

#### b. Collect Data

Data collection involves gathering information on the agent's performance. This data can come from logs, user feedback, or direct observations.

```mermaid
graph TD
    A[Collect Data] --> B[Logs]
    A --> C[User Feedback]
    A --> D[Direct Observations]
```

#### c. Analyze Performance

Once data is collected, it is analyzed to assess the agent's performance against the defined metrics. This step may involve statistical analysis, machine learning models, or other analytical techniques.

```mermaid
graph TD
    A[Analyze Performance] --> B[Statistical Analysis]
    A --> C[Machine Learning Models]
    A --> D[Other Analytical Techniques]
```

#### d. Generate Reports

After analysis, performance reports are generated. These reports provide insights into how well the agent is performing and identify areas for improvement.

```mermaid
graph TD
    A[Generate Reports] --> B[Performance Insights]
    B --> C[Identify Areas for Improvement]
```

### 4. Tracking Agent Accuracy

Accuracy tracking is a critical aspect of agent evaluation. It involves measuring how often an agent's actions or decisions are correct. The following steps outline the process of tracking agent accuracy:

#### a. Define Correctness Criteria

The first step is to define what constitutes a correct action or decision for the agent.

```mermaid
graph TD
    A[Define Correctness Criteria] --> B[Task-Specific Standards]
    B --> C[Action Accuracy]
    B --> D[Decision Accuracy]
```

#### b. Monitor Agent Actions

Agents' actions are continuously monitored to track their performance. This monitoring can be done in real-time or through periodic evaluations.

```mermaid
graph TD
    A[Monitor Agent Actions] --> B[Real-Time Monitoring]
    A --> C[Periodic Evaluations]
```

#### c. Compare Against Correctness Criteria

Each action or decision made by the agent is compared against the defined correctness criteria to determine its accuracy.

```mermaid
graph TD
    A[Compare Against Correctness Criteria] --> B[Evaluate Each Action]
    B --> C[Correct or Incorrect?]
```

#### d. Calculate Accuracy Metrics

Accuracy metrics are calculated based on the comparison results. These metrics provide a quantitative measure of the agent's accuracy.

```mermaid
graph TD
    A[Calculate Accuracy Metrics] --> B[Accuracy Percentage]
    A --> C[Error Rate]
```

### 5. Measuring Agent Accuracy

Measuring agent accuracy involves several steps and considerations:

#### a. Data Labeling

To measure accuracy, the data used for evaluation must be accurately labeled. This involves annotating the data with the correct actions or decisions.

```mermaid
graph TD
    A[Data Labeling] --> B[Annotate Data with Correct Actions]
    B --> C[Ensure Accuracy of Labels]
```

#### b. Establish Baseline Performance

A baseline performance level is established by evaluating a sample set of data. This baseline serves as a reference point for measuring improvements or declines in accuracy.

```mermaid
graph TD
    A[Establish Baseline Performance] --> B[Evaluate Sample Data]
    B --> C[Set Performance Benchmarks]
```

#### c. Regular Evaluations

Agents are regularly evaluated to measure their accuracy over time. This helps in tracking performance trends and identifying any deviations from the expected behavior.

```mermaid
graph TD
    A[Regular Evaluations] --> B[Track Performance Over Time]
    B --> C[Identify Performance Trends]
    B --> D[Detect Deviations]
```

#### d. Feedback and Improvement

Feedback from evaluations is used to improve the agent's performance. This may involve retraining the agent, adjusting its algorithms, or refining its decision-making processes.

```mermaid
graph TD
    A[Feedback and Improvement] --> B[Use Evaluation Feedback]
    B --> C[Retrain Agent]
    B --> D[Adjust Algorithms]
    B --> E[Refine Decision-Making Processes]
```

### 6. Visualizing Agent Evaluation with Mermaid Graphs

Mermaid graphs provide a clear and concise way to visualize the agent evaluation process. Here are some examples of how Mermaid graphs can be used:

#### a. Overall Evaluation Process

```mermaid
graph TD
    A[Define Evaluation Metrics] --> B[Collect Data]
    B --> C[Analyze Performance]
    C --> D[Generate Reports]
```

#### b. Accuracy Tracking

```mermaid
graph TD
    A[Define Correctness Criteria] --> B[Monitor Agent Actions]
    B --> C[Compare Against Correctness Criteria]
    C --> D[Calculate Accuracy Metrics]
```

#### c. Continuous Improvement Cycle

```mermaid
graph TD
    A[Regular Evaluations] --> B[Track Performance Over Time]
    B --> C[Identify Performance Trends]
    C --> D[Detect Deviations]
    D --> E[Feedback and Improvement]
    E --> A
```

### 7. Case Study: Evaluating a Chatbot Agent

To illustrate the agent evaluation process, let's consider a case study involving a chatbot agent designed to assist customers in an e-commerce platform.

#### a. Define Evaluation Metrics

For the chatbot, key performance metrics might include:

- **Response Accuracy:** The percentage of correct responses provided by the chatbot.
- **Response Time:** The average time taken by the chatbot to respond to user queries.
- **Customer Satisfaction:** Measured through user feedback and ratings.

#### b. Collect Data

Data is collected from chatbot interactions, including user queries, responses, and feedback.

#### c. Analyze Performance

Performance analysis involves comparing the chatbot's responses against a predefined set of correct responses and calculating accuracy metrics.

#### d. Generate Reports

Reports are generated to provide insights into the chatbot's performance, highlighting areas where it excels and areas needing improvement.

### 8. Best Practices for Agent Evaluation

Here are some best practices to ensure effective agent evaluation:

#### a. Use Realistic Scenarios

Evaluate agents in realistic scenarios that closely mimic real-world conditions. This ensures that the evaluation results are relevant and applicable.

#### b. Continuous Monitoring

Continuously monitor agent performance to detect and address issues promptly. This helps in maintaining high performance levels.

#### c. Incorporate User Feedback

User feedback is invaluable for improving agent performance. Incorporate feedback into the evaluation process to identify and rectify shortcomings.

#### d. Regular Updates

Regularly update the evaluation metrics and criteria to keep pace with evolving tasks and requirements.

### Conclusion

Agent evaluation mechanisms are vital for ensuring the reliability, efficiency, and effectiveness of autonomous agents. By defining clear evaluation metrics, continuously monitoring performance, and using feedback for improvement, we can develop agents that consistently perform at high levels. Visualizing the evaluation process with tools like Mermaid graphs further aids in understanding and communication. Through diligent evaluation and continuous improvement, we can harness the full potential of autonomous agents in various applications.

--------------------------------------------------

# File: guides/financial_analysis_swarm_mm.md

# Building a Multi-Agent System for Real-Time Financial Analysis: A Comprehensive Tutorial

In this tutorial, we'll walk through the process of building a sophisticated multi-agent system for real-time financial analysis using the Swarms framework. This system is designed for financial analysts and developer analysts who want to leverage AI and multiple data sources to gain deeper insights into stock performance, market trends, and economic indicators.

Before we dive into the code, let's briefly introduce the Swarms framework. Swarms is an innovative open-source project that simplifies the creation and management of AI agents. It's particularly well-suited for complex tasks like financial analysis, where multiple specialized agents can work together to provide comprehensive insights.

For more information and to contribute to the project, visit the [Swarms GitHub repository](https://github.com/kyegomez/swarms). We highly recommend exploring the documentation for a deeper understanding of Swarms' capabilities.

Additional resources:
- [Swarms Discord](https://discord.gg/EamjgSaEQf) for community discussions
- [Swarms Twitter](https://x.com/swarms_corp) for updates
- [Swarms Spotify](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) for podcasts
- [Swarms Blog](https://medium.com/@kyeg) for in-depth articles
- [Swarms Website](https://swarms.xyz) for an overview of the project

Now, let's break down our financial analysis system step by step.

## Step 1: Setting Up the Environment
First install the necessary packages:

```bash
$ pip3 install -U swarms yfiance swarm_models fredapi pandas 
```

First, we need to set up our environment and import the necessary libraries:

```python
import os
import time
from datetime import datetime, timedelta
import yfinance as yf
import requests
from fredapi import Fred
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
from swarms import Agent, AgentRearrange
from swarm_models import OpenAIChat
import logging
from dotenv import load_dotenv
import asyncio
import aiohttp
from ratelimit import limits, sleep_and_retry

# Load environment variables
load_dotenv()

# Set up logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
logger = logging.getLogger(__name__)

# API keys
POLYGON_API_KEY = os.getenv('POLYGON_API_KEY')
FRED_API_KEY = os.getenv('FRED_API_KEY')
OPENAI_API_KEY = os.getenv('OPENAI_API_KEY')

# Initialize FRED client
fred_client = Fred(api_key=FRED_API_KEY)

# Polygon API base URL
POLYGON_BASE_URL = "https://api.polygon.io"
```

This section sets up our environment, imports necessary libraries, and initializes our API keys and clients. We're using `dotenv` to securely manage our API keys, and we've set up logging to track the execution of our script.

## Step 2: Implementing Rate Limiting

To respect API rate limits, we implement rate limiting decorators:

```python
@sleep_and_retry
@limits(calls=5, period=60)  # Adjust these values based on your Polygon API tier
async def call_polygon_api(session, endpoint, params=None):
    url = f"{POLYGON_BASE_URL}{endpoint}"
    params = params or {}
    params['apiKey'] = POLYGON_API_KEY
    async with session.get(url, params=params) as response:
        response.raise_for_status()
        return await response.json()

@sleep_and_retry
@limits(calls=120, period=60)  # FRED allows 120 requests per minute
def call_fred_api(func, *args, **kwargs):
    return func(*args, **kwargs)
```

These decorators ensure that we don't exceed the rate limits for our API calls. The `call_polygon_api` function is designed to work with asynchronous code, while `call_fred_api` is a wrapper for synchronous FRED API calls.

## Step 3: Implementing Data Fetching Functions

Next, we implement functions to fetch data from various sources:

### Yahoo Finance Integration

```python
async def get_yahoo_finance_data(session, ticker, period="1d", interval="1m"):
    try:
        stock = yf.Ticker(ticker)
        hist = await asyncio.to_thread(stock.history, period=period, interval=interval)
        info = await asyncio.to_thread(lambda: stock.info)
        return hist, info
    except Exception as e:
        logger.error(f"Error fetching Yahoo Finance data for {ticker}: {e}")
        return None, None

async def get_yahoo_finance_realtime(session, ticker):
    try:
        stock = yf.Ticker(ticker)
        return await asyncio.to_thread(lambda: stock.fast_info)
    except Exception as e:
        logger.error(f"Error fetching Yahoo Finance realtime data for {ticker}: {e}")
        return None
```

These functions fetch historical and real-time data from Yahoo Finance. We use `asyncio.to_thread` to run the synchronous `yfinance` functions in a separate thread, allowing our main event loop to continue running.

### Polygon.io Integration

```python
async def get_polygon_realtime_data(session, ticker):
    try:
        trades = await call_polygon_api(session, f"/v2/last/trade/{ticker}")
        quotes = await call_polygon_api(session, f"/v2/last/nbbo/{ticker}")
        return trades, quotes
    except Exception as e:
        logger.error(f"Error fetching Polygon.io realtime data for {ticker}: {e}")
        return None, None

async def get_polygon_news(session, ticker, limit=10):
    try:
        news = await call_polygon_api(session, f"/v2/reference/news", params={"ticker": ticker, "limit": limit})
        return news.get('results', [])
    except Exception as e:
        logger.error(f"Error fetching Polygon.io news for {ticker}: {e}")
        return []
```

These functions fetch real-time trade and quote data, as well as news articles from Polygon.io. We use our `call_polygon_api` function to make these requests, ensuring we respect rate limits.

### FRED Integration

```python
async def get_fred_data(session, series_id, start_date, end_date):
    try:
        data = await asyncio.to_thread(call_fred_api, fred_client.get_series, series_id, start_date, end_date)
        return data
    except Exception as e:
        logger.error(f"Error fetching FRED data for {series_id}: {e}")
        return None

async def get_fred_realtime(session, series_ids):
    try:
        data = {}
        for series_id in series_ids:
            series = await asyncio.to_thread(call_fred_api, fred_client.get_series, series_id)
            data[series_id] = series.iloc[-1]  # Get the most recent value
        return data
    except Exception as e:
        logger.error(f"Error fetching FRED realtime data: {e}")
        return {}
```

These functions fetch historical and real-time economic data from FRED. Again, we use `asyncio.to_thread` to run the synchronous FRED API calls in a separate thread.

## Step 4: Creating Specialized Agents

Now we create our specialized agents using the Swarms framework:

```python
stock_agent = Agent(
    agent_name="StockAgent",
    system_prompt="""You are an expert stock analyst. Your task is to analyze real-time stock data and provide insights. 
    Consider price movements, trading volume, and any available company information. 
    Provide a concise summary of the stock's current status and any notable trends or events.""",
    llm=OpenAIChat(api_key=OPENAI_API_KEY),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
)

market_agent = Agent(
    agent_name="MarketAgent",
    system_prompt="""You are a market analysis expert. Your task is to analyze overall market conditions using real-time data. 
    Consider major indices, sector performance, and market-wide trends. 
    Provide a concise summary of current market conditions and any significant developments.""",
    llm=OpenAIChat(api_key=OPENAI_API_KEY),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
)

macro_agent = Agent(
    agent_name="MacroAgent",
    system_prompt="""You are a macroeconomic analysis expert. Your task is to analyze key economic indicators and provide insights on the overall economic situation. 
    Consider GDP growth, inflation rates, unemployment figures, and other relevant economic data. 
    Provide a concise summary of the current economic situation and any potential impacts on financial markets.""",
    llm=OpenAIChat(api_key=OPENAI_API_KEY),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
)

news_agent = Agent(
    agent_name="NewsAgent",
    system_prompt="""You are a financial news analyst. Your task is to analyze recent news articles related to specific stocks or the overall market. 
    Consider the potential impact of news events on stock prices or market trends. 
    Provide a concise summary of key news items and their potential market implications.""",
    llm=OpenAIChat(api_key=OPENAI_API_KEY),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
)
```

Each agent is specialized in a different aspect of financial analysis. The `system_prompt` for each agent defines its role and the type of analysis it should perform.

## Step 5: Building the Multi-Agent System

We then combine our specialized agents into a multi-agent system:

```python
agents = [stock_agent, market_agent, macro_agent, news_agent]
flow = "StockAgent -> MarketAgent -> MacroAgent -> NewsAgent"

agent_system = AgentRearrange(agents=agents, flow=flow)
```

The `flow` variable defines the order in which our agents will process information. This allows for a logical progression from specific stock analysis to broader market and economic analysis.

## Step 6: Implementing Real-Time Analysis

Now we implement our main analysis function:

```python
async def real_time_analysis(session, ticker):
    logger.info(f"Starting real-time analysis for {ticker}")
    
    # Fetch real-time data
    yf_data, yf_info = await get_yahoo_finance_data(session, ticker)
    yf_realtime = await get_yahoo_finance_realtime(session, ticker)
    polygon_trades, polygon_quotes = await get_polygon_realtime_data(session, ticker)
    polygon_news = await get_polygon_news(session, ticker)
    fred_data = await get_fred_realtime(session, ['GDP', 'UNRATE', 'CPIAUCSL'])

    # Prepare input for the multi-agent system
    input_data = f"""
    Yahoo Finance Data:
    {yf_realtime}

    Recent Stock History:
    {yf_data.tail().to_string() if yf_data is not None else 'Data unavailable'}

    Polygon.io Trade Data:
    {polygon_trades}

    Polygon.io Quote Data:
    {polygon_quotes}

    Recent News:
    {polygon_news[:3] if polygon_news else 'No recent news available'}

    Economic Indicators:
    {fred_data}

    Analyze this real-time financial data for {ticker}. Provide insights on the stock's performance, overall market conditions, relevant economic factors, and any significant news that might impact the stock or market.
    """

    # Run the multi-agent analysis
    try:
        analysis = agent_system.run(input_data)
        logger.info(f"Analysis completed for {ticker}")
        return analysis
    except Exception as e:
        logger.error(f"Error during multi-agent analysis for {ticker}: {e}")
        return f"Error during analysis: {e}"
```

This function fetches data from all our sources, prepares it as input for our multi-agent system, and then runs the analysis. The result is a comprehensive analysis of the stock, considering individual performance, market conditions, economic factors, and relevant news.

## Step 7: Implementing Advanced Use Cases

We then implement more advanced analysis functions:

### Compare Stocks

```python
async def compare_stocks(session, tickers):
    results = {}
    for ticker in tickers:
        results[ticker] = await real_time_analysis(session, ticker)
    
    comparison_prompt = f"""
    Compare the following stocks based on the provided analyses:
    {results}

    Highlight key differences and similarities. Provide a ranking of these stocks based on their current performance and future prospects.
    """
    
    try:
        comparison = agent_system.run(comparison_prompt)
        logger.info(f"Stock comparison completed for {tickers}")
        return comparison
    except Exception as e:
        logger.error(f"Error during stock comparison: {e}")
        return f"Error during comparison: {e}"
```

This function compares multiple stocks by running a real-time analysis on each and then prompting our multi-agent system to compare the results.

### Sector Analysis

```python
async def sector_analysis(session, sector):
    sector_stocks = {
        'Technology': ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'NVDA'],
        'Finance': ['JPM', 'BAC', 'WFC', 'C', 'GS'],
        'Healthcare': ['JNJ', 'UNH', 'PFE', 'ABT', 'MRK'],
        'Consumer Goods': ['PG', 'KO', 'PEP', 'COST', 'WMT'],
        'Energy': ['XOM', 'CVX', 'COP', 'SLB', 'EOG']
    }
    
    if sector not in sector_stocks:
        return f"Sector '{sector}' not found. Available sectors: {', '.join(sector_stocks.keys())}"
    
    stocks = sector_stocks[sector][:5]
    
    sector_data = {}
    for stock in stocks:
        sector_data[stock] = await real_time_analysis(session, stock)
    
    sector_prompt = f"""
    Analyze the {sector} sector based on the following data from its top stocks:
    {sector_data}

    Provide insights on:
    1. Overall sector performance
    2. Key trends within the sector
    3. Top performing stocks and why they're outperforming
    4. Any challenges or opportunities facing the sector
    """
    
    try:
        analysis = agent_system.run(sector_prompt)
        logger.info(f"Sector analysis completed for {sector}")
        return analysis
    except Exception as e:
        logger.error(f"Error during sector analysis for {sector}: {e}")
        return f"Error during sector analysis: {e}"
```

This function analyzes an entire sector by running real-time analysis on its top stocks and then prompting our multi-agent system to provide sector-wide insights.

### Economic Impact Analysis

```python
async def economic_impact_analysis(session, indicator, threshold):
    # Fetch historical data for the indicator
    end_date = datetime.now().strftime('%Y-%m-%d')
    start_date = (datetime.now() - timedelta(days=365)).strftime('%Y-%m-%d')
    indicator_data = await get_fred_data(session, indicator, start_date, end_date)
    
    if indicator_data is None or len(indicator_data) < 2:
        return f"Insufficient data for indicator {indicator}"
    
    # Check if the latest value crosses the threshold
    latest_value = indicator_data.iloc[-1]
    previous_value = indicator_data.iloc[-2]
    crossed_threshold = (latest_value > threshold and previous_value <= threshold) or (latest_value < threshold and previous_value >= threshold)
    
    if crossed_threshold:
        impact_prompt = f"""
        The economic indicator {indicator} has crossed the threshold of {threshold}. Its current value is {latest_value}.

        Historical data:
        {indicator_data.tail().to_string()}

        Analyze the potential impacts of this change on:
        1. Overall economic conditions
        2. Different market
        2. Different market sectors
        3. Specific types of stocks (e.g., growth vs. value)
        4. Other economic indicators

        Provide a comprehensive analysis of the potential consequences and any recommended actions for investors.
        """
        
        try:
            analysis = agent_system.run(impact_prompt)
            logger.info(f"Economic impact analysis completed for {indicator}")
            return analysis
        except Exception as e:
            logger.error(f"Error during economic impact analysis for {indicator}: {e}")
            return f"Error during economic impact analysis: {e}"
    else:
        return f"The {indicator} indicator has not crossed the threshold of {threshold}. Current value: {latest_value}"
```

This function analyzes the potential impact of significant changes in economic indicators. It fetches historical data, checks if a threshold has been crossed, and if so, prompts our multi-agent system to provide a comprehensive analysis of the potential consequences.

## Step 8: Running the Analysis

Finally, we implement our main function to run all of our analyses:

```python
async def main():
    async with aiohttp.ClientSession() as session:
        # Example usage
        analysis_result = await real_time_analysis(session, 'AAPL')
        print("Single Stock Analysis:")
        print(analysis_result)

        comparison_result = await compare_stocks(session, ['AAPL', 'GOOGL', 'MSFT'])
        print("\nStock Comparison:")
        print(comparison_result)

        tech_sector_analysis = await sector_analysis(session, 'Technology')
        print("\nTechnology Sector Analysis:")
        print(tech_sector_analysis)

        gdp_impact = await economic_impact_analysis(session, 'GDP', 22000)
        print("\nEconomic Impact Analysis:")
        print(gdp_impact)

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

This `main` function demonstrates how to use all of our analysis functions. It runs a single stock analysis, compares multiple stocks, performs a sector analysis, and conducts an economic impact analysis.

## Conclusion and Next Steps

This tutorial has walked you through the process of building a sophisticated multi-agent system for real-time financial analysis using the Swarms framework. Here's a summary of what we've accomplished:

1. Set up our environment and API connections
2. Implemented rate limiting to respect API constraints
3. Created functions to fetch data from multiple sources (Yahoo Finance, Polygon.io, FRED)
4. Designed specialized AI agents for different aspects of financial analysis
5. Combined these agents into a multi-agent system
6. Implemented advanced analysis functions including stock comparison, sector analysis, and economic impact analysis

This system provides a powerful foundation for financial analysis, but there's always room for expansion and improvement. Here are some potential next steps:

1. **Expand data sources**: Consider integrating additional financial data providers for even more comprehensive analysis.

2. **Enhance agent specialization**: You could create more specialized agents, such as a technical analysis agent or a sentiment analysis agent for social media data.

3. **Implement a user interface**: Consider building a web interface or dashboard to make the system more user-friendly for non-technical analysts.

4. **Add visualization capabilities**: Integrate data visualization tools to help interpret complex financial data more easily.

5. **Implement a backtesting system**: Develop a system to evaluate your multi-agent system's performance on historical data.

6. **Explore advanced AI models**: The Swarms framework supports various AI models. Experiment with different models to see which performs best for your specific use case.

7. **Implement real-time monitoring**: Set up a system to continuously monitor markets and alert you to significant changes or opportunities.

Remember, the Swarms framework is a powerful and flexible tool that can be adapted to a wide range of complex tasks beyond just financial analysis. We encourage you to explore the [Swarms GitHub repository](https://github.com/kyegomez/swarms) for more examples and inspiration.

For more in-depth discussions and community support, consider joining the [Swarms Discord](https://discord.gg/EamjgSaEQf). You can also stay updated with the latest developments by following [Swarms on Twitter](https://x.com/swarms_corp).

If you're interested in learning more about AI and its applications in various fields, check out the [Swarms Spotify podcast](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994) and the [Swarms Blog](https://medium.com/@kyeg) for insightful articles and discussions.

Lastly, don't forget to visit the [Swarms Website](https://swarms.xyz) for a comprehensive overview of the project and its capabilities.

By leveraging the power of multi-agent AI systems, you're well-equipped to navigate the complex world of financial markets. Happy analyzing!



## Swarm Resources:


* [Swarms Github](https://github.com/kyegomez/swarms)
* [Swarms Discord](https://discord.gg/EamjgSaEQf)
* [Swarms Twitter](https://x.com/swarms_corp)
* [Swarms Spotify](https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994)
* [Swarms Blog](https://medium.com/@kyeg)
* [Swarms Website](https://swarms.xyz)

--------------------------------------------------

# File: guides/financial_data_api.md

# Analyzing Financial Data with AI Agents using Swarms Framework

In the rapidly evolving landscape of quantitative finance, the integration of artificial intelligence with financial data analysis has become increasingly crucial. This blog post will explore how to leverage the power of AI agents, specifically using the Swarms framework, to analyze financial data from various top-tier data providers. We'll demonstrate how to connect these agents with different financial APIs, enabling sophisticated analysis and decision-making processes.

## Table of Contents

1. [Introduction to Swarms Framework](#introduction-to-swarms-framework)
2. [Setting Up the Environment](#setting-up-the-environment)
3. [Connecting AI Agents with Financial Data Providers](#connecting-ai-agents-with-financial-data-providers)
   - [Polygon.io](#polygonio)
   - [Alpha Vantage](#alpha-vantage)
   - [Yahoo Finance](#yahoo-finance)
   - [IEX Cloud](#iex-cloud)
   - [Finnhub](#finnhub)
4. [Advanced Analysis Techniques](#advanced-analysis-techniques)
5. [Best Practices and Considerations](#best-practices-and-considerations)
6. [Conclusion](#conclusion)

## Introduction to Swarms Framework

The Swarms framework is a powerful tool for building and deploying AI agents that can interact with various data sources and perform complex analyses. In the context of financial data analysis, Swarms can be used to create intelligent agents that can process large volumes of financial data, identify patterns, and make data-driven decisions. Explore our github for examples, applications, and more.

## Setting Up the Environment

Before we dive into connecting AI agents with financial data providers, let's set up our environment:

1. Install the Swarms framework:

```bash
pip install -U swarms
```

2. Install additional required libraries:

```bash
pip install requests pandas numpy matplotlib
```

3. Set up your API keys for the various financial data providers. It's recommended to use environment variables or a secure configuration file to store these keys.

## Connecting AI Agents with Financial Data Providers

Now, let's explore how to connect AI agents using the Swarms framework with different financial data providers.

### Polygon.io

First, we'll create an AI agent that can fetch and analyze stock data from Polygon.io.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import requests
import pandas as pd

load_dotenv()

# Polygon.io API setup
POLYGON_API_KEY = os.getenv("POLYGON_API_KEY")
POLYGON_BASE_URL = "https://api.polygon.io/v2"

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant. Your task is to analyze stock data and provide insights.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbol, from_date, to_date):
    endpoint = f"{POLYGON_BASE_URL}/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}"
    params = {
        'apiKey': POLYGON_API_KEY,
        'adjusted': 'true'
    }
    response = requests.get(endpoint, params=params)
    data = response.json()
    return pd.DataFrame(data['results'])

# Example usage
symbol = "AAPL"
from_date = "2023-01-01"
to_date = "2023-12-31"

stock_data = get_stock_data(symbol, from_date, to_date)

analysis_request = f"""
Analyze the following stock data for {symbol} from {from_date} to {to_date}:

{stock_data.to_string()}

Provide insights on the stock's performance, including trends, volatility, and any notable events.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

In this example, we've created an AI agent that can fetch stock data from Polygon.io and perform an analysis based on that data. The agent uses the GPT-4 model to generate insights about the stock's performance.

### Alpha Vantage

Next, let's create an agent that can work with Alpha Vantage data to perform fundamental analysis.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import requests

load_dotenv()

# Alpha Vantage API setup
ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY")
ALPHA_VANTAGE_BASE_URL = "https://www.alphavantage.co/query"

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Fundamental-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in fundamental analysis. Your task is to analyze company financials and provide insights.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_income_statement(symbol):
    params = {
        'function': 'INCOME_STATEMENT',
        'symbol': symbol,
        'apikey': ALPHA_VANTAGE_API_KEY
    }
    response = requests.get(ALPHA_VANTAGE_BASE_URL, params=params)
    return response.json()

# Example usage
symbol = "MSFT"

income_statement = get_income_statement(symbol)

analysis_request = f"""
Analyze the following income statement data for {symbol}:

{income_statement}

Provide insights on the company's financial health, profitability trends, and any notable observations.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates an AI agent that can fetch income statement data from Alpha Vantage and perform a fundamental analysis of a company's financials.

### Yahoo Finance

Now, let's create an agent that can work with Yahoo Finance data to perform technical analysis.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import pandas as pd

load_dotenv()

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Technical-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in technical analysis. Your task is to analyze stock price data and provide insights on trends and potential trading signals.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbol, start_date, end_date):
    stock = yf.Ticker(symbol)
    data = stock.history(start=start_date, end=end_date)
    return data

# Example usage
symbol = "GOOGL"
start_date = "2023-01-01"
end_date = "2023-12-31"

stock_data = get_stock_data(symbol, start_date, end_date)

# Calculate some technical indicators
stock_data['SMA_20'] = stock_data['Close'].rolling(window=20).mean()
stock_data['SMA_50'] = stock_data['Close'].rolling(window=50).mean()

analysis_request = f"""
Analyze the following stock price data and technical indicators for {symbol} from {start_date} to {end_date}:

{stock_data.tail(30).to_string()}

Provide insights on the stock's price trends, potential support and resistance levels, and any notable trading signals based on the moving averages.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example shows an AI agent that can fetch stock price data from Yahoo Finance, calculate some basic technical indicators, and perform a technical analysis.

### IEX Cloud

Let's create an agent that can work with IEX Cloud data to analyze company news sentiment.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import requests

load_dotenv()

# IEX Cloud API setup
IEX_CLOUD_API_KEY = os.getenv("IEX_CLOUD_API_KEY")
IEX_CLOUD_BASE_URL = "https://cloud.iexapis.com/stable"

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="News-Sentiment-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in news sentiment analysis. Your task is to analyze company news and provide insights on the overall sentiment and potential impact on the stock.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_company_news(symbol, last_n):
    endpoint = f"{IEX_CLOUD_BASE_URL}/stock/{symbol}/news/last/{last_n}"
    params = {'token': IEX_CLOUD_API_KEY}
    response = requests.get(endpoint, params=params)
    return response.json()

# Example usage
symbol = "TSLA"
last_n = 10

news_data = get_company_news(symbol, last_n)

analysis_request = f"""
Analyze the following recent news articles for {symbol}:

{news_data}

Provide insights on the overall sentiment of the news, potential impact on the stock price, and any notable trends or events mentioned.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates an AI agent that can fetch recent news data from IEX Cloud and perform a sentiment analysis on the company news.

### Finnhub

Finally, let's create an agent that can work with Finnhub data to analyze earnings estimates and recommendations.

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import finnhub

load_dotenv()

# Finnhub API setup
FINNHUB_API_KEY = os.getenv("FINNHUB_API_KEY")
finnhub_client = finnhub.Client(api_key=FINNHUB_API_KEY)

# OpenAI API setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Earnings-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in earnings analysis. Your task is to analyze earnings estimates and recommendations to provide insights on a company's financial outlook.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_earnings_estimates(symbol):
    return finnhub_client.earnings_calendar(symbol=symbol, from_date="2023-01-01", to_date="2023-12-31")

def get_recommendations(symbol):
    return finnhub_client.recommendation_trends(symbol)

# Example usage
symbol = "NVDA"

earnings_estimates = get_earnings_estimates(symbol)
recommendations = get_recommendations(symbol)

analysis_request = f"""
Analyze the following earnings estimates and recommendations for {symbol}:

Earnings Estimates:
{earnings_estimates}

Recommendations:
{recommendations}

Provide insights on the company's expected financial performance, analyst sentiment, and any notable trends in the recommendations.
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example shows an AI agent that can fetch earnings estimates and analyst recommendations from Finnhub and perform an analysis on the company's financial outlook.

## Advanced Analysis Techniques

To further enhance the capabilities of our AI agents, we can implement more advanced analysis techniques:

1. Multi-source analysis: Combine data from multiple providers to get a more comprehensive view of a stock or market.

2. Time series forecasting: Implement machine learning models for price prediction.

3. Sentiment analysis of social media: Incorporate data from social media platforms to gauge market sentiment.

4. Portfolio optimization: Use AI agents to suggest optimal portfolio allocations based on risk tolerance and investment goals.

5. Anomaly detection: Implement algorithms to detect unusual patterns or events in financial data.

Here's an example of how we might implement a multi-source analysis:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import requests
import pandas as pd

load_dotenv()

# API setup
POLYGON_API_KEY = os.getenv("POLYGON_API_KEY")
ALPHA_VANTAGE_API_KEY = os.getenv("ALPHA_VANTAGE_API_KEY")
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Multi-Source-Analysis-Agent",
    system_prompt="You are a financial analysis AI assistant capable of analyzing data from multiple sources. Your task is to provide comprehensive insights on a stock based on various data points.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data_yf(symbol, start_date, end_date):
    stock = yf.Ticker(symbol)
    return stock.history(start=start_date, end=end_date)

def get_stock_data_polygon(symbol, from_date, to_date):
    endpoint = f"https://api.polygon.io/v2/aggs/ticker/{symbol}/range/1/day/{from_date}/{to_date}"
    params = {'apiKey': POLYGON_API_KEY, 'adjusted': 'true'}
    response = requests.get(endpoint, params=params)
    data = response.json()
    return pd.DataFrame(data['results'])

def get_company_overview_av(symbol):
    params = {
        'function': 'OVERVIEW',
        'symbol': symbol,
        'apikey': ALPHA_VANTAGE_API_KEY
    }
    response = requests.get("https://www.alphavantage.co/query", params=params)
    return response.json()

# Example usage
symbol = "AAPL"
start_date = "2023-01-01"
end_date = "2023-12-31"

yf_data = get_stock_data_yf(symbol, start_date, end_date)
polygon_data = get_stock_data_polygon(symbol, start_date, end_date)
av_overview = get_company_overview_av(symbol)

analysis_request = f"""
Analyze the following data for {symbol} from {start_date} to {end_date}:

Yahoo Finance Data:
{yf_data.tail().to_string()}

Polygon.io Data:
{polygon_data.tail().to_string()}

Alpha Vantage Company Overview:
{av_overview}

Provide a comprehensive analysis of the stock, including:
1. Price trends and volatility
2. Trading volume analysis
3. Fundamental analysis based on the company overview
4. Any discrepancies between data sources and potential reasons
5. Overall outlook and potential risks/opportunities
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This multi-source analysis example combines data from Yahoo Finance, Polygon.io, and Alpha Vantage to provide a more comprehensive view of a stock. The AI agent can then analyze this diverse set of data to provide deeper insights.

Now, let's explore some additional advanced analysis techniques:

### Time Series Forecasting

We can implement a simple time series forecasting model using the Prophet library and integrate it with our AI agent:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import pandas as pd
from prophet import Prophet
import matplotlib.pyplot as plt

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

agent = Agent(
    agent_name="Time-Series-Forecast-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in time series forecasting. Your task is to analyze stock price predictions and provide insights.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbol, start_date, end_date):
    stock = yf.Ticker(symbol)
    data = stock.history(start=start_date, end=end_date)
    return data

def forecast_stock_price(data, periods=30):
    df = data.reset_index()[['Date', 'Close']]
    df.columns = ['ds', 'y']
    
    model = Prophet()
    model.fit(df)
    
    future = model.make_future_dataframe(periods=periods)
    forecast = model.predict(future)
    
    fig = model.plot(forecast)
    plt.savefig('forecast_plot.png')
    plt.close()
    
    return forecast

# Example usage
symbol = "MSFT"
start_date = "2020-01-01"
end_date = "2023-12-31"

stock_data = get_stock_data(symbol, start_date, end_date)
forecast = forecast_stock_price(stock_data)

analysis_request = f"""
Analyze the following time series forecast for {symbol}:

Forecast Data:
{forecast.tail(30).to_string()}

The forecast plot has been saved as 'forecast_plot.png'.

Provide insights on:
1. The predicted trend for the stock price
2. Any seasonal patterns observed
3. Potential factors that might influence the forecast
4. Limitations of this forecasting method
5. Recommendations for investors based on this forecast
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates how to integrate a time series forecasting model (Prophet) with our AI agent. The agent can then provide insights based on the forecasted data.

### Sentiment Analysis of Social Media

We can use a pre-trained sentiment analysis model to analyze tweets about a company and integrate this with our AI agent:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import tweepy
from textblob import TextBlob
import pandas as pd

load_dotenv()

# Twitter API setup
TWITTER_API_KEY = os.getenv("TWITTER_API_KEY")
TWITTER_API_SECRET = os.getenv("TWITTER_API_SECRET")
TWITTER_ACCESS_TOKEN = os.getenv("TWITTER_ACCESS_TOKEN")
TWITTER_ACCESS_TOKEN_SECRET = os.getenv("TWITTER_ACCESS_TOKEN_SECRET")

auth = tweepy.OAuthHandler(TWITTER_API_KEY, TWITTER_API_SECRET)
auth.set_access_token(TWITTER_ACCESS_TOKEN, TWITTER_ACCESS_TOKEN_SECRET)
api = tweepy.API(auth)

# OpenAI setup
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

agent = Agent(
    agent_name="Social-Media-Sentiment-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in social media sentiment analysis. Your task is to analyze sentiment data from tweets and provide insights on market perception.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_tweets(query, count=100):
    tweets = api.search_tweets(q=query, count=count, tweet_mode="extended")
    return [tweet.full_text for tweet in tweets]

def analyze_sentiment(tweets):
    sentiments = [TextBlob(tweet).sentiment.polarity for tweet in tweets]
    return pd.DataFrame({'tweet': tweets, 'sentiment': sentiments})

# Example usage
symbol = "TSLA"
query = f"${symbol} stock"

tweets = get_tweets(query)
sentiment_data = analyze_sentiment(tweets)

analysis_request = f"""
Analyze the following sentiment data for tweets about {symbol} stock:

Sentiment Summary:
Positive tweets: {sum(sentiment_data['sentiment'] > 0)}
Negative tweets: {sum(sentiment_data['sentiment'] < 0)}
Neutral tweets: {sum(sentiment_data['sentiment'] == 0)}

Average sentiment: {sentiment_data['sentiment'].mean()}

Sample tweets and their sentiments:
{sentiment_data.head(10).to_string()}

Provide insights on:
1. The overall sentiment towards the stock
2. Any notable trends or patterns in the sentiment
3. Potential reasons for the observed sentiment
4. How this sentiment might impact the stock price
5. Limitations of this sentiment analysis method
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example shows how to perform sentiment analysis on tweets about a stock and integrate the results with our AI agent for further analysis.

### Portfolio Optimization

We can use the PyPortfolioOpt library to perform portfolio optimization and have our AI agent provide insights:

```python
import os
from swarms import Agent
from swarms.models import OpenAIChat
from dotenv import load_dotenv
import yfinance as yf
import pandas as pd
import numpy as np
from pypfopt import EfficientFrontier
from pypfopt import risk_models
from pypfopt import expected_returns

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

model = OpenAIChat(
    openai_api_key=OPENAI_API_KEY,
    model_name="gpt-4",
    temperature=0.1
)

agent = Agent(
    agent_name="Portfolio-Optimization-Agent",
    system_prompt="You are a financial analysis AI assistant specializing in portfolio optimization. Your task is to analyze optimized portfolio allocations and provide investment advice.",
    llm=model,
    max_loops=1,
    dashboard=False,
    verbose=True
)

def get_stock_data(symbols, start_date, end_date):
    data = yf.download(symbols, start=start_date, end=end_date)['Adj Close']
    return data

def optimize_portfolio(data):
    mu = expected_returns.mean_historical_return(data)
    S = risk_models.sample_cov(data)
    
    ef = EfficientFrontier(mu, S)
    weights = ef.max_sharpe()
    cleaned_weights = ef.clean_weights()
    
    return cleaned_weights

# Example usage
symbols = ["AAPL", "GOOGL", "MSFT", "AMZN", "FB"]
start_date = "2018-01-01"
end_date = "2023-12-31"

stock_data = get_stock_data(symbols, start_date, end_date)
optimized_weights = optimize_portfolio(stock_data)

analysis_request = f"""
Analyze the following optimized portfolio allocation:

{pd.Series(optimized_weights).to_string()}

The optimization aimed to maximize the Sharpe ratio based on historical data from {start_date} to {end_date}.

Provide insights on:
1. The recommended allocation and its potential benefits
2. Any notable concentrations or diversification in the portfolio
3. Potential risks associated with this allocation
4. How this portfolio might perform in different market conditions
5. Recommendations for an investor considering this allocation
6. Limitations of this optimization method
"""

analysis = agent.run(analysis_request)
print(analysis)
```

This example demonstrates how to perform portfolio optimization using the PyPortfolioOpt library and have our AI agent provide insights on the optimized allocation.

## Best Practices and Considerations

When using AI agents for financial data analysis, consider the following best practices:

1. Data quality: Ensure that the data you're feeding into the agents is accurate and up-to-date.

2. Model limitations: Be aware of the limitations of both the financial models and the AI models being used.

3. Regulatory compliance: Ensure that your use of AI in financial analysis complies with relevant regulations.

4. Ethical considerations: Be mindful of potential biases in AI models and strive for fair and ethical analysis.

5. Continuous monitoring: Regularly evaluate the performance of your AI agents and update them as needed.

6. Human oversight: While AI agents can provide valuable insights, human judgment should always play a role in financial decision-making.

7. Privacy and security: Implement robust security measures to protect sensitive financial data.

## Conclusion

The integration of AI agents with financial data APIs opens up exciting possibilities for advanced financial analysis. By leveraging the power of the Swarms framework and connecting it with various financial data providers, analysts and quants can gain deeper insights, automate complex analyses, and potentially make more informed investment decisions.

However, it's crucial to remember that while AI agents can process vast amounts of data and identify patterns that humans might miss, they should be used as tools to augment human decision-making rather than replace it entirely. The financial markets are complex systems influenced by numerous factors, many of which may not be captured in historical data or current models.

As the field of AI in finance continues to evolve, we can expect even more sophisticated analysis techniques and integrations. Staying updated with the latest developments in both AI and financial analysis will be key to leveraging these powerful tools effectively.

--------------------------------------------------

# File: guides/healthcare_blog.md

# Unlocking Efficiency and Cost Savings in Healthcare: How Swarms of LLM Agents Can Revolutionize Medical Operations and Save Millions

The healthcare industry is a complex ecosystem where time and money are critical. From administrative tasks to patient care, medical professionals often struggle to keep up with mounting demands, leading to inefficiencies that cost both time and money. Swarms of Large Language Model (LLM) agents represent a groundbreaking solution to these problems. By leveraging artificial intelligence in the form of swarms, healthcare organizations can automate various tasks, optimize processes, and dramatically improve both the quality of care and operational efficiency.

In this comprehensive analysis, we will explore how swarms of LLM agents can help healthcare and medical organizations save millions of dollars and thousands of hours annually. We will provide precise estimations based on industry data, calculate potential savings, and outline various use cases. Additionally, mermaid diagrams will be provided to illustrate swarm architectures, and reference links to Swarms GitHub and other resources will be included.

### 1. Administrative Automation

#### Use Case: Billing and Claims Processing

Administrative work is a major time drain in the healthcare sector, especially when it comes to billing and claims processing. The process is traditionally labor-intensive, requiring human staff to manually review and process claims, which often results in errors, delays, and higher operational costs.

**How Swarms of LLM Agents Can Help:**
Swarms of LLM agents can automate the entire billing and claims process, from coding procedures to filing claims with insurance companies. These agents can read medical records, understand the diagnosis codes (ICD-10), and automatically generate billing forms. With intelligent claims management, LLM agents can also follow up with insurance companies to ensure timely payment.

**Estimated Savings:**

- Average cost per manual claim: $25

- Average claims per hospital: 10,000 per month

- Swarms of LLM agents can reduce processing time by 90% and errors by 95%

- Estimated annual savings per hospital: 

    - Savings per claim: $22.5 (90% reduction)

    - Total annual savings: 10,000 claims/month × 12 months × $22.5 = **$2.7 million**


#### Billing and Claims Processing Swarm
```mermaid
graph TD;
    A[Medical Records] --> B[ICD-10 Coding Agent];
    B --> C[Billing Form Agent];
    C --> D[Claims Submission Agent];
    D --> E[Insurance Follow-up Agent];
    E --> F[Payment Processing];
```

### 2. Enhancing Clinical Decision Support

#### Use Case: Diagnostic Assistance

Doctors are increasingly turning to AI to assist in diagnosing complex medical conditions. Swarms of LLM agents can be trained to analyze patient data, laboratory results, and medical histories to assist doctors in making more accurate diagnoses.

**How Swarms of LLM Agents Can Help:**
A swarm of LLM agents can scan through thousands of medical records, journals, and patient histories to identify patterns or suggest rare diagnoses. These agents work collaboratively to analyze test results, compare symptoms with a vast medical knowledge base, and provide doctors with a list of probable diagnoses and recommended tests.

**Estimated Savings:**

- Time saved per diagnosis: 2 hours per patient

- Average patient cases per hospital: 5,000 per year

- Time saved annually: 2 × 5,000 = 10,000 hours

- Doctor's hourly rate: $150

- Total annual savings: 10,000 × $150 = **$1.5 million**


#### Diagnostic Swarm
```mermaid
graph TD;
    A[Patient Data] --> B[Lab Results];
    A --> C[Medical History];
    B --> D[Symptom Analysis Agent];
    C --> E[Pattern Recognition Agent];
    D --> F[Diagnosis Suggestion Agent];
    E --> F;
    F --> G[Doctor];
```

### 3. Streamlining Patient Communication

#### Use Case: Patient Follow-ups and Reminders

Timely communication with patients is critical for maintaining healthcare quality, but it can be extremely time-consuming for administrative staff. Missed appointments and delayed follow-ups lead to poor patient outcomes and lost revenue.

**How Swarms of LLM Agents Can Help:**
LLM agents can handle patient follow-ups by sending reminders for appointments, check-ups, and medication refills. Additionally, these agents can answer common patient queries, thereby reducing the workload for human staff. These agents can be connected to Electronic Health Record (EHR) systems to monitor patient data and trigger reminders based on predefined criteria.

**Estimated Savings:**

- Average cost per patient follow-up: $5

- Number of follow-ups: 20,000 annually per hospital

- Swarm efficiency: 90% reduction in manual effort

- Total annual savings: 20,000 × $4.5 = **$90,000**


#### Patient Follow-up Swarm
```mermaid
graph TD;
    A[Patient Data from EHR] --> B[Appointment Reminder Agent];
    A --> C[Medication Reminder Agent];
    B --> D[Automated Text/Email];
    C --> D;
    D --> E[Patient];
```

### 4. Optimizing Inventory Management

#### Use Case: Pharmaceutical Stock Management

Hospitals often struggle with managing pharmaceutical inventory efficiently. Overstocking leads to wasted resources, while understocking can be a critical problem for patient care.

**How Swarms of LLM Agents Can Help:**
A swarm of LLM agents can predict pharmaceutical needs by analyzing patient data, historical inventory usage, and supplier delivery times. These agents can dynamically adjust stock levels, automatically place orders, and ensure that hospitals have the right medications at the right time.

**Estimated Savings:**

- Annual waste due to overstocking: $500,000 per hospital

- Swarm efficiency: 80% reduction in overstocking

- Total annual savings: $500,000 × 0.8 = **$400,000**


#### Inventory Management Swarm
```mermaid
graph TD;
    A[Patient Admission Data] --> B[Inventory Prediction Agent];
    B --> C[Stock Adjustment Agent];
    C --> D[Supplier Ordering Agent];
    D --> E[Pharmacy];
```

### 5. Improving Clinical Research

#### Use Case: Literature Review and Data Analysis

Medical researchers spend a significant amount of time reviewing literature and analyzing clinical trial data. Swarms of LLM agents can assist by rapidly scanning through research papers, extracting relevant information, and even suggesting areas for further investigation.

**How Swarms of LLM Agents Can Help:**
These agents can be trained to perform literature reviews, extract relevant data, and cross-reference findings with ongoing clinical trials. LLM agents can also simulate clinical trial results by analyzing historical data, offering valuable insights before actual trials commence.

**Estimated Savings:**

- Average time spent on literature review per paper: 5 hours

- Number of papers reviewed annually: 1,000

- Time saved: 80% reduction in review time

- Total time saved: 1,000 × 5 × 0.8 = 4,000 hours

- Researcher's hourly rate: $100

- Total annual savings: 4,000 × $100 = **$400,000**


#### Clinical Research Swarm
```mermaid
graph TD;
    A[Research Papers] --> B[Data Extraction Agent];
    B --> C[Cross-reference Agent];
    C --> D[Simulation Agent];
    D --> E[Researcher];
```

### 6. Automating Medical Record Keeping

#### Use Case: EHR Management and Documentation

Healthcare providers spend a significant amount of time inputting and managing Electronic Health Records (EHR). Manual entry often results in errors and takes away from the time spent with patients.

**How Swarms of LLM Agents Can Help:**
Swarms of LLM agents can automate the documentation process by transcribing doctor-patient interactions, updating EHRs in real-time, and even detecting errors in the documentation. These agents can integrate with voice recognition systems to create seamless workflows, freeing up more time for healthcare providers to focus on patient care.

**Estimated Savings:**

- Average time spent on EHR per patient: 20 minutes

- Number of patients annually: 30,000

- Time saved: 80% reduction in manual effort

- Total time saved: 30,000 × 20 minutes × 0.8 = 480,000 minutes or 8,000 hours

- Provider's hourly rate: $150

- Total annual savings: 8,000 × $150 = **$1.2 million**


#### EHR Management Swarm
```mermaid
graph TD;
    A[Doctor-Patient Interaction] --> B[Voice-to-Text Agent];
    B --> C[EHR Update Agent];
    C --> D[Error Detection Agent];
    D --> E[EHR System];
```

### 7. Reducing Diagnostic Errors

#### Use Case: Medical Imaging Analysis

Medical imaging, such as MRI and CT scans, requires expert interpretation, which can be both time-consuming and prone to errors. Misdiagnoses or delays in interpretation can lead to prolonged treatment times and increased costs.

**How Swarms of LLM Agents Can Help:**
Swarms of LLM agents trained in computer vision can analyze medical images more accurately and faster than human radiologists. These agents can compare current scans with historical data, detect anomalies, and provide a diagnosis within minutes. Additionally, the swarm can escalate complex cases to human experts when necessary.

**Estimated Savings:**

- Time saved per scan: 30 minutes

- Number of scans annually: 10,000

- Time saved: 10,000 × 30 minutes = 5,000 hours

- Radiologist's hourly rate: $200

- Total annual savings: 5,000 × $


200 = **$1 million**

#### Medical Imaging Swarm
```mermaid
graph TD;
    A[Medical Image] --> B[Anomaly Detection Agent];
    B --> C[Comparison with Historical Data Agent];
    C --> D[Diagnosis Suggestion Agent];
    D --> E[Radiologist Review];
```

### Conclusion: The Financial and Time-Saving Impact of LLM Swarms in Healthcare


In this comprehensive analysis, we explored how swarms of LLM agents can revolutionize the healthcare and medical industries by automating complex, labor-intensive tasks that currently drain both time and resources. From billing and claims processing to diagnostic assistance, patient communication, and medical imaging analysis, these intelligent agents can work collaboratively to significantly improve efficiency while reducing costs. Through our detailed calculations, it is evident that healthcare organizations could save upwards of $7.29 million annually, along with thousands of hours in administrative and clinical work.

Swarms of LLM agents not only promise financial savings but also lead to improved patient outcomes, streamlined research, and enhanced operational workflows. By adopting these agentic solutions, healthcare organizations can focus more on their mission of providing high-quality care while ensuring their systems run seamlessly and efficiently.

To explore more about how swarms of agents can be tailored to your healthcare operations, you can visit the [Swarms GitHub](https://github.com/kyegomez/swarms) for code and documentation, explore our [Swarms Website](https://swarms.world) for further insights, and if you're ready to implement these solutions in your organization, feel free to [book a call](https://cal.com/swarms) for a personalized consultation.

The future of healthcare is agentic, and by embracing swarms of LLM agents, your organization can unlock unprecedented levels of productivity and savings.

Swarms of LLM agents offer a powerful solution for medical and healthcare organizations looking to reduce costs and save time. Through automation, these agents can optimize everything from administrative tasks to clinical decision-making and inventory management. Based on the estimates provided, healthcare organizations can potentially save millions of dollars annually, all while improving the quality of care provided to patients.

The table below summarizes the estimated savings for each use case:

| Use Case                          | Estimated Annual Savings |
|------------------------------------|--------------------------|
| Billing and Claims Processing      | $2.7 million             |
| Diagnostic Assistance              | $1.5 million             |
| Patient Follow-ups and Reminders   | $90,000                  |
| Pharmaceutical Stock Management    | $400,000                 |
| Clinical Research                  | $400,000                 |
| EHR Management and Documentation   | $1.2 million             |
| Medical Imaging Analysis           | $1 million               |
| **Total Estimated Savings**        | **$7.29 million**        |

### References
- [Swarms GitHub](https://github.com/kyegomez/swarms)

- [Swarms Website](https://swarms.xyz)

- [book a call](https://cal.com/swarms) 

- Swarms Discord: https://discord.gg/EamjgSaEQf

- Swarms Twitter: https://x.com/swarms_corp

- Swarms Spotify: https://open.spotify.com/show/2HLiswhmUaMdjHC8AUHcCF?si=c831ef10c5ef4994

Swarms Blog: https://medium.com/@kyeg
Swarms Website: https://swarms.xyz 

By adopting swarms of LLM agents, healthcare organizations can streamline operations, reduce inefficiencies, and focus on what truly matters—delivering top-notch patient care.



--------------------------------------------------

# File: guides/pricing.md

# Comparing LLM Provider Pricing: A Guide for Enterprises

Large language models (LLMs) have become a cornerstone of innovation for enterprises across various industries. 

As executives contemplate which model to integrate into their operations, understanding the intricacies of LLM provider pricing is crucial. 

This comprehensive guide delves into the tactical business considerations, unit economics, profit margins, and ROI calculations that will empower decision-makers to deploy the right AI solution for their organization.

## Table of Contents

1. [Introduction to LLM Pricing Models](#introduction-to-llm-pricing-models)
2. [Understanding Unit Economics in LLM Deployment](#understanding-unit-economics-in-llm-deployment)
3. [Profit Margins and Cost Structures](#profit-margins-and-cost-structures)
4. [LLM Pricing in Action: Case Studies](#llm-pricing-in-action-case-studies)
5. [Calculating ROI for LLM Integration](#calculating-roi-for-llm-integration)
6. [Comparative Analysis of Major LLM Providers](#comparative-analysis-of-major-llm-providers)
7. [Hidden Costs and Considerations](#hidden-costs-and-considerations)
8. [Optimizing LLM Usage for Cost-Efficiency](#optimizing-llm-usage-for-cost-efficiency)
9. [Future Trends in LLM Pricing](#future-trends-in-llm-pricing)
10. [Strategic Decision-Making Framework](#strategic-decision-making-framework)
11. [Conclusion: Navigating the LLM Pricing Landscape](#conclusion-navigating-the-llm-pricing-landscape)

## 1. Introduction to LLM Pricing Models

The pricing of Large Language Models (LLMs) is a complex landscape that can significantly impact an enterprise's bottom line. As we dive into this topic, it's crucial to understand the various pricing models employed by LLM providers and how they align with different business needs.

### Pay-per-Token Model

The most common pricing structure in the LLM market is the pay-per-token model. In this system, businesses are charged based on the number of tokens processed by the model. A token can be as short as one character or as long as one word, depending on the language and the specific tokenization method used by the model.

**Advantages:**
- Scalability: Costs scale directly with usage, allowing for flexibility as demand fluctuates.
- Transparency: Easy to track and attribute costs to specific projects or departments.

**Disadvantages:**
- Unpredictability: Costs can vary significantly based on the verbosity of inputs and outputs.
- Potential for overruns: Without proper monitoring, costs can quickly escalate.

### Subscription-Based Models

Some providers offer subscription tiers that provide a set amount of compute resources or tokens for a fixed monthly or annual fee.

**Advantages:**
- Predictable costs: Easier budgeting and financial planning.
- Potential cost savings: Can be more economical for consistent, high-volume usage.

**Disadvantages:**
- Less flexibility: May lead to underutilization or overages.
- Commitment required: Often involves longer-term contracts.

### Custom Enterprise Agreements

For large-scale deployments, providers may offer custom pricing agreements tailored to the specific needs of an enterprise.

**Advantages:**
- Optimized for specific use cases: Can include specialized support, SLAs, and pricing structures.
- Potential for significant cost savings at scale.

**Disadvantages:**
- Complexity: Negotiating and managing these agreements can be resource-intensive.
- Less standardization: Difficult to compare across providers.

### Hybrid Models

Some providers are beginning to offer hybrid models that combine elements of pay-per-token and subscription-based pricing.

**Advantages:**
- Flexibility: Can adapt to varying usage patterns.
- Risk mitigation: Balances the benefits of both main pricing models.

**Disadvantages:**
- Complexity: Can be more challenging to understand and manage.
- Potential for suboptimal pricing if not carefully structured.

As we progress through this guide, we'll explore how these pricing models interact with various business considerations and how executives can leverage this understanding to make informed decisions.

## 2. Understanding Unit Economics in LLM Deployment

To make informed decisions about LLM deployment, executives must have a clear grasp of the unit economics involved. This section breaks down the components that contribute to the cost per unit of LLM usage and how they impact overall business economics.

### Defining the Unit

In the context of LLMs, a "unit" can be defined in several ways:

1. **Per Token**: The most granular unit, often used in pricing models.
2. **Per Request**: A single API call to the LLM, which may process multiple tokens.
3. **Per Task**: A complete operation, such as generating a summary or answering a question, which may involve multiple requests.
4. **Per User Interaction**: In customer-facing applications, this could be an entire conversation or session.

Understanding which unit is most relevant to your use case is crucial for accurate economic analysis.

### Components of Unit Cost

1. **Direct LLM Costs**
   - Token processing fees
   - API call charges
   - Data transfer costs

2. **Indirect Costs**
   - Compute resources for pre/post-processing
   - Storage for inputs, outputs, and fine-tuning data
   - Networking costs

3. **Operational Costs**
   - Monitoring and management tools
   - Integration and maintenance engineering time
   - Customer support related to AI functions

4. **Overhead**
   - Legal and compliance costs
   - Training and documentation
   - Risk management and insurance

### Calculating Unit Economics

To calculate the true unit economics, follow these steps:

1. **Determine Total Costs**: Sum all direct, indirect, operational, and overhead costs over a fixed period (e.g., monthly).

2. **Measure Total Units**: Track the total number of relevant units processed in the same period.

3. **Calculate Cost per Unit**: Divide total costs by total units.

   ```
   Cost per Unit = Total Costs / Total Units
   ```

4. **Analyze Revenue per Unit**: If the LLM is part of a revenue-generating product, calculate the revenue attributed to each unit.

5. **Determine Profit per Unit**: Subtract the cost per unit from the revenue per unit.

   ```
   Profit per Unit = Revenue per Unit - Cost per Unit
   ```

### Example Calculation

Let's consider a hypothetical customer service AI chatbot:

- Monthly LLM API costs: $10,000
- Indirect and operational costs: $5,000
- Total monthly interactions: 100,000

```
Cost per Interaction = ($10,000 + $5,000) / 100,000 = $0.15
```

If each interaction generates an average of $0.50 in value (through cost savings or revenue):

```
Profit per Interaction = $0.50 - $0.15 = $0.35
```

### Economies of Scale

As usage increases, unit economics often improve due to:

- Volume discounts from LLM providers
- Amortization of fixed costs over more units
- Efficiency gains through learning and optimization

However, it's crucial to model how these economies of scale manifest in your specific use case, as they may plateau or even reverse at very high volumes due to increased complexity and support needs.

### Diseconomies of Scale

Conversely, be aware of potential diseconomies of scale:

- Increased complexity in managing large-scale deployments
- Higher costs for specialized talent as operations grow
- Potential for diminishing returns on very large language models

By thoroughly understanding these unit economics, executives can make more informed decisions about which LLM provider and pricing model best aligns with their business objectives and scale.

## 3. Profit Margins and Cost Structures

Understanding profit margins and cost structures is crucial for executives evaluating LLM integration. This section explores how different pricing models and operational strategies can impact overall profitability.

### Components of Profit Margin

1. **Gross Margin**: The difference between revenue and the direct costs of LLM usage.
   ```
   Gross Margin = Revenue - Direct LLM Costs
   Gross Margin % = (Gross Margin / Revenue) * 100
   ```

2. **Contribution Margin**: Gross margin minus variable operational costs.
   ```
   Contribution Margin = Gross Margin - Variable Operational Costs
   ```

3. **Net Margin**: The final profit after all costs, including fixed overheads.
   ```
   Net Margin = Contribution Margin - Fixed Costs
   Net Margin % = (Net Margin / Revenue) * 100
   ```

### Cost Structures in LLM Deployment

1. **Fixed Costs**
   - Subscription fees for LLM access (if using a subscription model)
   - Base infrastructure costs
   - Core team salaries
   - Licensing fees for essential software

2. **Variable Costs**
   - Per-token or per-request charges
   - Scaling infrastructure costs
   - Usage-based API fees
   - Performance-based team bonuses

3. **Step Costs**
   - Costs that increase in chunks as usage scales
   - Examples: Adding new server clusters, hiring additional support staff

### Analyzing Profit Margins Across Different Pricing Models

Let's compare how different LLM pricing models might affect profit margins for a hypothetical AI-powered writing assistant service:

**Scenario**: The service charges users $20/month and expects to process an average of 100,000 tokens per user per month.

1. **Pay-per-Token Model**
   - LLM cost: $0.06 per 1,000 tokens
   - Monthly LLM cost per user: $6
   - Gross margin per user: $14 (70%)

2. **Subscription Model**
   - Fixed monthly fee: $5,000 for up to 10 million tokens
   - At 1,000 users: $5 per user
   - Gross margin per user: $15 (75%)

3. **Hybrid Model**
   - Base fee: $2,000 per month
   - Reduced per-token rate: $0.04 per 1,000 tokens
   - Monthly LLM cost per user: $6 ($2 base + $4 usage)
   - Gross margin per user: $14 (70%)

### Strategies for Improving Profit Margins

1. **Optimize Token Usage**
   - Implement efficient prompting techniques
   - Cache common responses
   - Use compression algorithms for inputs and outputs

2. **Leverage Economies of Scale**
   - Negotiate better rates at higher volumes
   - Spread fixed costs across a larger user base

3. **Implement Tiered Pricing**
   - Offer different service levels to capture more value from power users
   - Example: Basic ($10/month, 50K tokens), Pro ($30/month, 200K tokens)

4. **Vertical Integration**
   - Invest in proprietary LLM development for core functionalities
   - Reduce dependency on third-party providers for critical operations

5. **Smart Caching and Pre-computation**
   - Store and reuse common LLM outputs
   - Perform batch processing during off-peak hours

6. **Hybrid Cloud Strategies**
   - Use on-premises solutions for consistent workloads
   - Leverage cloud elasticity for demand spikes

### Case Study: Margin Improvement

Consider a company that initially used a pay-per-token model:

**Initial State:**
- Revenue per user: $20
- LLM cost per user: $6
- Other variable costs: $4
- Fixed costs per user: $5
- Net margin per user: $5 (25%)

**After Optimization:**
- Implemented efficient prompting: Reduced token usage by 20%
- Negotiated volume discount: 10% reduction in per-token price
- Introduced tiered pricing: Average revenue per user increased to $25
- Optimized operations: Reduced other variable costs to $3

**Result:**
- New LLM cost per user: $4.32
- New net margin per user: $12.68 (50.7%)

This case study demonstrates how a holistic approach to margin improvement, addressing both revenue and various cost components, can significantly enhance profitability.

Understanding these profit margin dynamics and cost structures is essential for executives to make informed decisions about LLM integration and to continuously optimize their AI-powered services for maximum profitability.

## 4. LLM Pricing in Action: Case Studies

To provide a concrete understanding of how LLM pricing models work in real-world scenarios, let's examine several case studies across different industries and use cases. These examples will illustrate the interplay between pricing models, usage patterns, and business outcomes.

### Case Study 1: E-commerce Product Description Generator

**Company**: GlobalMart, a large online retailer
**Use Case**: Automated generation of product descriptions
**LLM Provider**: GPT-4o

**Pricing Model**: Pay-per-token
- Input: $5.00 per 1M tokens
- Output: $15.00 per 1M tokens

**Usage Pattern**:
- Average input: 50 tokens per product (product attributes)
- Average output: 200 tokens per product (generated description)
- Daily products processed: 10,000

**Daily Cost Calculation**:
1. Input cost: (50 tokens * 10,000 products) / 1M * $5.00 = $2.50
2. Output cost: (200 tokens * 10,000 products) / 1M * $15.00 = $30.00
3. Total daily cost: $32.50

**Business Impact**:
- Reduced time to market for new products by 70%
- Improved SEO performance due to unique, keyword-rich descriptions
- Estimated daily value generated: $500 (based on increased sales and efficiency)

**ROI Analysis**:
- Daily investment: $32.50
- Daily return: $500
- ROI = (Return - Investment) / Investment * 100 = 1,438%

**Key Takeaway**: The pay-per-token model works well for this use case due to the predictable and moderate token usage per task. The high ROI justifies the investment in a more advanced model like GPT-4o.

### Case Study 2: Customer Service Chatbot

**Company**: TechSupport Inc., a software company
**Use Case**: 24/7 customer support chatbot
**LLM Provider**: Claude 3.5 Sonnet

**Pricing Model**: Input: $3 per 1M tokens, Output: $15 per 1M tokens

**Usage Pattern**:
- Average conversation: 500 tokens input (customer queries + context), 1000 tokens output (bot responses)
- Daily conversations: 5,000

**Daily Cost Calculation**:
1. Input cost: (500 tokens * 5,000 conversations) / 1M * $3 = $7.50
2. Output cost: (1000 tokens * 5,000 conversations) / 1M * $15 = $75.00
3. Total daily cost: $82.50

**Business Impact**:
- Reduced customer wait times by 90%
- Resolved 70% of queries without human intervention
- Estimated daily cost savings: $2,000 (based on reduced human support hours)

**ROI Analysis**:
- Daily investment: $82.50
- Daily return: $2,000
- ROI = (Return - Investment) / Investment * 100 = 2,324%

**Key Takeaway**: The higher cost of Claude 3.5 Sonnet is justified by its superior performance in handling complex customer queries, resulting in significant cost savings and improved customer satisfaction.

### Case Study 3: Financial Report Summarization

**Company**: FinAnalyze, a financial services firm
**Use Case**: Automated summarization of lengthy financial reports
**LLM Provider**: GPT-3.5 Turbo

**Pricing Model**: Input: $0.50 per 1M tokens, Output: $1.50 per 1M tokens

**Usage Pattern**:
- Average report: 20,000 tokens input, 2,000 tokens output
- Daily reports processed: 100

**Daily Cost Calculation**:
1. Input cost: (20,000 tokens * 100 reports) / 1M * $0.50 = $100
2. Output cost: (2,000 tokens * 100 reports) / 1M * $1.50 = $30
3. Total daily cost: $130

**Business Impact**:
- Reduced analysis time by 80%
- Improved consistency in report summaries
- Enabled analysts to focus on high-value tasks
- Estimated daily value generated: $1,000 (based on time savings and improved decision-making)

**ROI Analysis**:
- Daily investment: $130
- Daily return: $1,000
- ROI = (Return - Investment) / Investment * 100 = 669%

**Key Takeaway**: The lower cost of GPT-3.5 Turbo is suitable for this task, which requires processing large volumes of text but doesn't necessarily need the most advanced language understanding. The high input token count makes the input pricing a significant factor in model selection.

### Case Study 4: AI-Powered Language Learning App

**Company**: LinguaLeap, an edtech startup
**Use Case**: Personalized language exercises and conversations
**LLM Provider**: Claude 3 Haiku

**Pricing Model**: Input: $0.25 per 1M tokens, Output: $1.25 per 1M tokens

**Usage Pattern**:
- Average session: 300 tokens input (user responses + context), 500 tokens output (exercises + feedback)
- Daily active users: 50,000
- Average sessions per user per day: 3

**Daily Cost Calculation**:
1. Input cost: (300 tokens * 3 sessions * 50,000 users) / 1M * $0.25 = $11.25
2. Output cost: (500 tokens * 3 sessions * 50,000 users) / 1M * $1.25 = $93.75
3. Total daily cost: $105

**Business Impact**:
- Increased user engagement by 40%
- Improved learning outcomes, leading to higher user retention
- Enabled scaling to new languages without proportional increase in human tutors
- Estimated daily revenue: $5,000 (based on subscription fees and in-app purchases)

**ROI Analysis**:
- Daily investment: $105
- Daily revenue: $5,000
- ROI = (Revenue - Investment) / Investment * 100 = 4,662%

**Key Takeaway**: The high-volume, relatively simple interactions in this use case make Claude 3 Haiku an excellent choice. Its low cost allows for frequent interactions without prohibitive expenses, which is crucial for an app relying on regular user engagement.

### Case Study 5: Legal Document Analysis

**Company**: LegalEagle LLP, a large law firm
**Use Case**: Contract review and risk assessment
**LLM Provider**: Claude 3 Opus

**Pricing Model**: Input: $15 per 1M tokens, Output: $75 per 1M tokens

**Usage Pattern**:
- Average contract: 10,000 tokens input, 3,000 tokens output (analysis and risk assessment)
- Daily contracts processed: 50

**Daily Cost Calculation**:
1. Input cost: (10,000 tokens * 50 contracts) / 1M * $15 = $7.50
2. Output cost: (3,000 tokens * 50 contracts) / 1M * $75 = $11.25
3. Total daily cost: $18.75

**Business Impact**:
- Reduced contract review time by 60%
- Improved accuracy in identifying potential risks
- Enabled handling of more complex cases
- Estimated daily value: $10,000 (based on time savings and improved risk management)

**ROI Analysis**:
- Daily investment: $18.75
- Daily value: $10,000
- ROI = (Value - Investment) / Investment * 100 = 53,233%

**Key Takeaway**: Despite the high cost per token, Claude 3 Opus's advanced capabilities justify its use in this high-stakes environment where accuracy and nuanced understanding are critical. The high value generated per task offsets the higher token costs.

These case studies demonstrate how different LLM providers and pricing models can be optimal for various use cases, depending on factors such as token volume, task complexity, and the value generated by the AI application. Executives should carefully consider these factors when selecting an LLM provider and pricing model for their specific needs.

## 5. Calculating ROI for LLM Integration

Calculating the Return on Investment (ROI) for LLM integration is crucial for executives to justify the expenditure and assess the business value of AI implementation. This section will guide you through the process of calculating ROI, considering both tangible and intangible benefits.

### The ROI Formula

The basic ROI formula is:

```
ROI = (Net Benefit / Cost of Investment) * 100
```

For LLM integration, we can expand this to:

```
ROI = ((Total Benefits - Total Costs) / Total Costs) * 100
```

### Identifying Benefits

1. **Direct Cost Savings**
   - Reduced labor costs
   - Decreased operational expenses
   - Lower error-related costs

2. **Revenue Increases**
   - New product offerings enabled by LLM
   - Improved customer acquisition and retention
   - Upselling and cross-selling opportunities

3. **Productivity Gains**
   - Time saved on repetitive tasks
   - Faster decision-making processes
   - Improved employee efficiency

4. **Quality Improvements**
   - Enhanced accuracy in outputs
   - Consistency in service delivery
   - Reduced error rates

5. **Strategic Advantages**
   - Market differentiation
   - Faster time-to-market for new offerings
   - Improved competitive positioning

### Calculating Costs

1. **Direct LLM Costs**
   - API usage fees
   - Subscription costs

2. **Infrastructure Costs**
   - Cloud computing resources
   - Data storage
   - Networking expenses

3. **Integration and Development Costs**
   - Initial setup and integration
   - Ongoing maintenance and updates
   - Custom feature development

4. **Training and Support**
   - Employee training programs
   - User support and documentation
   - Change management initiatives

5. **Compliance and Security**
   - Data privacy measures
   - Security audits and implementations
   - Regulatory compliance efforts

### Step-by-Step ROI Calculation

1. **Define the Time Period**: Determine the timeframe for your ROI calculation (e.g., 1 year, 3 years).

2. **Estimate Total Benefits**:
   - Quantify direct cost savings and revenue increases
   - Assign monetary values to productivity gains and quality improvements
   - Estimate the value of strategic advantages (this may be more subjective)

3. **Calculate Total Costs**:
   - Sum up all direct and indirect costs related to LLM integration

4. **Apply the ROI Formula**:
   ```
   ROI = ((Total Benefits - Total Costs) / Total Costs) * 100
   ```

5. **Consider Time Value of Money**: For longer-term projections, use Net Present Value (NPV) to account for the time value of money.

### Example ROI Calculation

Let's consider a hypothetical customer service chatbot implementation:

**Time Period**: 1 year

**Benefits**:
- Labor cost savings: $500,000
- Increased sales from improved customer satisfaction: $300,000
- Productivity gains from faster query resolution: $200,000

Total Benefits: $1,000,000

**Costs**:
- LLM API fees: $100,000
- Integration and development: $150,000
- Training and support: $50,000
- Infrastructure: $50,000

Total Costs: $350,000

**ROI Calculation**:
```
ROI = (($1,000,000 - $350,000) / $350,000) * 100 = 185.7%
```

This indicates a strong positive return on investment, with benefits outweighing costs by a significant margin.

### Considerations for Accurate ROI Calculation

1. **Be Conservative in Estimates**: It's better to underestimate benefits and overestimate costs to provide a more realistic view.

2. **Account for Ramp-Up Time**: Full benefits may not be realized immediately. Consider a phased approach in your calculations.

3. **Include Opportunity Costs**: Consider the potential returns if the investment were made elsewhere.

4. **Factor in Risk**: Adjust your ROI based on the likelihood of achieving projected benefits.

5. **Consider Non-Financial Benefits**: Some benefits, like improved employee satisfaction or enhanced brand perception, may not have direct financial equivalents but are still valuable.

6. **Perform Sensitivity Analysis**: Calculate ROI under different scenarios (best case, worst case, most likely) to understand the range of possible outcomes.

7. **Benchmark Against Alternatives**: Compare the ROI of LLM integration against other potential investments or solutions.

### Long-Term ROI Considerations

While initial ROI calculations are crucial for decision-making, it's important to consider long-term implications:

1. **Scalability**: How will ROI change as usage increases?
2. **Technological Advancements**: Will newer, more efficient models become available?
3. **Market Changes**: How might shifts in the competitive landscape affect the value proposition?
4. **Regulatory Environment**: Could future regulations impact the cost or feasibility of LLM use?

By thoroughly calculating and analyzing the ROI of LLM integration, executives can make data-driven decisions about AI investments and set realistic expectations for the value these technologies can bring to their organizations.

## 6. Comparative Analysis of Major LLM Providers

In this section, we'll compare the offerings of major LLM providers, focusing on their pricing structures, model capabilities, and unique selling points. This analysis will help executives understand the landscape and make informed decisions about which provider best suits their needs.

### OpenAI

**Models**: GPT-4o, GPT-3.5 Turbo

**Pricing Structure**:
- Pay-per-token model
- Different rates for input and output tokens
- Bulk discounts available for high-volume users

**Key Features**:
- State-of-the-art performance on a wide range of tasks
- Regular model updates and improvements
- Extensive documentation and community support

**Considerations**:
- Higher pricing compared to some competitors
- Potential for rapid price changes as technology evolves
- Usage limits and approval process for higher-tier models

### Anthropic

**Models**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku

**Pricing Structure**:
- Pay-per-token model
- Different rates for input and output tokens
- Tiered pricing based on model capabilities

**Key Features**:
- Strong focus on AI safety and ethics
- Long context windows (200K tokens)
- Specialized models for different use cases (e.g., Haiku for speed, Opus for complex tasks)

**Considerations**:
- Newer to the market compared to OpenAI
- Potentially more limited third-party integrations
- Strong emphasis on responsible AI use

### Google (Vertex AI)

**Models**: PaLM 2 for Chat, PaLM 2 for Text

**Pricing Structure**:
- Pay-per-thousand characters model
- Different rates for input and output
- Additional charges for advanced features (e.g., semantic retrieval)

**Key Features**:
- Integration with Google Cloud ecosystem
- Multi-modal capabilities (text, image, audio)
- Enterprise-grade security and compliance features

**Considerations**:
- Pricing can be complex due to additional Google Cloud costs
- Strong performance in specialized domains (e.g., coding, mathematical reasoning)
- Potential for integration with other Google services

### Amazon (Bedrock)

**Models**: Claude (Anthropic), Titan

**Pricing Structure**:
- Pay-per-second of compute time
- Additional charges for data transfer and storage

**Key Features**:
- Seamless integration with AWS services
- Access to multiple model providers through a single API
- Fine-tuning and customization options

**Considerations**:
- Pricing model can be less predictable for inconsistent workloads
- Strong appeal for existing AWS customers
- Potential for cost optimizations through AWS ecosystem

### Microsoft (Azure OpenAI Service)

**Models**: GPT-4, GPT-3.5 Turbo

**Pricing Structure**:
- Similar to OpenAI's pricing, but with Azure integration
- Additional costs for Azure services (e.g., storage, networking)

**Key Features**:
- Enterprise-grade security and compliance
- Integration with Azure AI services
- Access to fine-tuning and customization options

**Considerations**:
- Attractive for organizations already using Azure
- Potential for volume discounts through Microsoft Enterprise Agreements
- Additional overhead for Azure management

### Comparative Analysis

| Provider | Pricing Model | Strengths | Considerations |
|----------|---------------|-----------|----------------|
| OpenAI   | Pay-per-token | - Top performance<br>- Regular updates<br>- Strong community | - Higher costs<br>- Usage limits |
| Anthropic| Pay-per-token | - Ethical focus<br>- Long context<br>- Specialized models | - Newer provider<br>- Limited integrations |
| Google   | Pay-per-character | - Google Cloud integration<br>- Multi-modal<br>- Enterprise features | - Complex pricing<br>- Google ecosystem lock-in |
| Amazon   | Pay-per-compute time | - AWS integration<br>- Multiple providers<br>- Customization options | - Less predictable costs<br>- AWS ecosystem focus |
| Microsoft| Pay-per-token (Azure-based) | - Enterprise security<br>- Azure integration<br>- Fine-tuning options | - Azure overhead<br>- Potential lock-in |

### Factors to Consider in Provider Selection

1. **Performance Requirements**: Assess whether you need state-of-the-art performance or if a less advanced (and potentially cheaper) model suffices.

2. **Pricing Predictability**: Consider whether your usage patterns align better with token-based or compute-time-based pricing.

3. **Integration Needs**: Evaluate how well each provider integrates with your existing technology stack.

4. **Scalability**: Assess each provider's ability to handle your expected growth in usage.

5. **Customization Options**: Determine if you need fine-tuning or specialized model development capabilities.

6. **Compliance and Security**: Consider your industry-specific regulatory requirements and each provider's security offerings.

7. **Support and Documentation**: Evaluate the quality of documentation, community support, and enterprise-level assistance.

8. **Ethical Considerations**: Assess each provider's stance on AI ethics and responsible use.

9. **Lock-In Concerns**: Consider the long-term implications of committing to a specific provider or cloud ecosystem.

10. **Multi-Provider Strategy**: Evaluate the feasibility and benefits of using multiple providers for different use cases.

By carefully comparing these providers and considering the factors most relevant to your organization, you can make an informed decision that balances cost, performance, and strategic fit. Remember that the LLM landscape is rapidly evolving, so it's important to regularly reassess your choices and stay informed about new developments and pricing changes.

## 7. Hidden Costs and Considerations

When evaluating LLM providers and calculating the total cost of ownership, it's crucial to look beyond the advertised pricing and consider the hidden costs and additional factors that can significantly impact your budget and overall implementation success. This section explores these often-overlooked aspects to help executives make more comprehensive and accurate assessments.

### 1. Data Preparation and Cleaning

**Considerations**:
- Cost of data collection and aggregation
- Expenses related to data cleaning and normalization
- Ongoing data maintenance and updates

**Impact**:
- Can be time-consuming and labor-intensive
- May require specialized tools or personnel
- Critical for model performance and accuracy

### 2. Fine-Tuning and Customization

**Considerations**:
- Costs associated with creating custom datasets
- Compute resources required for fine-tuning
- Potential need for specialized ML expertise

**Impact**:
- Can significantly improve model performance for specific tasks
- May lead to better ROI in the long run
- Increases initial implementation costs

### 3. Integration and Development

**Considerations**:
- Engineering time for API integration
- Development of custom interfaces or applications
- Ongoing maintenance and updates

**Impact**:
- Can be substantial, especially for complex integrations
- May require hiring additional developers or consultants
- Critical for seamless user experience and workflow integration

### 4. Monitoring and Optimization

**Considerations**:
- Tools and systems for performance monitoring
- Regular audits and optimizations
- Costs associated with debugging and troubleshooting

**Impact**:
- Ongoing expense that increases with scale
- Essential for maintaining efficiency and cost-effectiveness
- Can lead to significant savings through optimized usage

### 5. Compliance and Security

**Considerations**:
- Legal counsel for data privacy and AI regulations
- Implementation of security measures (e.g., encryption, access controls)
- Regular audits and certifications

**Impact**:
- Can be substantial, especially in heavily regulated industries
- Critical for risk management and maintaining customer trust
- May limit certain use cases or require additional safeguards

### 6. Training and Change Management

- Employee training programs
- Development of user guides and documentation
- Change management initiatives

**Impact**:
- Often underestimated but crucial for adoption
- Can affect productivity during the transition period
- Important for realizing the full potential of LLM integration

### 7. Scaling Costs

**Considerations**:
- Potential price increases as usage grows
- Need for additional infrastructure or resources
- Costs associated with managing increased complexity

**Impact**:
- Can lead to unexpected expenses if not properly forecasted
- May require renegotiation of contracts or switching providers
- Important to consider in long-term planning

### 8. Opportunity Costs

**Considerations**:
- Time and resources diverted from other projects
- Potential missed opportunities due to focus on LLM implementation
- Learning curve and productivity dips during adoption

**Impact**:
- Difficult to quantify but important to consider
- Can affect overall business strategy and priorities
- May influence timing and scope of LLM integration

### 9. Vendor Lock-in

**Considerations**:
- Costs associated with switching providers
- Dependency on provider-specific features or integrations
- Potential for price increases once deeply integrated

**Impact**:
- Can limit flexibility and negotiating power
- May affect long-term costs and strategic decisions
- Important to consider multi-provider or portable implementation strategies

### 10. Ethical and Reputational Considerations

**Considerations**:
- Potential backlash from AI-related controversies
- Costs of ensuring ethical AI use and transparency
- Investments in responsible AI practices

**Impact**:
- Can affect brand reputation and customer trust
- May require ongoing public relations efforts
- Important for long-term sustainability and social responsibility

By carefully considering these hidden costs and factors, executives can develop a more comprehensive understanding of the total investment required for successful LLM integration. This holistic approach allows for better budgeting, risk management, and strategic planning.

## Conclusion: Navigating the LLM Pricing Landscape

As we've explored throughout this guide, the landscape of LLM provider pricing is complex and multifaceted. From understanding the basic pricing models to calculating ROI and considering hidden costs, there are numerous factors that executives must weigh when making decisions about AI integration.

Key takeaways include:

1. The importance of aligning LLM selection with specific business needs and use cases.
2. The need for thorough ROI analysis that goes beyond simple cost calculations.
3. The value of considering both short-term implementation costs and long-term scalability.
4. The critical role of hidden costs in determining the true total cost of ownership.
5. The potential for significant business value when LLMs are strategically implemented and optimized.

As the AI landscape continues to evolve rapidly, staying informed and adaptable is crucial. What may be the best choice today could change as new models are released, pricing structures shift, and your organization's needs evolve.

To help you navigate these complexities and make the most informed decisions for your enterprise, we invite you to take the next steps in your AI journey:

1. **Book a Consultation**: Speak with our enterprise-grade LLM specialists who can provide personalized insights and recommendations tailored to your specific needs. Schedule a 15-minute call at [https://cal.com/swarms/15min](https://cal.com/swarms/15min).

2. **Join Our Community**: Connect with fellow AI executives, share experiences, and stay updated on the latest developments in the LLM space. Join our Discord community at [https://discord.gg/yxU9t9da](https://discord.gg/yxU9t9da).

By leveraging expert guidance and peer insights, you can position your organization to make the most of LLM technologies while optimizing costs and maximizing value. The future of AI in enterprise is bright, and with the right approach, your organization can be at the forefront of this transformative technology.

--------------------------------------------------

# File: index.md

# Welcome to Swarms Docs Home

[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/EamjgSaEQf) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/swarms_corp)

## What is Swarms?

**Swarms** is the **first and most reliable multi-agent production-grade framework** designed to orchestrate intelligent AI agents at scale. Built for enterprise applications, Swarms enables you to create sophisticated multi-agent systems that can handle complex tasks through collaboration, parallel processing, and intelligent task distribution.

### Key Capabilities

- **🏢 Production-Ready**: Enterprise-grade infrastructure with high reliability, comprehensive logging, and robust error handling
- **🤖 Multi-Agent Orchestration**: Support for hierarchical swarms, parallel processing, sequential workflows, and dynamic agent rearrangement
- **🔄 Flexible Integration**: Multi-model support, custom agent creation, extensive tool library, and multiple memory systems
- **📈 Scalable Architecture**: Concurrent processing, resource management, load balancing, and horizontal scaling capabilities
- **🛠️ Developer-Friendly**: Simple API, extensive documentation, active community, and CLI tools for rapid development
- **🔐 Enterprise Security**: Built-in error handling, rate limiting, monitoring integration, and audit logging

### Why Choose Swarms?

Swarms stands out as the **most reliable multi-agent framework** because it was built from the ground up for production environments. Unlike other frameworks that focus on research or simple demos, Swarms provides the infrastructure, tooling, and best practices needed to deploy multi-agent systems in real-world applications.

Whether you're building financial analysis systems, healthcare diagnostics, manufacturing optimization, or any other complex multi-agent application, Swarms provides the foundation you need to succeed.

## Swarms Installation

```bash
pip3 install swarms
```

## Update Swarms


```bash
pip3 install -U swarms
```

### **Get Started Building Production-Grade Multi-Agent Applications**

## Onboarding

| Section              | Links                                                                                      |
|----------------------|--------------------------------------------------------------------------------------------|
| Installation    | [Installation](https://docs.swarms.world/en/latest/swarms/install/install/)                                                            |
| Quickstart | [Get Started](https://docs.swarms.world/en/latest/swarms/install/quickstart/)                                                 |
| Environment Setup | [Environment Configuration](https://docs.swarms.world/en/latest/swarms/install/workspace_manager/)                                                 |
| Environment Variables | [Environment Variables](https://docs.swarms.world/en/latest/swarms/install/env/)                                                 |
| Swarms CLI | [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/)                                                 |
| Agent Internal Mechanisms | [Agent Architecture](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/)                                                 |
| Agent API | [Agent API](https://docs.swarms.world/en/latest/swarms/structs/agent/)                                                 |
| Managing Prompts in Production | [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/)                                                 |
| Integrating External Agents | [External Agents Integration](https://docs.swarms.world/en/latest/swarms/agents/external_party_agents/)                                                 |
| Creating Agents from YAML | [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/agents/create_agents_yaml/)                                                 |
| Why You Need Swarms | [Why MultiAgent Collaboration](https://docs.swarms.world/en/latest/swarms/concept/why/)                                                 |
| Swarm Architectures Analysis | [Swarm Architectures](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/)                                                 |
| Choosing the Right Swarm | [How to Choose Swarms](https://docs.swarms.world/en/latest/swarms/concept/how_to_choose_swarms/)                                                 |
| Full API Reference | [API Reference](https://docs.swarms.world/en/latest/swarms/framework/reference/)                                                 |
| AgentRearrange Docs | [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)                                                 |


## Ecosystem

Here you'll find references about the Swarms framework, marketplace, community, and more to enable you to build your multi-agent applications.

| Section              | Links                                                                                      |
|----------------------|--------------------------------------------------------------------------------------------|
| Swarms Python Framework Docs     | [Framework Docs](https://docs.swarms.world/en/latest/swarms/install/install/)                                                            |
| Swarms Cloud API     | [Cloud API](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/)                                                            |
| Swarms Marketplace API     | [Marketplace API](https://docs.swarms.world/en/latest/swarms_platform/)                                                            |
| Swarms Memory Systems     | [Memory Systems](https://docs.swarms.world/en/latest/swarms_memory/)                                                            |
| Available Models     | [Models Overview](https://docs.swarms.world/en/latest/swarms/models/)                                                            |
| Swarms Tools     | [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/)                                                            |
| Example Applications     | [Examples](https://docs.swarms.world/en/latest/swarms/examples)                                                            |
| Swarms Corp Github     | [Swarms Corp GitHub](https://github.com/The-Swarm-Corporation)                      |


## Join the Swarms Community

| Platform | Link | Description |
|----------|------|-------------|
| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides |
| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles |
| 💬 Discord | [Join Discord](https://discord.gg/EamjgSaEQf) | Live chat and community support |
| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements |
| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates |
| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos |
| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events |

## Get Support

Want to get in touch with the Swarms team? Open an issue on [GitHub](https://github.com/kyegomez/swarms/issues/new) or reach out to us via [email](mailto:kye@swarms.world). We're here to help!



--------------------------------------------------

# File: protocol/overview.md

# Swarms Protocol Overview & Architecture

This document provides a comprehensive overview of the Swarms protocol architecture, illustrating the flow from agent classes to multi-agent structures, and showcasing the main components and folders within the `swarms/` package. The Swarms framework is designed for extensibility, modularity, and production-readiness, enabling the orchestration of intelligent agents, tools, memory, and complex multi-agent systems.

---

## Introduction

Swarms is an enterprise-grade, production-ready multi-agent orchestration framework. It enables developers and organizations to build, deploy, and manage intelligent agents that can reason, collaborate, and solve complex tasks autonomously or in groups. The architecture is inspired by the principles of modularity, composability, and scalability, ensuring that each component can be extended or replaced as needed.

The protocol is structured to support a wide range of use cases, from simple single-agent automations to sophisticated multi-agent workflows involving memory, tool use, and advanced reasoning.

For a high-level introduction and installation instructions, see the [Swarms Docs Home](https://docs.swarms.world/en/latest/).

---

## High-Level Architecture Flow

The Swarms protocol is organized into several key layers, each responsible for a specific aspect of the system. The typical flow is as follows:

1. **Agent Class (`swarms/agents`)**
    
    - The core building block of the framework. Agents encapsulate logic, state, and behavior. They can be simple (stateless) or complex 
    (stateful, with memory and reasoning capabilities).
    
    - Agents can be specialized for different tasks (e.g., reasoning agents, tool agents, judge agents, etc.).
    
    - Example: A `ReasoningAgent` that can analyze data and make decisions, or a `ToolAgent` that wraps external APIs.
    
    - [Quickstart for Agents](https://docs.swarms.world/en/latest/swarms/agents/)
    
    - [Agent API Reference](https://docs.swarms.world/en/latest/swarms/structs/agent/)

2. **Tools with Memory (`swarms/tools`, `swarms/utils`)**
    - Tools are modular components that agents use to interact with the outside world, perform computations, or access resources (APIs, 
    databases, files, etc.).

    - Memory modules and utility functions allow agents to retain context, cache results, and manage state across interactions.
    
    - Example: A tool for calling an LLM API, a memory cache for conversation history, or a utility for parsing and formatting data.
    
    - [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/)
    
    - [BaseTool Reference](https://docs.swarms.world/en/latest/swarms/tools/base_tool/)

3. **Reasoning & Specialized Agents (`swarms/agents`)**
    - These agents build on the base agent class, adding advanced reasoning, self-consistency, and specialized logic for tasks like 
    planning, evaluation, or multi-step workflows.

    - Includes agents for self-reflection, iterative improvement, and domain-specific expertise.

    - Example: A `SelfConsistencyAgent` that aggregates multiple reasoning paths, or a `JudgeAgent` that evaluates outputs from other 
    agents.

    - [Reasoning Agents Overview](https://docs.swarms.world/en/latest/swarms/agents/reasoning_agents_overview/)
    
    - [Self Consistency Agent](https://docs.swarms.world/en/latest/swarms/agents/consistency_agent/)
    
    - [Agent Judge](https://docs.swarms.world/en/latest/swarms/agents/agent_judge/)

4. **Multi-Agent Structures (`swarms/structs`)**
    - Agents are composed into higher-order structures for collaboration, voting, parallelism, and workflow orchestration.

    - Includes swarms for majority voting, round-robin execution, hierarchical delegation, and more.

    - Example: A `MajorityVotingSwarm` that aggregates outputs from several agents, or a `HierarchicalSwarm` that delegates tasks to 
    sub-agents.

    - [Multi-Agent Architectures Overview](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/)
    
    - [MajorityVotingSwarm](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/)
    
    - [HierarchicalSwarm](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)
    
    - [Sequential Workflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)
    
    - [Concurrent Workflow](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/)

5. **Supporting Components**

    - **Communication (`swarms/communication`)**: Provides wrappers for inter-agent communication, database access, message passing, and 
    integration with external systems (e.g., Redis, DuckDB, Pulsar). See [Communication Structure](https://docs.swarms.world/en/latest/swarms/structs/conversation/)
    
    - **Artifacts (`swarms/artifacts`)**: Manages the creation, storage, and retrieval of artifacts (outputs, files, logs) generated by 
    agents and swarms.
    
    - **Prompts (`swarms/prompts`)**: Houses prompt templates, system prompts, and agent-specific prompts for LLM-based agents. See 
    [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/)
    
    - **Telemetry (`swarms/telemetry`)**: Handles logging, monitoring, and bootup routines for observability and debugging.
    
    - **Schemas (`swarms/schemas`)**: Defines data schemas for agents, tools, completions, and communication protocols, ensuring type 
    safety and consistency.
    
    - **CLI (`swarms/cli`)**: Provides command-line utilities for agent creation, management, and orchestration. See [CLI Documentation]
    (https://docs.swarms.world/en/latest/swarms/cli/main/)

---

## Proposing Large Improvements or Enhancements: Swarms Improvement Proposals (SIPs)

For significant changes, new agent architectures, or radical new features, Swarms uses a formal process called **Swarms Improvement Proposals (SIPs)**. SIPs are design documents that describe new features, enhancements, or changes to the Swarms framework. They ensure that major changes are well-documented, discussed, and reviewed by the community before implementation.

**When to use a SIP:**

- Proposing new agent types, swarm patterns, or coordination mechanisms

- Core framework changes or breaking changes

- New integrations (LLM providers, tools, external services)

- Any complex or multi-component feature

**SIP Process Overview:**

1. Discuss your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions)

2. Submit a SIP as a GitHub Issue using the SIP template

3. Engage with the community and iterate on your proposal

4. Undergo review and, if accepted, proceed to implementation

**Learn more:** See the full [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/)

---

## Detailed Architecture Diagram

The following Mermaid diagram visualizes the protocol flow and the relationship between the main folders in the `swarms/` package:

```mermaid
flowchart TD
    A["Agent Class<br/>(swarms/agents)"] --> B["Tools with Memory<br/>(swarms/tools, swarms/utils)"]
    B --> C["Reasoning & Specialized Agents<br/>(swarms/agents)"]
    C --> D["Multi-Agent Structures<br/>(swarms/structs)"]
    D --> E["Communication, Artifacts, Prompts, Telemetry, Schemas, CLI"]
    
    subgraph Folders
        A1["agents"]
        A2["tools"]
        A3["structs"]
        A4["utils"]
        A5["telemetry"]
        A6["schemas"]
        A7["prompts"]
        A8["artifacts"]
        A9["communication"]
        A10["cli"]
    end
    
    %% Folder showcase
    subgraph "swarms/"
        A1
        A2
        A3
        A4
        A5
        A6
        A7
        A8
        A9
        A10
    end
    
    %% Connect folder showcase to main flow
    A1 -.-> A
    A2 -.-> B
    A3 -.-> D
    A4 -.-> B
    A5 -.-> E
    A6 -.-> E
    A7 -.-> E
    A8 -.-> E
    A9 -.-> E
    A10 -.-> E
```

---

## Folder-by-Folder Breakdown

### `agents/`

**Purpose:** Defines all agent classes, including base agents, reasoning agents, tool agents, judge agents, and more.

**Highlights:**

- Modular agent design for extensibility.

- Support for YAML-based agent creation and configuration. See [YAML Agent Creation](https://docs.swarms.world/en/latest/swarms/
agents/create_agents_yaml/)

- Specialized agents for self-consistency, evaluation, and domain-specific tasks.

- **Example:**

- `ReasoningAgent`, `ToolAgent`, `JudgeAgent`, `ConsistencyAgent`, `OpenAIAssistant`, etc.

- [Agents Overview](https://docs.swarms.world/en/latest/swarms/framework/agents_explained/)


### `tools/`

**Purpose:** Houses all tool-related logic, including tool registry, function calling, tool schemas, and integration with external 
APIs.

**Highlights:**

- Tools can be dynamically registered and called by agents.

- Support for OpenAI function calling, Cohere, and custom tool schemas.

- Utilities for parsing, formatting, and executing tool calls.

- **Example:**

- `base_tool.py`, `tool_registry.py`, `mcp_client_call.py`, `func_calling_utils.py`, etc.

- [Tools Reference](https://docs.swarms.world/en/latest/swarms/tools/tools_examples/)

- [What are tools?](https://docs.swarms.world/en/latest/swarms/tools/build_tool/)


### `structs/`
**Purpose:** Implements multi-agent structures, workflows, routers, registries, and orchestration logic.

**Highlights:**

- Swarms for majority voting, round-robin, hierarchical delegation, spreadsheet processing, and more.

- Workflow orchestration (sequential, concurrent, graph-based).

- Utilities for agent matching, rearrangement, and evaluation.

- **Example:**

- `MajorityVotingSwarm`, `HierarchicalSwarm`, `SwarmRouter`, `SequentialWorkflow`, `ConcurrentWorkflow`, etc.

- [Custom Multi Agent Architectures](https://docs.swarms.world/en/latest/swarms/structs/custom_swarm/)

- [SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)

- [AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)


### `utils/`

**Purpose:** Provides utility functions, memory management, caching, wrappers, and helpers used throughout the framework.

**Highlights:**

- Memory and caching for agents and tools. See [Integrating RAG with Agents](https://docs.swarms.world/en/latest/swarms/memory/
diy_memory/)

- Wrappers for concurrency, logging, and data processing.

- General-purpose utilities for string, file, and data manipulation.

**Example:**

- `agent_cache.py`, `concurrent_wrapper.py`, `file_processing.py`, `formatter.py`, etc.


### `telemetry/`

**Purpose:** Handles telemetry, logging, monitoring, and bootup routines for the framework.

**Highlights:**

- Centralized logging and execution tracking.

- Bootup routines for initializing the framework.

- Utilities for monitoring agent and swarm performance.

- **Example:**

- `bootup.py`, `log_executions.py`, `main.py`.


### `schemas/`

**Purpose:** Defines data schemas for agents, tools, completions, and communication protocols.

**Highlights:**

- Ensures type safety and consistency across the framework.

- Pydantic-based schemas for validation and serialization.

- Schemas for agent classes, tool calls, completions, and more.

**Example:**

- `agent_class_schema.py`, `tool_schema_base_model.py`, `agent_completion_response.py`, etc.


### `prompts/`

**Purpose:** Contains prompt templates, system prompts, and agent-specific prompts for LLM-based agents.

**Highlights:**

- Modular prompt design for easy customization.

- Support for multi-modal, collaborative, and domain-specific prompts.

- Templates for system, task, and conversational prompts.

**Example:**

- `prompt.py`, `reasoning_prompt.py`, `multi_agent_collab_prompt.py`, etc.

- [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/)


### `artifacts/`

**Purpose:** Manages the creation, storage, and retrieval of artifacts (outputs, files, logs) generated by agents and swarms.

**Highlights:**

- Artifact management for reproducibility and traceability.
- Support for various output types and formats.

**Example:**

- `main_artifact.py`.


### `communication/`

**Purpose:** Provides wrappers for inter-agent communication, database access, message passing, and integration with external systems.

**Highlights:**

- Support for Redis, DuckDB, Pulsar, Supabase, and more.
- Abstractions for message passing and data exchange between agents.

**Example:**

- `redis_wrap.py`, `duckdb_wrap.py`, `base_communication.py`, etc.

- [Communication Structure](https://docs.swarms.world/en/latest/swarms/structs/conversation/)


### `cli/`

**Purpose:** Command-line utilities for agent creation, management, and orchestration.

**Highlights:**

- Scripts for onboarding, agent creation, and management.

- CLI entry points for interacting with the framework.

**Example:**

- `main.py`, `create_agent.py`, `onboarding_process.py`.

- [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/)


---

## How the System Works Together

The Swarms protocol is designed for composability. Agents can be created and configured independently, then composed into larger structures (swarms) for collaborative or competitive workflows. Tools and memory modules are injected into agents as needed, enabling them to perform complex tasks and retain context. Multi-agent structures orchestrate the flow of information and decision-making, while supporting components (communication, telemetry, artifacts, etc.) ensure robustness, observability, and extensibility.

For example, a typical workflow might involve:

- Creating a set of specialized agents (e.g., data analyst, summarizer, judge).

- Registering tools (e.g., LLM API, database access, web search) and memory modules.

- Composing agents into a `MajorityVotingSwarm` for collaborative decision-making.

- Using communication wrappers to exchange data between agents and external systems.

- Logging all actions and outputs for traceability and debugging.


For more advanced examples, see the [Examples Overview](https://docs.swarms.world/en/latest/examples/index/).

---

## Swarms Framework Philosophy

Swarms is built on the following principles:

- **Modularity:** Every component (agent, tool, prompt, schema) is a module that can be extended or replaced.

- **Composability:** Agents and tools can be composed into larger structures for complex workflows.

- **Observability:** Telemetry and artifact management ensure that all actions are traceable and debuggable.

- **Extensibility:** New agents, tools, and workflows can be added with minimal friction.

- **Production-Readiness:** The framework is designed for reliability, scalability, and real-world deployment.


For more on the philosophy and architecture, see [Development Philosophy & Principles](https://docs.swarms.world/en/latest/swarms/concept/philosophy/) and [Understanding Swarms Architecture](https://docs.swarms.world/en/latest/swarms/concept/framework_architecture/).

---

## Further Reading & References

| Resource Name                        | Link                                                                                   | Description                                      |
|-------------------------------------- |----------------------------------------------------------------------------------------|--------------------------------------------------|
| Swarms Docs Home                     | [Swarms Docs Home](https://docs.swarms.world/en/latest/)                               | Main documentation homepage                      |
| Quickstart for Agents                | [Quickstart for Agents](https://docs.swarms.world/en/latest/swarms/agents/)            | Getting started with Swarms agents               |
| Agent API Reference                  | [Agent API Reference](https://docs.swarms.world/en/latest/swarms/structs/agent/)       | API reference for Agent class                    |
| Tools Overview                       | [Tools Overview](https://docs.swarms.world/en/latest/swarms_tools/overview/)           | Overview of available tools                      |
| BaseTool Reference                   | [BaseTool Reference](https://docs.swarms.world/en/latest/swarms/tools/base_tool/)      | Reference for the BaseTool class                 |
| Reasoning Agents Overview            | [Reasoning Agents Overview](https://docs.swarms.world/en/latest/swarms/agents/reasoning_agents_overview/) | Overview of reasoning agents                     |
| Multi-Agent Architectures Overview   | [Multi-Agent Architectures Overview](https://docs.swarms.world/en/latest/swarms/concept/swarm_architectures/) | Multi-agent system architectures                 |
| Examples Overview                    | [Examples Overview](https://docs.swarms.world/en/latest/examples/index/)               | Example projects and use cases                   |
| CLI Documentation                    | [CLI Documentation](https://docs.swarms.world/en/latest/swarms/cli/main/)              | Command-line interface documentation             |
| Prompts Management                   | [Prompts Management](https://docs.swarms.world/en/latest/swarms/prompts/main/)         | Managing and customizing prompts                 |
| Development Philosophy & Principles  | [Development Philosophy & Principles](https://docs.swarms.world/en/latest/swarms/concept/philosophy/) | Framework philosophy and guiding principles      |
| Understanding Swarms Architecture    | [Understanding Swarms Architecture](https://docs.swarms.world/en/latest/swarms/concept/framework_architecture/) | In-depth look at Swarms architecture             |
| SIP Guidelines and Template          | [SIP Guidelines and Template](https://docs.swarms.world/en/latest/protocol/sip/)       | Swarms Improvement Proposal process and template |

# Conclusion

The Swarms protocol provides a robust foundation for building intelligent, collaborative, and autonomous systems. By organizing the codebase into clear, modular folders and defining a logical flow from agents to multi-agent structures, Swarms enables rapid development and deployment of advanced AI solutions. Whether you are building a simple automation or a complex multi-agent application, the Swarms architecture provides the tools and abstractions you need to succeed.



--------------------------------------------------

# File: protocol/sip.md

# Swarms Improvement Proposal (SIP) Guidelines

A simplified process for proposing new functionality and enhancements to the Swarms framework.

## What is a SIP?

A **Swarms Improvement Proposal (SIP)** is a design document that describes a new feature, enhancement, or change to the Swarms framework. SIPs serve as the primary mechanism for proposing significant changes, collecting community feedback, and documenting design decisions.

The SIP author is responsible for building consensus within the community and documenting the proposal clearly and concisely.

## When to Submit a SIP

Consider submitting a SIP for:

- **New Agent Types or Behaviors**: Adding new agent architectures, swarm patterns, or coordination mechanisms
- **Core Framework Changes**: Modifications to the Swarms API, core classes, or fundamental behaviors
- **New Integrations**: Adding support for new LLM providers, tools, or external services
- **Breaking Changes**: Any change that affects backward compatibility
- **Complex Features**: Multi-component features that require community discussion and design review

For simple bug fixes, minor enhancements, or straightforward additions, use regular GitHub issues and pull requests instead.

## SIP Types

**Standard SIP**: Describes a new feature or change to the Swarms framework
**Process SIP**: Describes changes to development processes, governance, or community guidelines
**Informational SIP**: Provides information or guidelines to the community without proposing changes

## Submitting a SIP

1. **Discuss First**: Post your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) to gauge community interest
2. **Create Issue**: Submit your SIP as a GitHub Issue with the `SIP` and `proposal` labels
3. **Follow Format**: Use the SIP template format below
4. **Engage Community**: Respond to feedback and iterate on your proposal

## SIP Format

### Required Sections

#### **SIP Header**
```
Title: [Descriptive title]
Author: [Your name and contact]
Type: [Standard/Process/Informational]
Status: Proposal
Created: [Date]
```

#### **Abstract** (200 words max)
A brief summary of what you're proposing and why.

#### **Motivation**
- What problem does this solve?
- Why can't the current framework handle this?
- What are the benefits to the Swarms ecosystem?

#### **Specification**
- Detailed technical description
- API changes or new interfaces
- Code examples showing usage
- Integration points with existing framework

#### **Implementation Plan**
- High-level implementation approach
- Breaking changes (if any)
- Migration path for existing users
- Testing strategy

#### **Alternatives Considered**
- Other approaches you evaluated
- Why you chose this solution
- Trade-offs and limitations

### Optional Sections

#### **Reference Implementation**
Link to prototype code or proof-of-concept (can be added later)

#### **Security Considerations**
Any security implications or requirements

## SIP Workflow

```
Proposal → Draft → Review → Accepted/Rejected → Final
```

1. **Proposal**: Initial submission as GitHub Issue
2. **Draft**: Maintainer assigns SIP number and `draft` label
3. **Review**: Community and maintainer review period
4. **Decision**: Accepted, rejected, or needs revision
5. **Final**: Implementation completed and merged

## SIP Status

- **Proposal**: Newly submitted, awaiting initial review
- **Draft**: Under active discussion and refinement
- **Review**: Formal review by maintainers
- **Accepted**: Approved for implementation
- **Rejected**: Not accepted (with reasons)
- **Final**: Implementation completed and merged
- **Withdrawn**: Author withdrew the proposal

## Review Process

- SIPs are reviewed during regular maintainer meetings
- Community feedback is collected via GitHub comments
- Acceptance requires:
  - Clear benefit to the Swarms ecosystem
  - Technical feasibility
  - Community support
  - Working prototype (for complex features)

## Getting Help

- **Discussions**: Use [GitHub Discussions](https://github.com/kyegomez/swarms/discussions) for questions
- **Documentation**: Check [docs.swarms.world](https://docs.swarms.world) for framework details
- **Examples**: Look at existing SIPs for reference

## SIP Template

When creating your SIP, copy this template:

```markdown
# SIP-XXX: [Title]

**Author**: [Your name] <[email]>
**Type**: Standard
**Status**: Proposal
**Created**: [Date]

## Abstract

[Brief 200-word summary]

## Motivation

[Why is this needed? What problem does it solve?]

## Specification

[Detailed technical description with code examples]

## Implementation Plan

[How will this be built? Any breaking changes?]

## Alternatives Considered

[Other approaches and why you chose this one]

## Reference Implementation

[Link to prototype code if available]
```

---

**Note**: This process is designed to be lightweight while ensuring important changes get proper community review. For questions about whether your idea needs a SIP, start a discussion in the GitHub Discussions forum.

--------------------------------------------------

# File: quickstart.md


# Welcome to Swarms Docs Home

[![Join our Discord](https://img.shields.io/badge/Discord-Join%20our%20server-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/EamjgSaEQf) [![Subscribe on YouTube](https://img.shields.io/badge/YouTube-Subscribe-red?style=for-the-badge&logo=youtube&logoColor=white)](https://www.youtube.com/@kyegomez3242) [![Connect on LinkedIn](https://img.shields.io/badge/LinkedIn-Connect-blue?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/kye-g-38759a207/) [![Follow on X.com](https://img.shields.io/badge/X.com-Follow-1DA1F2?style=for-the-badge&logo=x&logoColor=white)](https://x.com/swarms_corp)

## What is Swarms?

**Swarms** is the **first and most reliable multi-agent production-grade framework** designed to orchestrate intelligent AI agents at scale. Built for enterprise applications, Swarms enables you to create sophisticated multi-agent systems that can handle complex tasks through collaboration, parallel processing, and intelligent task distribution.

### Key Capabilities

- **🏢 Production-Ready**: Enterprise-grade infrastructure with high reliability, comprehensive logging, and robust error handling
- **🤖 Multi-Agent Orchestration**: Support for hierarchical swarms, parallel processing, sequential workflows, and dynamic agent rearrangement
- **🔄 Flexible Integration**: Multi-model support, custom agent creation, extensive tool library, and multiple memory systems
- **📈 Scalable Architecture**: Concurrent processing, resource management, load balancing, and horizontal scaling capabilities
- **🛠️ Developer-Friendly**: Simple API, extensive documentation, active community, and CLI tools for rapid development
- **🔐 Enterprise Security**: Built-in error handling, rate limiting, monitoring integration, and audit logging

### Why Choose Swarms?

Swarms stands out as the **most reliable multi-agent framework** because it was built from the ground up for production environments. Unlike other frameworks that focus on research or simple demos, Swarms provides the infrastructure, tooling, and best practices needed to deploy multi-agent systems in real-world applications.

Whether you're building financial analysis systems, healthcare diagnostics, manufacturing optimization, or any other complex multi-agent application, Swarms provides the foundation you need to succeed.

Get started learning swarms with the following examples and more.  

## Install 💻

```bash
$ pip3 install -U swarms
```

### Using uv (Recommended)
[uv](https://github.com/astral-sh/uv) is a fast Python package installer and resolver, written in Rust.

```bash
# Install uv
$ curl -LsSf https://astral.sh/uv/install.sh | sh

# Install swarms using uv
$ uv pip install swarms
```

### Using poetry
```bash
# Install poetry if you haven't already
$ curl -sSL https://install.python-poetry.org | python3 -

# Add swarms to your project
$ poetry add swarms
```

### From source
```bash
# Clone the repository
$ git clone https://github.com/kyegomez/swarms.git
$ cd swarms

# Install with pip
$ pip install -e .
```

---

## Environment Configuration

[Learn more about the environment configuration here](https://docs.swarms.world/en/latest/swarms/install/env/)

```
OPENAI_API_KEY=""
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
```



### 🤖 Your First Agent

An **Agent** is the fundamental building block of a swarm—an autonomous entity powered by an LLM + Tools + Memory. [Learn more Here](https://docs.swarms.world/en/latest/swarms/structs/agent/)

```python
from swarms import Agent

# Initialize a new agent
agent = Agent(
    model_name="gpt-4o-mini", # Specify the LLM
    max_loops=1,              # Set the number of interactions
    interactive=True,         # Enable interactive mode for real-time feedback
)

# Run the agent with a task
agent.run("What are the key benefits of using a multi-agent system?")
```

### 🤝 Your First Swarm: Multi-Agent Collaboration

A **Swarm** consists of multiple agents working together. This simple example creates a two-agent workflow for researching and writing a blog post. [Learn More About SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)

```python
from swarms import Agent, SequentialWorkflow

# Agent 1: The Researcher
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Your job is to research the provided topic and provide a detailed summary.",
    model_name="gpt-4o-mini",
)

# Agent 2: The Writer
writer = Agent(
    agent_name="Writer",
    system_prompt="Your job is to take the research summary and write a beautiful, engaging blog post about it.",
    model_name="gpt-4o-mini",
)

# Create a sequential workflow where the researcher's output feeds into the writer's input
workflow = SequentialWorkflow(agents=[researcher, writer])

# Run the workflow on a task
final_post = workflow.run("The history and future of artificial intelligence")
print(final_post)

```

-----

## 🏗️ Multi-Agent Architectures For Production Deployments

`swarms` provides a variety of powerful, pre-built multi-agent architectures enabling you to orchestrate agents in various ways. Choose the right structure for your specific problem to build efficient and reliable production systems.

| **Architecture** | **Description** | **Best For** |
|---|---|---|
| **[SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** | Agents execute tasks in a linear chain; one agent's output is the next one's input. | Step-by-step processes like data transformation pipelines, report generation. |
| **[ConcurrentWorkflow](https://docs.swarms.world/en/latest/swarms/structs/concurrent_workflow/)** | Agents run tasks simultaneously for maximum efficiency. | High-throughput tasks like batch processing, parallel data analysis. |
| **[AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)** | Dynamically maps complex relationships (e.g., `a -> b, c`) between agents. | Flexible and adaptive workflows, task distribution, dynamic routing. |
| **[GraphWorkflow](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** | Orchestrates agents as nodes in a Directed Acyclic Graph (DAG). | Complex projects with intricate dependencies, like software builds. |
| **[MixtureOfAgents (MoA)](https://docs.swarms.world/en/latest/swarms/structs/moa/)** | Utilizes multiple expert agents in parallel and synthesizes their outputs. | Complex problem-solving, achieving state-of-the-art performance through collaboration. |
| **[GroupChat](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** | Agents collaborate and make decisions through a conversational interface. | Real-time collaborative decision-making, negotiations, brainstorming. |
| **[ForestSwarm](https://docs.swarms.world/en/latest/swarms/structs/forest_swarm/)** | Dynamically selects the most suitable agent or tree of agents for a given task. | Task routing, optimizing for expertise, complex decision-making trees. |
| **[SpreadSheetSwarm](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** | Manages thousands of agents concurrently, tracking tasks and outputs in a structured format. | Massive-scale parallel operations, large-scale data generation and analysis. |
| **[SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** | Universal orchestrator that provides a single interface to run any type of swarm with dynamic selection. | Simplifying complex workflows, switching between swarm strategies, unified multi-agent management. |

-----

### SequentialWorkflow

A `SequentialWorkflow` executes tasks in a strict order, forming a pipeline where each agent builds upon the work of the previous one. `SequentialWorkflow` is Ideal for processes that have clear, ordered steps. This ensures that tasks with dependencies are handled correctly.

```python
from swarms import Agent, SequentialWorkflow

# Initialize agents for a 3-step process
# 1. Generate an idea
idea_generator = Agent(agent_name="IdeaGenerator", system_prompt="Generate a unique startup idea.", model_name="gpt-4o-mini")
# 2. Validate the idea
validator = Agent(agent_name="Validator", system_prompt="Take this startup idea and analyze its market viability.", model_name="gpt-4o-mini")
# 3. Create a pitch
pitch_creator = Agent(agent_name="PitchCreator", system_prompt="Write a 3-sentence elevator pitch for this validated startup idea.", model_name="gpt-4o-mini")

# Create the sequential workflow
workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator])

# Run the workflow
elevator_pitch = workflow.run()
print(elevator_pitch)
```

-----


### ConcurrentWorkflow (with `SpreadSheetSwarm`)

A concurrent workflow runs multiple agents simultaneously. `SpreadSheetSwarm` is a powerful implementation that can manage thousands of concurrent agents and log their outputs to a CSV file. Use this architecture for high-throughput tasks that can be performed in parallel, drastically reducing execution time.

```python
from swarms import Agent, SpreadSheetSwarm

# Define a list of tasks (e.g., social media posts to generate)
platforms = ["Twitter", "LinkedIn", "Instagram"]

# Create an agent for each task
agents = [
    Agent(
        agent_name=f"{platform}-Marketer",
        system_prompt=f"Generate a real estate marketing post for {platform}.",
        model_name="gpt-4o-mini",
    )
    for platform in platforms
]

# Initialize the swarm to run these agents concurrently
swarm = SpreadSheetSwarm(
    agents=agents,
    autosave_on=True,
    save_file_path="marketing_posts.csv",
)

# Run the swarm with a single, shared task description
property_description = "A beautiful 3-bedroom house in sunny California."
swarm.run(task=f"Generate a post about: {property_description}")
# Check marketing_posts.csv for the results!
```

---

### AgentRearrange

Inspired by `einsum`, `AgentRearrange` lets you define complex, non-linear relationships between agents using a simple string-based syntax. [Learn more](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/). This architecture is Perfect for orchestrating dynamic workflows where agents might work in parallel, sequence, or a combination of both.

```python
from swarms import Agent, AgentRearrange

# Define agents
researcher = Agent(agent_name="researcher", model_name="gpt-4o-mini")
writer = Agent(agent_name="writer", model_name="gpt-4o-mini")
editor = Agent(agent_name="editor", model_name="gpt-4o-mini")

# Define a flow: researcher sends work to both writer and editor simultaneously
# This is a one-to-many relationship
flow = "researcher -> writer, editor"

# Create the rearrangement system
rearrange_system = AgentRearrange(
    agents=[researcher, writer, editor],
    flow=flow,
)

# Run the system
# The researcher will generate content, and then both the writer and editor
# will process that content in parallel.
outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.")
print(outputs)
```


<!-- 
### GraphWorkflow

`GraphWorkflow` orchestrates tasks using a Directed Acyclic Graph (DAG), allowing you to manage complex dependencies where some tasks must wait for others to complete.

**Description:** Essential for building sophisticated pipelines, like in software development or complex project management, where task order and dependencies are critical.

```python
from swarms import Agent, GraphWorkflow, Node, Edge, NodeType

# Define agents and a simple python function as nodes
code_generator = Agent(agent_name="CodeGenerator", system_prompt="Write Python code for the given task.", model_name="gpt-4o-mini")
code_tester = Agent(agent_name="CodeTester", system_prompt="Test the given Python code and find bugs.", model_name="gpt-4o-mini")

# Create nodes for the graph
node1 = Node(id="generator", agent=code_generator)
node2 = Node(id="tester", agent=code_tester)

# Create the graph and define the dependency
graph = GraphWorkflow()
graph.add_nodes([node1, node2])
graph.add_edge(Edge(source="generator", target="tester")) # Tester runs after generator

# Set entry and end points
graph.set_entry_points(["generator"])
graph.set_end_points(["tester"])

# Run the graph workflow
results = graph.run("Create a function that calculates the factorial of a number.")
print(results)
``` -->

----

### SwarmRouter: The Universal Swarm Orchestrator

The `SwarmRouter` simplifies building complex workflows by providing a single interface to run any type of swarm. Instead of importing and managing different swarm classes, you can dynamically select the one you need just by changing the `swarm_type` parameter. [Read the full documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)

This makes your code cleaner and more flexible, allowing you to switch between different multi-agent strategies with ease. Here's a complete example that shows how to define agents and then use `SwarmRouter` to execute the same task using different collaborative strategies.

```python
from swarms import Agent
from swarms.structs.swarm_router import SwarmRouter, SwarmType

# Define a few generic agents
writer = Agent(agent_name="Writer", system_prompt="You are a creative writer.", model_name="gpt-4o-mini")
editor = Agent(agent_name="Editor", system_prompt="You are an expert editor for stories.", model_name="gpt-4o-mini")
reviewer = Agent(agent_name="Reviewer", system_prompt="You are a final reviewer who gives a score.", model_name="gpt-4o-mini")

# The agents and task will be the same for all examples
agents = [writer, editor, reviewer]
task = "Write a short story about a robot who discovers music."

# --- Example 1: SequentialWorkflow ---
# Agents run one after another in a chain: Writer -> Editor -> Reviewer.
print("Running a Sequential Workflow...")
sequential_router = SwarmRouter(swarm_type=SwarmType.SequentialWorkflow, agents=agents)
sequential_output = sequential_router.run(task)
print(f"Final Sequential Output:\n{sequential_output}\n")

# --- Example 2: ConcurrentWorkflow ---
# All agents receive the same initial task and run at the same time.
print("Running a Concurrent Workflow...")
concurrent_router = SwarmRouter(swarm_type=SwarmType.ConcurrentWorkflow, agents=agents)
concurrent_outputs = concurrent_router.run(task)
# This returns a dictionary of each agent's output
for agent_name, output in concurrent_outputs.items():
    print(f"Output from {agent_name}:\n{output}\n")

# --- Example 3: MixtureOfAgents ---
# All agents run in parallel, and a special 'aggregator' agent synthesizes their outputs.
print("Running a Mixture of Agents Workflow...")
aggregator = Agent(
    agent_name="Aggregator",
    system_prompt="Combine the story, edits, and review into a final document.",
    model_name="gpt-4o-mini"
)
moa_router = SwarmRouter(
    swarm_type=SwarmType.MixtureOfAgents,
    agents=agents,
    aggregator_agent=aggregator, # MoA requires an aggregator
)
aggregated_output = moa_router.run(task)
print(f"Final Aggregated Output:\n{aggregated_output}\n")
```


The `SwarmRouter` is a powerful tool for simplifying multi-agent orchestration. It provides a consistent and flexible way to deploy different collaborative strategies, allowing you to build more sophisticated applications with less code.

-------

### MixtureOfAgents (MoA)

The `MixtureOfAgents` architecture processes tasks by feeding them to multiple "expert" agents in parallel. Their diverse outputs are then synthesized by an aggregator agent to produce a final, high-quality result. [Learn more here](https://docs.swarms.world/en/latest/swarms/examples/moa_example/)

```python
from swarms import Agent, MixtureOfAgents

# Define expert agents
financial_analyst = Agent(agent_name="FinancialAnalyst", system_prompt="Analyze financial data.", model_name="gpt-4o-mini")
market_analyst = Agent(agent_name="MarketAnalyst", system_prompt="Analyze market trends.", model_name="gpt-4o-mini")
risk_analyst = Agent(agent_name="RiskAnalyst", system_prompt="Analyze investment risks.", model_name="gpt-4o-mini")

# Define the aggregator agent
aggregator = Agent(
    agent_name="InvestmentAdvisor",
    system_prompt="Synthesize the financial, market, and risk analyses to provide a final investment recommendation.",
    model_name="gpt-4o-mini"
)

# Create the MoA swarm
moa_swarm = MixtureOfAgents(
    agents=[financial_analyst, market_analyst, risk_analyst],
    aggregator_agent=aggregator,
)

# Run the swarm
recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?")
print(recommendation)
```

----

### GroupChat

`GroupChat` creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve a problem. You can define the speaking order or let it be determined dynamically. This architecture is ideal for tasks that benefit from debate and multi-perspective reasoning, such as contract negotiation, brainstorming, or complex decision-making.

```python
from swarms import Agent, GroupChat

# Define agents for a debate
tech_optimist = Agent(agent_name="TechOptimist", system_prompt="Argue for the benefits of AI in society.", model_name="gpt-4o-mini")
tech_critic = Agent(agent_name="TechCritic", system_prompt="Argue against the unchecked advancement of AI.", model_name="gpt-4o-mini")

# Create the group chat
chat = GroupChat(
    agents=[tech_optimist, tech_critic],
    max_loops=4, # Limit the number of turns in the conversation
)

# Run the chat with an initial topic
conversation_history = chat.run(
    "Let's discuss the societal impact of artificial intelligence."
)

# Print the full conversation
for message in conversation_history:
    print(f"[{message['agent_name']}]: {message['content']}")
```




--------------------------------------------------

# File: swarms/agents/abstractagent.md

# swarms.agents

## 1. Introduction

`AbstractAgent` is an abstract class that serves as a foundation for implementing AI agents. An agent is an entity that can communicate with other agents and perform actions. The `AbstractAgent` class allows for customization in the implementation of the `receive` method, enabling different agents to define unique actions for receiving and processing messages.

`AbstractAgent` provides capabilities for managing tools and accessing memory, and has methods for running, chatting, and stepping through communication with other agents.

## 2. Class Definition

```python
class AbstractAgent:
    """An abstract class for AI agent.

    An agent can communicate with other agents and perform actions.
    Different agents can differ in what actions they perform in the `receive` method.

    Agents are full and completed:

    Agents = llm + tools + memory
    """

    def __init__(self, name: str):
        """
        Args:
            name (str): name of the agent.
        """
        self._name = name

    @property
    def name(self):
        """Get the name of the agent."""
        return self._name

    def tools(self, tools):
        """init tools"""

    def memory(self, memory_store):
        """init memory"""

    def reset(self):
        """(Abstract method) Reset the agent."""

    def run(self, task: str):
        """Run the agent once"""

    def _arun(self, taks: str):
        """Run Async run"""

    def chat(self, messages: List[Dict]):
        """Chat with the agent"""

    def _achat(self, messages: List[Dict]):
        """Asynchronous Chat"""

    def step(self, message: str):
        """Step through the agent"""

    def _astep(self, message: str):
        """Asynchronous step"""
```

## 3. Functionality and Usage

The `AbstractAgent` class represents a generic AI agent and provides a set of methods to interact with it.

To create an instance of an agent, the `name` of the agent should be specified.

### Core Methods

#### 1. `reset`

The `reset` method allows the agent to be reset to its initial state.

```python
agent.reset()
```

#### 2. `run`

The `run` method allows the agent to perform a specific task.

```python
agent.run("some_task")
```

#### 3. `chat`

The `chat` method enables communication with the agent through a series of messages.

```python
messages = [{"id": 1, "text": "Hello, agent!"}, {"id": 2, "text": "How are you?"}]
agent.chat(messages)
```

#### 4. `step`

The `step` method allows the agent to process a single message.

```python
agent.step("Hello, agent!")
```

### Asynchronous Methods

The class also provides asynchronous variants of the core methods.

### Additional Functionality

Additional functionalities for agent initialization and management of tools and memory are also provided.

```python
agent.tools(some_tools)
agent.memory(some_memory_store)
```

## 4. Additional Information and Tips

When implementing a new agent using the `AbstractAgent` class, ensure that the `receive` method is overridden to define the specific behavior of the agent upon receiving messages.

## 5. References and Resources

For further exploration and understanding of AI agents and agent communication, refer to the relevant literature and research on this topic.


--------------------------------------------------

# File: swarms/agents/agent_judge.md

# AgentJudge

A specialized agent for evaluating and judging outputs from other agents or systems. Acts as a quality control mechanism providing objective assessments and feedback.

Based on the research paper: **"Agent-as-a-Judge: Evaluate Agents with Agents"** - [arXiv:2410.10934](https://arxiv.org/abs/2410.10934)

## Overview

The AgentJudge is designed to evaluate and critique outputs from other AI agents, providing structured feedback on quality, accuracy, and areas for improvement. It supports both single-shot evaluations and iterative refinement through multiple evaluation loops with context building.

Key capabilities:

- **Quality Assessment**: Evaluates correctness, clarity, and completeness of agent outputs

- **Structured Feedback**: Provides detailed critiques with strengths, weaknesses, and suggestions

- **Multimodal Support**: Can evaluate text outputs alongside images

- **Context Building**: Maintains evaluation context across multiple iterations

- **Batch Processing**: Efficiently processes multiple evaluations

## Architecture

```mermaid
graph TD
    A[Input Task] --> B[AgentJudge]
    B --> C{Evaluation Mode}

    C -->|step()| D[Single Eval]
    C -->|run()| E[Iterative Eval]
    C -->|run_batched()| F[Batch Eval]

    D --> G[Agent Core]
    E --> G
    F --> G

    G --> H[LLM Model]
    H --> I[Quality Analysis]
    I --> J[Feedback & Output]

    subgraph "Feedback Details"
        N[Strengths]
        O[Weaknesses]
        P[Improvements]
        Q[Accuracy Check]
    end

    J --> N
    J --> O
    J --> P
    J --> Q

```

## Class Reference

### Constructor

```python
AgentJudge(
    id: str = str(uuid.uuid4()),
    agent_name: str = "Agent Judge",
    description: str = "You're an expert AI agent judge...",
    system_prompt: str = AGENT_JUDGE_PROMPT,
    model_name: str = "openai/o1",
    max_loops: int = 1,
    verbose: bool = False,
    *args,
    **kwargs
)
```

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `id` | `str` | `str(uuid.uuid4())` | Unique identifier for the judge instance |
| `agent_name` | `str` | `"Agent Judge"` | Name of the agent judge |
| `description` | `str` | `"You're an expert AI agent judge..."` | Description of the agent's role |
| `system_prompt` | `str` | `AGENT_JUDGE_PROMPT` | System instructions for evaluation |
| `model_name` | `str` | `"openai/o1"` | LLM model for evaluation |
| `max_loops` | `int` | `1` | Maximum evaluation iterations |
| `verbose` | `bool` | `False` | Enable verbose logging |

### Methods

#### step()

```python
step(
    task: str = None,
    tasks: Optional[List[str]] = None,
    img: Optional[str] = None
) -> str
```

Processes a single task or list of tasks and returns evaluation.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `task` | `str` | `None` | Single task/output to evaluate |
| `tasks` | `List[str]` | `None` | List of tasks/outputs to evaluate |
| `img` | `str` | `None` | Path to image for multimodal evaluation |

**Returns:** `str` - Detailed evaluation response

#### run()

```python
run(
    task: str = None,
    tasks: Optional[List[str]] = None,
    img: Optional[str] = None
) -> List[str]
```

Executes evaluation in multiple iterations with context building.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `task` | `str` | `None` | Single task/output to evaluate |
| `tasks` | `List[str]` | `None` | List of tasks/outputs to evaluate |
| `img` | `str` | `None` | Path to image for multimodal evaluation |

**Returns:** `List[str]` - List of evaluation responses from each iteration

#### run_batched()

```python
run_batched(
    tasks: Optional[List[str]] = None,
    imgs: Optional[List[str]] = None
) -> List[List[str]]
```

Executes batch evaluation of multiple tasks with corresponding images.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tasks` | `List[str]` | `None` | List of tasks/outputs to evaluate |
| `imgs` | `List[str]` | `None` | List of image paths (same length as tasks) |

**Returns:** `List[List[str]]` - Evaluation responses for each task

## Examples

### Basic Usage

```python
from swarms import AgentJudge

# Initialize with default settings
judge = AgentJudge()

# Single task evaluation
result = judge.step(task="The capital of France is Paris.")
print(result)
```

### Custom Configuration

```python
from swarms import AgentJudge

# Custom judge configuration
judge = AgentJudge(
    agent_name="content-evaluator",
    model_name="gpt-4",
    max_loops=3,
    verbose=True
)

# Evaluate multiple outputs
outputs = [
    "Agent CalculusMaster: The integral of x^2 + 3x + 2 is (1/3)x^3 + (3/2)x^2 + 2x + C",
    "Agent DerivativeDynamo: The derivative of sin(x) is cos(x)",
    "Agent LimitWizard: The limit of sin(x)/x as x approaches 0 is 1"
]

evaluation = judge.step(tasks=outputs)
print(evaluation)
```

### Iterative Evaluation with Context

```python
from swarms import AgentJudge

# Multiple iterations with context building
judge = AgentJudge(max_loops=3)

# Each iteration builds on previous context
evaluations = judge.run(task="Agent output: 2+2=5")
for i, eval_result in enumerate(evaluations):
    print(f"Iteration {i+1}: {eval_result}\n")
```

### Multimodal Evaluation

```python
from swarms import AgentJudge

judge = AgentJudge()

# Evaluate with image
evaluation = judge.step(
    task="Describe what you see in this image",
    img="path/to/image.jpg"
)
print(evaluation)
```

### Batch Processing

```python
from swarms import AgentJudge

judge = AgentJudge()

# Batch evaluation with images
tasks = [
    "Describe this chart",
    "What's the main trend?",
    "Any anomalies?"
]
images = [
    "chart1.png",
    "chart2.png", 
    "chart3.png"
]

# Each task evaluated independently
evaluations = judge.run_batched(tasks=tasks, imgs=images)
for i, task_evals in enumerate(evaluations):
    print(f"Task {i+1} evaluations: {task_evals}")
```

## Reference

```bibtex
@misc{zhuge2024agentasajudgeevaluateagentsagents,
    title={Agent-as-a-Judge: Evaluate Agents with Agents}, 
    author={Mingchen Zhuge and Changsheng Zhao and Dylan Ashley and Wenyi Wang and Dmitrii Khizbullin and Yunyang Xiong and Zechun Liu and Ernie Chang and Raghuraman Krishnamoorthi and Yuandong Tian and Yangyang Shi and Vikas Chandra and Jürgen Schmidhuber},
    year={2024},
    eprint={2410.10934},
    archivePrefix={arXiv},
    primaryClass={cs.AI},
    url={https://arxiv.org/abs/2410.10934}
}
```

--------------------------------------------------

# File: swarms/agents/consistency_agent.md

# Consistency Agent Documentation

The `SelfConsistencyAgent` is a specialized agent designed for generating multiple independent responses to a given task and aggregating them into a single, consistent final answer. It leverages concurrent processing to enhance efficiency and employs a majority voting mechanism to ensure the reliability of the aggregated response.

## Purpose

The primary objective of the `SelfConsistencyAgent` is to provide a robust mechanism for decision-making and problem-solving by generating diverse responses and synthesizing them into a coherent final answer. This approach is particularly useful in scenarios where consistency and reliability are critical.

## Class: `SelfConsistencyAgent`

### Initialization

- **`__init__`**: Initializes the `SelfConsistencyAgent` with specified parameters.

#### Arguments

| Argument               | Type    | Default | Description                                                                 |
|------------------------|---------|---------|-----------------------------------------------------------------------------|
| `name`                 | `str`   | `"Self-Consistency-Agent"` | Name of the agent.                                                         |
| `description`          | `str`   | `"An agent that uses self consistency to generate a final answer."` | Description of the agent's purpose.                                        |
| `system_prompt`        | `str`   | `CONSISTENCY_SYSTEM_PROMPT` | System prompt for the reasoning agent.                                     |
| `model_name`           | `str`   | Required | The underlying language model to use.                                      |
| `num_samples`          | `int`   | `5`     | Number of independent responses to generate.                               |
| `max_loops`            | `int`   | `1`     | Maximum number of reasoning loops per sample.                              |
| `majority_voting_prompt` | `Optional[str]` | `majority_voting_prompt` | Custom prompt for majority voting aggregation.                             |
| `eval`                 | `bool`  | `False` | Enable evaluation mode for answer validation.                              |
| `output_type`          | `OutputType` | `"dict"` | Format of the output.                                                      |
| `random_models_on`     | `bool`  | `False` | Enable random model selection for diversity.                               |

### Methods

- **`run`**: Generates multiple responses for the given task and aggregates them.
  - **Arguments**:
    - `task` (`str`): The input prompt.
    - `img` (`Optional[str]`, optional): Image input for vision tasks.
    - `answer` (`Optional[str]`, optional): Expected answer for validation (if eval=True).
  - **Returns**: `Union[str, Dict[str, Any]]` - The aggregated final answer.

- **`aggregation_agent`**: Aggregates a list of responses into a single final answer using majority voting.
  - **Arguments**:
    - `responses` (`List[str]`): The list of responses.
    - `prompt` (`str`, optional): Custom prompt for the aggregation agent.
    - `model_name` (`str`, optional): Model to use for aggregation.
  - **Returns**: `str` - The aggregated answer.

- **`check_responses_for_answer`**: Checks if a specified answer is present in any of the provided responses.
  - **Arguments**:
    - `responses` (`List[str]`): A list of responses to check.
    - `answer` (`str`): The answer to look for in the responses.
  - **Returns**: `bool` - `True` if the answer is found, `False` otherwise.

- **`batched_run`**: Run the agent on multiple tasks in batch.
  - **Arguments**:
    - `tasks` (`List[str]`): List of tasks to be processed.
  - **Returns**: `List[Union[str, Dict[str, Any]]]` - List of results for each task.

### Examples

#### Example 1: Basic Usage

```python
from swarms.agents.consistency_agent import SelfConsistencyAgent

# Initialize the agent
agent = SelfConsistencyAgent(
    name="Math-Reasoning-Agent",
    model_name="gpt-4o-mini",
    max_loops=1,
    num_samples=5
)

# Define a task
task = "What is the 40th prime number?"

# Run the agent
final_answer = agent.run(task)

# Print the final aggregated answer
print("Final aggregated answer:", final_answer)
```

#### Example 2: Using Custom Majority Voting Prompt

```python
from swarms.agents.consistency_agent import SelfConsistencyAgent

# Initialize the agent with a custom majority voting prompt
agent = SelfConsistencyAgent(
    name="Reasoning-Agent",
    model_name="gpt-4o-mini",
    max_loops=1,
    num_samples=5,
    majority_voting_prompt="Please provide the most common response."
)

# Define a task
task = "Explain the theory of relativity in simple terms."

# Run the agent
final_answer = agent.run(task)

# Print the final aggregated answer
print("Final aggregated answer:", final_answer)
```

#### Example 3: Evaluation Mode

```python
from swarms.agents.consistency_agent import SelfConsistencyAgent

# Initialize the agent with evaluation mode
agent = SelfConsistencyAgent(
    name="Validation-Agent",
    model_name="gpt-4o-mini",
    num_samples=3,
    eval=True
)

# Run with expected answer for validation
result = agent.run("What is 2 + 2?", answer="4", eval=True)
if result is not None:
    print("Validation passed:", result)
else:
    print("Validation failed - expected answer not found")
```

#### Example 4: Random Models for Diversity

```python
from swarms.agents.consistency_agent import SelfConsistencyAgent

# Initialize the agent with random model selection
agent = SelfConsistencyAgent(
    name="Diverse-Reasoning-Agent",
    model_name="gpt-4o-mini",
    num_samples=5,
    random_models_on=True
)

# Run the agent
result = agent.run("What are the benefits of renewable energy?")
print("Diverse reasoning result:", result)
```

#### Example 5: Batch Processing

```python
from swarms.agents.consistency_agent import SelfConsistencyAgent

# Initialize the agent
agent = SelfConsistencyAgent(
    name="Batch-Processing-Agent",
    model_name="gpt-4o-mini",
    num_samples=3
)

# Define multiple tasks
tasks = [
    "What is the capital of France?",
    "What is 15 * 23?",
    "Explain photosynthesis in simple terms."
]

# Process all tasks
results = agent.batched_run(tasks)

# Print results
for i, result in enumerate(results):
    print(f"Task {i+1} result: {result}")
```

## Key Features

### Self-Consistency Technique
The agent implements the self-consistency approach based on the research paper "Self-Consistency Improves Chain of Thought Reasoning in Language Models" by Wang et al. (2022). This technique:

1. **Generates Multiple Independent Responses**: Creates several reasoning paths for the same problem
2. **Analyzes Consistency**: Examines agreement among different reasoning approaches
3. **Aggregates Results**: Uses majority voting or consensus building
4. **Produces Reliable Output**: Delivers a final answer reflecting the most reliable consensus

### Benefits
- **Mitigates Random Errors**: Multiple reasoning paths reduce individual path errors
- **Reduces Bias**: Diverse approaches minimize single-method biases
- **Improves Reliability**: Consensus-based results are more trustworthy
- **Handles Complexity**: Better performance on complex problem-solving tasks

### Use Cases
- **Mathematical Problem Solving**: Where accuracy is critical
- **Decision Making**: When reliability is paramount
- **Validation Tasks**: When answers need verification
- **Complex Reasoning**: Multi-step problem solving
- **Research Questions**: Where multiple perspectives are valuable

## Technical Details

### Concurrent Execution
The agent uses `ThreadPoolExecutor` to generate multiple responses concurrently, improving performance while maintaining independence between reasoning paths.

### Aggregation Process
The aggregation uses an AI-powered agent that:
- Identifies dominant responses
- Analyzes disparities and disagreements
- Evaluates consensus strength
- Synthesizes minority insights
- Provides comprehensive recommendations

### Output Formats
The agent supports various output types:
- `"dict"`: Dictionary format with conversation history
- `"str"`: Simple string output
- `"list"`: List format
- `"json"`: JSON formatted output

## Limitations

1. **Computational Cost**: Higher `num_samples` increases processing time and cost
2. **Model Dependencies**: Performance depends on the underlying model capabilities
3. **Consensus Challenges**: May struggle with tasks where multiple valid approaches exist
4. **Memory Usage**: Concurrent execution requires more memory resources

## Best Practices

1. **Sample Size**: Use 3-7 samples for most tasks; increase for critical decisions
2. **Model Selection**: Choose models with strong reasoning capabilities
3. **Evaluation Mode**: Enable for tasks with known correct answers
4. **Custom Prompts**: Tailor majority voting prompts for specific domains
5. **Batch Processing**: Use `batched_run` for multiple related tasks

---


--------------------------------------------------

# File: swarms/agents/create_agents_yaml.md

# Building Agents from a YAML File

The `create_agents_from_yaml` function is designed to dynamically create agents and orchestrate swarms based on configurations defined in a YAML file. It is particularly suited for enterprise use-cases, offering scalability and reliability for agent-based workflows.

### Key Features:
- **Multi-Agent Creation**: Automatically instantiate multiple agents from a YAML file.
- **Swarm Architecture**: Supports swarm architectures where agents collaborate to solve complex tasks.
- **Logging with Loguru**: Includes robust logging for tracking operations and diagnosing issues.
- **Flexible Return Types**: Offers several return types based on the requirements of the system.
- **Customizable**: Supports additional arguments (`*args` and `**kwargs`) for fine-tuning agent behavior.
- **Error Handling**: Handles missing configurations and invalid inputs with meaningful error messages.

---

### Parameters

| Parameter    | Description                                                                                                                                       | Type        | Default Value | Example                             |
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------------|-------------------------------------|
| `model`      | A callable representing the model (LLM or other) that agents will use.                                                                             | Callable    | None          | `OpenAIChat(model_name="gpt-4")`    |
| `yaml_file`  | Path to the YAML file containing agent configurations.                                                                                            | String      | "agents.yaml" | `"config/agents.yaml"`              |
| `return_type`| Determines the type of return object. Options: `"auto"`, `"swarm"`, `"agents"`, `"both"`, `"tasks"`, `"run_swarm"`.                                | String      | "auto"        | `"both"`                            |
| `*args`      | Additional positional arguments for further customization (e.g., agent behavior).                                                                  | List        | N/A           | N/A                                 |
| `**kwargs`   | Additional keyword arguments for customization (e.g., specific parameters passed to the agents or swarm).                                           | Dict        | N/A           | N/A                                 |

---

### Return Types

| Return Type     | Description                                                                                                                                   |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
| `SwarmRouter`   | Returns a `SwarmRouter` object, orchestrating the created agents, only if swarm architecture is defined in YAML.                               |
| `Agent`         | Returns a single agent if only one is defined.                                                                                                |
| `List[Agent]`   | Returns a list of agents if multiple are defined.                                                                                             |
| `Tuple`         | If both agents and a swarm are present, returns both as a tuple (`SwarmRouter, List[Agent]`).                                                  |
| `List[Dict]`    | Returns a list of task results if tasks were executed.                                                                                        |
| `None`          | Returns nothing if an invalid return type is provided or an error occurs.                                                                     |

---

### Detailed Return Types

| Return Type        | Condition                                                          | Example Return Value                          |
|--------------------|---------------------------------------------------------------------|-----------------------------------------------|
| `"auto"`           | Automatically determines the return based on YAML content.          | `SwarmRouter` if swarm architecture is defined, otherwise `Agent` or `List[Agent]`. |
| `"swarm"`          | Returns `SwarmRouter` if present; otherwise returns agents.         | `<SwarmRouter>`                               |
| `"agents"`         | Returns a list of agents (or a single agent if only one is defined).| `[<Agent>, <Agent>]` or `<Agent>`             |
| `"both"`           | Returns both `SwarmRouter` and agents in a tuple.                  | `(<SwarmRouter>, [<Agent>, <Agent>])`         |
| `"tasks"`          | Returns the task results, if tasks were executed by agents.         | `[{'task': 'task_output'}, {'task2': 'output'}]` |
| `"run_swarm"`      | Executes the swarm (if defined) and returns the result.             | `'Swarm task output here'`                    |

---

### Example Use Cases

1. **Creating Multiple Agents for Financial Analysis**

```yaml
agents:
  - agent_name: "Financial-Analysis-Agent"
    system_prompt: "Analyze the best investment strategy for 2024."
    max_loops: 1
    autosave: true
    verbose: false
    context_length: 100000
    output_type: "str"
    task: "Analyze stock options for long-term gains."

  - agent_name: "Risk-Analysis-Agent"
    system_prompt: "Evaluate the risk of tech stocks in 2024."
    max_loops: 2
    autosave: false
    verbose: true
    context_length: 50000
    output_type: "json"
    task: "What are the riskiest stocks in the tech sector?"
```

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_router import SwarmRouter

# Model representing your LLM
def model(prompt):
    return f"Processed: {prompt}"

# Create agents and return them as a list
agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="agents")
print(agents)
```

2. **Running a Swarm of Agents to Solve a Complex Task**

```yaml
agents:
  - agent_name: "Legal-Agent"
    system_prompt: "Provide legal advice on corporate structuring."
    task: "How to incorporate a business as an LLC?"

swarm_architecture:
  name: "Corporate-Swarm"
  description: "A swarm for helping businesses with legal and tax advice."
  swarm_type: "ConcurrentWorkflow"
  task: "How can we optimize a business structure for maximum tax efficiency?"
  max_loops: 3
```

```python
import os

from dotenv import load_dotenv
from loguru import logger
from swarm_models import OpenAIChat

from swarms.agents.create_agents_from_yaml import (
    create_agents_from_yaml,
)

# Load environment variables
load_dotenv()

# Path to your YAML file
yaml_file = "agents_multi_agent.yaml"


try:
  # Create agents and run tasks (using 'both' to return agents and task results)
  task_results = create_agents_from_yaml(
      model=model, yaml_file=yaml_file, return_type="run_swarm"
  )

  logger.info(f"Results from agents: {task_results}")
except Exception as e:
    logger.error(f"An error occurred: {e}")

```

3. **Returning Both Agents and Tasks**

```yaml
agents:
  - agent_name: "Market-Research-Agent"
    system_prompt: "What are the latest trends in AI?"
    task: "Provide a market analysis for AI technologies in 2024."
```

```python
from swarms.structs.agent import Agent

# Model representing your LLM
def model(prompt):
    return f"Processed: {prompt}"

# Create agents and run tasks, return both agents and task results
swarm, agents = create_agents_from_yaml(model=model, yaml_file="agents.yaml", return_type="both")
print(swarm, agents)
```

---



---

### YAML Schema Overview:

Below is a breakdown of the attributes expected in the YAML configuration file, which governs how agents and swarms are created.

### YAML Attributes Table:

| Attribute Name                   | Description                                                | Type          | Required | Default/Example Value                    |
|-----------------------------------|------------------------------------------------------------|---------------|----------|------------------------------------------|
| `agents`                          | List of agents to be created. Each agent must have specific configurations. | List of dicts | Yes      |                                          |
| `agent_name`                      | The name of the agent.                                     | String        | Yes      | `"Stock-Analysis-Agent"`                 |
| `system_prompt`                   | The system prompt that the agent will use.                 | String        | Yes      | `"Your full system prompt here"`         |
| `max_loops`                       | Maximum number of iterations or loops for the agent.       | Integer       | No       | 1                                        |
| `autosave`                        | Whether the agent should automatically save its state.     | Boolean       | No       | `true`                                   |
| `dashboard`                       | Whether to enable a dashboard for the agent.               | Boolean       | No       | `false`                                  |
| `verbose`                         | Whether to run the agent in verbose mode (for debugging).  | Boolean       | No       | `false`                                  |
| `dynamic_temperature_enabled`     | Enable dynamic temperature adjustments during agent execution. | Boolean       | No       | `false`                                  |
| `saved_state_path`                | Path where the agent's state is saved for recovery.        | String        | No       | `"path_to_save_state.json"`              |
| `user_name`                       | Name of the user interacting with the agent.               | String        | No       | `"default_user"`                         |
| `retry_attempts`                  | Number of times to retry an operation in case of failure.  | Integer       | No       | 1                                        |
| `context_length`                  | Maximum context length for agent interactions.             | Integer       | No       | 100000                                   |
| `return_step_meta`                | Whether to return metadata for each step of the task.      | Boolean       | No       | `false`                                  |
| `output_type`                     | The type of output the agent will return (e.g., `str`, `json`). | String        | No       | `"str"`                                  |
| `task`                            | Task to be executed by the agent (optional).               | String        | No       | `"What is the best strategy for long-term stock investment?"` |

#### Swarm Architecture (Optional):

| Attribute Name                   | Description                                                | Type          | Required | Default/Example Value                    |
|-----------------------------------|------------------------------------------------------------|---------------|----------|------------------------------------------|
| `swarm_architecture`              | Defines the swarm configuration. For more information on what can be added to the swarm architecture, please refer to the [Swarm Router documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/). | Dict          | No       |                                          |
| `name`                            | The name of the swarm.                                     | String        | Yes      | `"MySwarm"`                              |
| `description`                     | Description of the swarm and its purpose.                  | String        | No       | `"A swarm for collaborative task solving"`|
| `max_loops`                       | Maximum number of loops for the swarm.                     | Integer       | No       | 5                                        |
| `swarm_type`                      | The type of swarm (e.g., `ConcurrentWorkflow`) `SequentialWorkflow`.            | String        | Yes      | `"ConcurrentWorkflow"`                   |
| `task`                            | The primary task assigned to the swarm.                    | String        | No       | `"How can we trademark concepts as a delaware C CORP for free?"` |

---
### YAML Schema Example:

Below is an updated YAML schema that conforms to the function's expectations:

```yaml
agents:
  - agent_name: "Financial-Analysis-Agent"
    system_prompt: "Your full system prompt here"
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "finance_agent.json"
    user_name: "swarms_corp"
    retry_attempts: 1
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    # task: "How can I establish a ROTH IRA to buy stocks and get a tax break?" # Turn off if using swarm

  - agent_name: "Stock-Analysis-Agent"
    system_prompt: "Your full system prompt here"
    max_loops: 2
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: false
    saved_state_path: "stock_agent.json"
    user_name: "stock_user"
    retry_attempts: 3
    context_length: 150000
    return_step_meta: true
    output_type: "json"
    # task: "What is the best strategy for long-term stock investment?"

# Optional Swarm Configuration
swarm_architecture:
  name: "MySwarm"
  description: "A swarm for collaborative task solving"
  max_loops: 5
  swarm_type: "ConcurrentWorkflow"
  task: "How can we trademark concepts as a delaware C CORP for free?" # Main task 
```

# Diagram
```mermaid
graph TD;
    A[Task] -->|Send to| B[Financial-Analysis-Agent]
    A -->|Send to| C[Stock-Analysis-Agent]
```

---

### How to Use `create_agents_from_yaml` Function with YAML:

- You need to plug in your specific model until we can create a model router that can fetch any model and set specific settings

#### Example Code:
```python
import os

from dotenv import load_dotenv
from loguru import logger
from swarm_models import OpenAIChat

from swarms.agents.create_agents_from_yaml import (
    create_agents_from_yaml,
)

# Load environment variables
load_dotenv()

# Path to your YAML file
yaml_file = "agents.yaml"


# Get the OpenAI API key from the environment variable
api_key = os.getenv("GROQ_API_KEY")

# Model
model = OpenAIChat(
    openai_api_base="https://api.groq.com/openai/v1",
    openai_api_key=api_key,
    model_name="llama-3.1-70b-versatile",
    temperature=0.1,
)

try:
    # Create agents and run tasks (using 'both' to return agents and task results)
    task_results = create_agents_from_yaml(
        model=model, yaml_file=yaml_file, return_type="run_swarm" # 
    )

    logger.info(f"Results from agents: {task_results}")
except Exception as e:
    logger.error(f"An error occurred: {e}")

```

---

### Error Handling:

1. **FileNotFoundError**: If the specified YAML file does not exist.
2. **ValueError**: Raised if there are invalid or missing configurations in the YAML file.
3. **Invalid Return Type**: If an invalid return type is specified, the function will raise a `ValueError`.

### Conclusion:
The `create_agents_from_yaml` function provides a flexible and powerful way to dynamically configure and execute agents, supporting a wide range of tasks and configurations for enterprise-level use cases. By following the YAML schema and function signature, users can easily define and manage their agents and swarms.

--------------------------------------------------

# File: swarms/agents/external_party_agents.md



# **Swarms External Agent Integration**

Integrating external agents from other frameworks like **Langchain**, **Griptape**, and more is straightforward using **Swarms**. Below are step-by-step guides on how to bring these agents into Swarms by creating a new class, implementing the required methods, and ensuring compatibility.

---

## **Quick Overview**

- **Step 1**: Create a new class that inherits the `Agent` class from Swarms.
- **Step 2**: Override the `.run(task: str) -> str` method that will execute the agent and return a string response.
- **Step 3**: Optionally, add methods to save outputs to other formats like JSON, logs, or databases.

### **Agent Class**

The primary structure you'll need to integrate any external agent is the `Agent` class from **Swarms**. Here’s a template for how your new agent class should be structured:

```python
from swarms import Agent

class ExternalAgent(Agent):
    def run(self, task: str) -> str:
        # Implement logic to run external agent
        pass

    def save_to_json(self, output: str, filepath: str):
        # Optionally save the result to a JSON file
        with open(filepath, "w") as file:
            json.dump({"response": output}, file)
```

---

## **Griptape Agent Integration Example**

In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method.

### **Griptape Integration Steps**:

1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class.
2. **Create Griptape Agent**: Initialize the **Griptape** agent inside your class and provide it with the necessary tools.
3. **Override the `run()` method**: Implement logic to process a task string and execute the Griptape agent.

## **Griptape Example Code**:

```python
from swarms import (
    Agent as SwarmsAgent,
)  # Import the base Agent class from Swarms
from griptape.structures import Agent as GriptapeAgent
from griptape.tools import (
    WebScraperTool,
    FileManagerTool,
    PromptSummaryTool,
)

# Create a custom agent class that inherits from SwarmsAgent
class GriptapeSwarmsAgent(SwarmsAgent):
    def __init__(self, *args, **kwargs):
        # Initialize the Griptape agent with its tools
        self.agent = GriptapeAgent(
            input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.",
            tools=[
                WebScraperTool(off_prompt=True),
                PromptSummaryTool(off_prompt=True),
                FileManagerTool(),
            ],
            *args,
            **kwargs,
        )

    # Override the run method to take a task and execute it using the Griptape agent
    def run(self, task: str) -> str:
        # Extract URL and filename from task
        url, filename = task.split(",")  # Example task string: "https://example.com, output.txt"
        # Execute the Griptape agent
        result = self.agent.run(url.strip(), filename.strip())
        # Return the final result as a string
        return str(result)


# Example usage:
griptape_swarms_agent = GriptapeSwarmsAgent()
output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt")
print(output)
```

### **Explanation**:
1. **GriptapeSwarmsAgent**: The custom class that integrates **Griptape** into **Swarms**.
2. **run(task: str)**: This method extracts inputs from the task string and runs the agent using **Griptape** tools.
3. **Tools**: The **Griptape** agent is equipped with web scraping, summarization, and file management tools.


## **Additional Features**:
You can enhance your external agents with additional features such as:

- **Saving outputs** to JSON, databases, or logs.

- **Handling errors** and retry mechanisms for robustness.

- **Custom logging** with tools like **Loguru** for extensive debugging.

---

## **Langchain Agent Integration Example**

Next, we demonstrate how to integrate a **Langchain** agent with **Swarms** by following similar steps.

### **Langchain Integration Steps**:

1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class.
2. **Create Langchain Agent**: Initialize a Langchain agent with the necessary components (like language models or memory modules).
3. **Override the `run()` method**: Pass tasks to the Langchain agent and return the response.

## **Langchain Example Code**:

```python
from swarms import Agent as SwarmsAgent
from langchain import LLMChain
from langchain.llms import OpenAI
from langchain.prompts import PromptTemplate

# Create a custom agent class that inherits from SwarmsAgent
class LangchainSwarmsAgent(SwarmsAgent):
    def __init__(self, *args, **kwargs):
        # Initialize the Langchain agent with LLM and prompt
        prompt_template = PromptTemplate(template="Answer the question: {question}")
        llm = OpenAI(model="gpt-3.5-turbo")
        self.chain = LLMChain(llm=llm, prompt=prompt_template)
        super().__init__(*args, **kwargs)

    # Override the run method to take a task and execute it using the Langchain agent
    def run(self, task: str) -> str:
        # Pass the task to the Langchain agent
        result = self.chain.run({"question": task})
        # Return the final result as a string
        return result

# Example usage:
langchain_swarms_agent = LangchainSwarmsAgent()
output = langchain_swarms_agent.run("What is the capital of France?")
print(output)
```

### **Explanation**:
1. **LangchainSwarmsAgent**: The custom class integrates **Langchain** into **Swarms**.
2. **run(task: str)**: The task is passed to a language model via Langchain and returns a result.


### Additional Examples from other providers


### 1. **OpenAI Function Calling Agents**
- **Description**: OpenAI models like GPT-4 can now call functions programmatically. This makes it possible to create agents that execute external functions, APIs, or code snippets.
  
  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  import openai

  # Custom OpenAI Function Calling Agent
  class OpenAIFunctionAgent(SwarmsAgent):
      def __init__(self, *args, **kwargs):
          # Initialize OpenAI API credentials and settings
          self.api_key = "your_openai_api_key"
          super().__init__(*args, **kwargs)

      def run(self, task: str) -> str:
          # Example task: "summarize, 'Provide a short summary of this text...'"
          command, input_text = task.split(", ")
          response = openai.Completion.create(
              model="gpt-4",
              prompt=f"{command}: {input_text}",
              temperature=0.5,
              max_tokens=100,
          )
          return response.choices[0].text.strip()

  # Example usage:
  openai_agent = OpenAIFunctionAgent()
  output = openai_agent.run("summarize, Provide a short summary of this text...")
  print(output)
  ```

### 2. **Rasa Agents**
- **Description**: **Rasa** is a popular open-source framework for building conversational AI agents. You can integrate **Rasa** to build dialogue-based agents with **Swarms**.

  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  from rasa.core.agent import Agent as RasaAgent
  from rasa.core.interpreter import RasaNLUInterpreter

  # Custom Rasa Swarms Agent
  class RasaSwarmsAgent(SwarmsAgent):
      def __init__(self, model_path: str, *args, **kwargs):
          # Initialize the Rasa agent with a pre-trained model
          self.agent = RasaAgent.load(model_path)
          super().__init__(*args, **kwargs)

      def run(self, task: str) -> str:
          # Pass user input to the Rasa agent
          result = self.agent.handle_text(task)
          # Return the final response from the agent
          return result[0]["text"] if result else "No response."

  # Example usage:
  rasa_swarms_agent = RasaSwarmsAgent("path/to/rasa_model")
  output = rasa_swarms_agent.run("Hello, how can I get a refund?")
  print(output)
  ```

### 3. **Hugging Face Transformers**
- **Description**: **Hugging Face** offers a variety of pre-trained models, including transformers for NLP tasks. These can be easily integrated into **Swarms** for various tasks like text generation, question answering, and more.

  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  from transformers import pipeline

  # Custom Hugging Face Agent
  class HuggingFaceSwarmsAgent(SwarmsAgent):
      def __init__(self, model_name: str, *args, **kwargs):
          # Initialize a pre-trained pipeline from Hugging Face
          self.pipeline = pipeline("text-generation", model=model_name)
          super().__init__(*args, **kwargs)

      def run(self, task: str) -> str:
          # Generate text based on the task input
          result = self.pipeline(task, max_length=50)
          return result[0]["generated_text"]

  # Example usage:
  hf_swarms_agent = HuggingFaceSwarmsAgent("gpt2")
  output = hf_swarms_agent.run("Once upon a time in a land far, far away...")
  print(output)
  ```

### 4. **AutoGPT or BabyAGI**
- **Description**: **AutoGPT** and **BabyAGI** are agent frameworks designed to be autonomous, where agents can recursively execute tasks and create new tasks based on previous outputs.
  
  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  from autogpt import AutoGPT

  # Custom AutoGPT Agent
  class AutoGPTSwarmsAgent(SwarmsAgent):
      def __init__(self, config, *args, **kwargs):
          # Initialize AutoGPT with configuration
          self.agent = AutoGPT(config)
          super().__init__(*args, **kwargs)

      def run(self, task: str) -> str:
          # Execute task recursively using AutoGPT
          result = self.agent.run(task)
          return result

  # Example usage:
  autogpt_swarms_agent = AutoGPTSwarmsAgent({"goal": "Solve world hunger"})
  output = autogpt_swarms_agent.run("Develop a plan to solve world hunger.")
  print(output)
  ```

### 5. **DialogFlow Agents**
- **Description**: **DialogFlow** by Google is used to build conversational agents. These agents can process user intents and deliver responses based on predefined conversation flows.
  
  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  from google.cloud import dialogflow

  # Custom DialogFlow Agent
  class DialogFlowSwarmsAgent(SwarmsAgent):
      def __init__(self, project_id: str, session_id: str, *args, **kwargs):
          # Initialize DialogFlow session client
          self.session_client = dialogflow.SessionsClient()
          self.project_id = project_id
          self.session_id = session_id
          super().__init__(*args, **kwargs)

      def run(self, task: str) -> str:
          session = self.session_client.session_path(self.project_id, self.session_id)
          text_input = dialogflow.TextInput(text=task, language_code="en-US")
          query_input = dialogflow.QueryInput(text=text_input)
          response = self.session_client.detect_intent(
              request={"session": session, "query_input": query_input}
          )
          return response.query_result.fulfillment_text

  # Example usage:
  dialogflow_swarms_agent = DialogFlowSwarmsAgent("your_project_id", "your_session_id")
  output = dialogflow_swarms_agent.run("Book me a flight to Paris.")
  print(output)
  ```

### 6. **ChatterBot Agents**
- **Description**: **ChatterBot** is a Python-based machine-learning conversational agent. It learns from previous conversations to generate intelligent responses.
  
  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  from chatterbot import ChatBot

  # Custom ChatterBot Agent
  class ChatterBotSwarmsAgent(SwarmsAgent):
      def __init__(self, name: str, *args, **kwargs):
          # Initialize ChatterBot
          self.agent = ChatBot(name)
          super().__init__(*args, **kwargs)

      def run(self, task: str) -> str:
          # Get a response from ChatterBot based on user input
          response = self.agent.get_response(task)
          return str(response)

  # Example usage:
  chatterbot_swarms_agent = ChatterBotSwarmsAgent("Assistant")
  output = chatterbot_swarms_agent.run("What is the capital of Italy?")
  print(output)
  ```

### 7. **Custom APIs as Agents**
- **Description**: You can create agents that integrate with any REST or GraphQL API by defining them as a task runner within Swarms. This allows for interaction with third-party services.
  
  ## Example Integration:
  ```python
  from swarms import Agent as SwarmsAgent
  import requests

  # Custom API Agent
  class APIAgent(SwarmsAgent):
      def run(self, task: str) -> str:
          # Parse task for API endpoint and parameters
          endpoint, params = task.split(", ")
          response = requests.get(endpoint, params={"q": params})
          return response.text

  # Example usage:
  api_swarms_agent = APIAgent()
  output = api_swarms_agent.run("https://api.example.com/search, python")
  print(output)
  ```

---

### **Summary of Integrations**:

- **Griptape**: Integrate with tools for web scraping, summarization, etc.

- **Langchain**: Use powerful language model orchestration.

- **OpenAI Function Calling**: Directly run OpenAI API-based agents.

- **Rasa**: Build and integrate conversational agents.

- **Hugging Face**: Leverage transformer models.

- **AutoGPT/BabyAGI**: Recursive, autonomous task execution.

- **DialogFlow**: Integrate conversational flows for voice/chat-based systems.

- **ChatterBot**: Machine-learning conversational agents.

- **Custom APIs**: Leverage external APIs as agents for custom workflows.


---


## **Conclusion**:

By following the steps outlined above, you can seamlessly integrate external agent frameworks like **Griptape** and **Langchain** into **Swarms**. This makes Swarms a highly versatile platform for orchestrating various agentic workflows and leveraging the unique capabilities of different frameworks.

For more examples and use cases, please refer to the official Swarms documentation site.



--------------------------------------------------

# File: swarms/agents/gkp_agent.md

# Generated Knowledge Prompting (GKP) Agent

The GKP Agent is a sophisticated reasoning system that enhances its capabilities by generating relevant knowledge before answering queries. This approach, inspired by Liu et al. 2022, is particularly effective for tasks requiring commonsense reasoning and factual information.

## Overview

The GKP Agent consists of three main components:
1. Knowledge Generator - Creates relevant factual information
2. Reasoner - Uses generated knowledge to form answers
3. Coordinator - Synthesizes multiple reasoning paths into a final answer

## Architecture

```mermaid
graph TD
    A[Input Query] --> B[Knowledge Generator]
    B --> C[Generate Knowledge Items]
    C --> D[Reasoner]
    D --> E[Multiple Reasoning Paths]
    E --> F[Coordinator]
    F --> G[Final Answer]
    
    subgraph "Knowledge Generation"
        B
        C
    end
    
    subgraph "Reasoning"
        D
        E
    end
    
    subgraph "Coordination"
        F
        G
    end
```

## Use Cases

```mermaid
graph LR
    A[GKP Agent] --> B[Commonsense Reasoning]
    A --> C[Factual Question Answering]
    A --> D[Complex Problem Solving]
    A --> E[Multi-step Reasoning]
    
    B --> B1[Everyday Logic]
    B --> B2[Social Situations]
    
    C --> C1[Historical Facts]
    C --> C2[Scientific Information]
    
    D --> D1[Technical Analysis]
    D --> D2[Decision Making]
    
    E --> E1[Chain of Thought]
    E --> E2[Multi-perspective Analysis]
```

## API Reference

### GKPAgent

The main agent class that orchestrates the knowledge generation and reasoning process.

#### Initialization Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| agent_name | str | "gkp-agent" | Name identifier for the agent |
| model_name | str | "openai/o1" | LLM model to use for all components |
| num_knowledge_items | int | 6 | Number of knowledge snippets to generate per query |

#### Methods

| Method | Description | Parameters | Returns |
|--------|-------------|------------|---------|
| process(query: str) | Process a single query through the GKP pipeline | query: str | Dict[str, Any] containing full processing results |
| run(queries: List[str], detailed_output: bool = False) | Process multiple queries | queries: List[str], detailed_output: bool | Union[List[str], List[Dict[str, Any]]] |

### KnowledgeGenerator

Component responsible for generating relevant knowledge for queries.

#### Initialization Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| agent_name | str | "knowledge-generator" | Name identifier for the knowledge generator agent |
| model_name | str | "openai/o1" | Model to use for knowledge generation |
| num_knowledge_items | int | 2 | Number of knowledge items to generate per query |

#### Methods

| Method | Description | Parameters | Returns |
|--------|-------------|------------|---------|
| generate_knowledge(query: str) | Generate relevant knowledge for a query | query: str | List[str] of generated knowledge statements |

### Reasoner

Component that uses generated knowledge to reason about and answer queries.

#### Initialization Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| agent_name | str | "knowledge-reasoner" | Name identifier for the reasoner agent |
| model_name | str | "openai/o1" | Model to use for reasoning |

#### Methods

| Method | Description | Parameters | Returns |
|--------|-------------|------------|---------|
| reason_and_answer(query: str, knowledge: str) | Reason about a query using provided knowledge | query: str, knowledge: str | Dict[str, str] containing explanation, confidence, and answer |

## Example Usage

```python
from swarms.agents.gkp_agent import GKPAgent

# Initialize the GKP Agent
agent = GKPAgent(
    agent_name="gkp-agent",
    model_name="gpt-4",  # Using OpenAI's model
    num_knowledge_items=6,  # Generate 6 knowledge items per query
)

# Example queries
queries = [
    "What are the implications of quantum entanglement on information theory?",
]

# Run the agent
results = agent.run(queries)

# Print results
for i, result in enumerate(results):
    print(f"\nQuery {i+1}: {queries[i]}")
    print(f"Answer: {result}")
```

## Best Practices

1. **Knowledge Generation**
   - Set appropriate number of knowledge items based on query complexity
   - Monitor knowledge quality and relevance
   - Adjust model parameters for optimal performance

2. **Reasoning Process**
   - Ensure diverse reasoning paths for complex queries
   - Validate confidence levels
   - Consider multiple perspectives

3. **Coordination**
   - Review coordination logic for complex scenarios
   - Validate final answers against source knowledge
   - Monitor processing time and optimize if needed

## Performance Considerations

- Processing time increases with number of knowledge items
- Complex queries may require more knowledge items
- Consider caching frequently used knowledge
- Monitor token usage for cost optimization

## Error Handling

The agent includes robust error handling for:
- Invalid queries
- Failed knowledge generation
- Reasoning errors
- Coordination failures


--------------------------------------------------

# File: swarms/agents/index.md

# Agents Introduction


An agent in swarms is basically 4 elements added together:

`agent = LLM + Tools + RAG + Loop`

The Agent class is the core component of the Swarms framework, designed to create intelligent, autonomous AI agents capable of handling complex tasks through multi-modal processing, tool integration, and structured outputs. This comprehensive guide covers all aspects of the Agent class, from basic setup to advanced features.


## Prerequisites & Installation

### System Requirements

- Python 3.7+

- OpenAI API key (for GPT models)

- Anthropic API key (for Claude models)

### Installation

```bash
pip3 install -U swarms
```

### Environment Setup

Create a `.env` file with your API keys:

```bash
OPENAI_API_KEY="your-openai-api-key"
ANTHROPIC_API_KEY="your-anthropic-api-key"
WORKSPACE_DIR="agent_workspace"
```

## Basic Agent Configuration

### Core Agent Structure

The Agent class provides a comprehensive set of parameters for customization:

```python
from swarms import Agent

# Basic agent initialization
agent = Agent(
    agent_name="MyAgent",
    agent_description="A specialized AI agent for specific tasks",
    system_prompt="You are a helpful assistant...",
    model_name="gpt-4o-mini",
    max_loops=1,
    max_tokens=4096,
    temperature=0.7,
    output_type="str",
    safety_prompt_on=True
)
```

### Key Configuration Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `agent_name` | str | Unique identifier for the agent | Required |
| `agent_description` | str | Detailed description of capabilities | Required |
| `system_prompt` | str | Core instructions defining behavior | Required |
| `model_name` | str | AI model to use | "gpt-4o-mini" |
| `max_loops` | int | Maximum execution loops | 1 |
| `max_tokens` | int | Maximum response tokens | 4096 |
| `temperature` | float | Response creativity (0-1) | 0.7 |
| `output_type` | str | Response format type | "str" |
| `multi_modal` | bool | Enable image processing | False |
| `safety_prompt_on` | bool | Enable safety checks | True |

### Simple Example

```python
from swarms import Agent

# Create a basic financial advisor agent
financial_agent = Agent(
    agent_name="Financial-Advisor",
    agent_description="Personal finance and investment advisor",
    system_prompt="""You are an expert financial advisor with deep knowledge of:
    - Investment strategies and portfolio management
    - Risk assessment and mitigation
    - Market analysis and trends
    - Financial planning and budgeting
    
    Provide clear, actionable advice while considering risk tolerance.""",
    model_name="gpt-4o-mini",
    max_loops=1,
    temperature=0.3,
    output_type="str"
)

# Run the agent
response = financial_agent.run("What are the best investment strategies for a 30-year-old?")
print(response)
```

## Multi-Modal Capabilities

### Image Processing

The Agent class supports comprehensive image analysis through vision-enabled models:

```python
from swarms import Agent

# Create a vision-enabled agent
vision_agent = Agent(
    agent_name="Vision-Analyst",
    agent_description="Advanced image analysis and quality control agent",
    system_prompt="""You are an expert image analyst capable of:
    - Detailed visual inspection and quality assessment
    - Object detection and classification
    - Scene understanding and context analysis
    - Defect identification and reporting
    
    Provide comprehensive analysis with specific observations.""",
    model_name="gpt-4o-mini",  # Vision-enabled model
    multi_modal=True,  # Enable multi-modal processing
    max_loops=1,
    output_type="str"
)

# Analyze a single image
response = vision_agent.run(
    task="Analyze this image for quality control purposes",
    img="path/to/image.jpg"
)

# Process multiple images
response = vision_agent.run(
    task="Compare these images and identify differences",
    imgs=["image1.jpg", "image2.jpg", "image3.jpg"],
    summarize_multiple_images=True
)
```

### Supported Image Formats

| Format | Description | Max Size |
|--------|-------------|----------|
| JPEG/JPG | Standard compressed format | 20MB |
| PNG | Lossless with transparency | 20MB |
| GIF | Animated (first frame only) | 20MB |
| WebP | Modern efficient format | 20MB |

### Quality Control Example

```python
from swarms import Agent
from swarms.prompts.logistics import Quality_Control_Agent_Prompt

def security_analysis(danger_level: str) -> str:
    """Analyze security danger level and return appropriate response."""
    danger_responses = {
        "low": "No immediate danger detected",
        "medium": "Moderate security concern identified",
        "high": "Critical security threat detected",
        None: "No danger level assessment available"
    }
    return danger_responses.get(danger_level, "Unknown danger level")

# Quality control agent with tool integration
quality_agent = Agent(
    agent_name="Quality-Control-Agent",
    agent_description="Advanced quality control and security analysis agent",
    system_prompt=f"""
    {Quality_Control_Agent_Prompt}
    
    You have access to security analysis tools. When analyzing images:
    1. Identify potential safety hazards
    2. Assess quality standards compliance
    3. Determine appropriate danger levels (low, medium, high)
    4. Use the security_analysis function for threat assessment
    """,
    model_name="gpt-4o-mini",
    multi_modal=True,
    max_loops=1,
    tools=[security_analysis]
)

# Analyze factory image
response = quality_agent.run(
    task="Analyze this factory image for safety and quality issues",
    img="factory_floor.jpg"
)
```

## Tool Integration

### Creating Custom Tools

Tools are Python functions that extend your agent's capabilities:

```python
import json
import requests
from typing import Optional, Dict, Any

def get_weather_data(city: str, country: Optional[str] = None) -> str:
    """
    Get current weather data for a specified city.
    
    Args:
        city (str): The city name
        country (Optional[str]): Country code (e.g., 'US', 'UK')
    
    Returns:
        str: JSON formatted weather data
    
    Example:
        >>> weather = get_weather_data("San Francisco", "US")
        >>> print(weather)
        {"temperature": 18, "condition": "partly cloudy", ...}
    """
    try:
        # API call logic here
        weather_data = {
            "city": city,
            "country": country,
            "temperature": 18,
            "condition": "partly cloudy",
            "humidity": 65,
            "wind_speed": 12
        }
        return json.dumps(weather_data, indent=2)
    
    except Exception as e:
        return json.dumps({"error": f"Weather API error: {str(e)}"})

def calculate_portfolio_metrics(prices: list, weights: list) -> str:
    """
    Calculate portfolio performance metrics.
    
    Args:
        prices (list): List of asset prices
        weights (list): List of portfolio weights
    
    Returns:
        str: JSON formatted portfolio metrics
    """
    try:
        # Portfolio calculation logic
        portfolio_value = sum(p * w for p, w in zip(prices, weights))
        metrics = {
            "total_value": portfolio_value,
            "weighted_average": portfolio_value / sum(weights),
            "asset_count": len(prices)
        }
        return json.dumps(metrics, indent=2)
    
    except Exception as e:
        return json.dumps({"error": f"Calculation error: {str(e)}"})
```

### Tool Integration Example

```python
from swarms import Agent

# Create agent with custom tools
multi_tool_agent = Agent(
    agent_name="Multi-Tool-Assistant",
    agent_description="Versatile assistant with weather and financial tools",
    system_prompt="""You are a versatile assistant with access to:
    - Weather data retrieval for any city
    - Portfolio analysis and financial calculations
    
    Use these tools to provide comprehensive assistance.""",
    model_name="gpt-4o-mini",
    max_loops=1,
    tools=[get_weather_data, calculate_portfolio_metrics]
)

# Use the agent with tools
response = multi_tool_agent.run(
    "What's the weather in New York and calculate metrics for a portfolio with prices [100, 150, 200] and weights [0.3, 0.4, 0.3]?"
)
```

### API Integration Tools

```python
import requests
import json
from typing import List

def get_cryptocurrency_price(coin_id: str, vs_currency: str = "usd") -> str:
    """Get current cryptocurrency price from CoinGecko API."""
    try:
        url = "https://api.coingecko.com/api/v3/simple/price"
        params = {
            "ids": coin_id,
            "vs_currencies": vs_currency,
            "include_market_cap": True,
            "include_24hr_vol": True,
            "include_24hr_change": True
        }
        
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
    
    except Exception as e:
        return json.dumps({"error": f"API error: {str(e)}"})

def get_top_cryptocurrencies(limit: int = 10) -> str:
    """Get top cryptocurrencies by market cap."""
    try:
        url = "https://api.coingecko.com/api/v3/coins/markets"
        params = {
            "vs_currency": "usd",
            "order": "market_cap_desc",
            "per_page": limit,
            "page": 1
        }
        
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
    
    except Exception as e:
        return json.dumps({"error": f"API error: {str(e)}"})

# Crypto analysis agent
crypto_agent = Agent(
    agent_name="Crypto-Analysis-Agent",
    agent_description="Cryptocurrency market analysis and price tracking agent",
    system_prompt="""You are a cryptocurrency analysis expert with access to:
    - Real-time price data for any cryptocurrency
    - Market capitalization rankings
    - Trading volume and price change data
    
    Provide insightful market analysis and investment guidance.""",
    model_name="gpt-4o-mini",
    max_loops=1,
    tools=[get_cryptocurrency_price, get_top_cryptocurrencies]
)

# Analyze crypto market
response = crypto_agent.run("Analyze the current Bitcoin price and show me the top 5 cryptocurrencies")
```

## Structured Outputs

### Function Schema Definition

Define structured outputs using OpenAI's function calling format:

```python
from swarms import Agent

# Define function schemas for structured outputs
stock_analysis_schema = {
    "type": "function",
    "function": {
        "name": "analyze_stock_performance",
        "description": "Analyze stock performance with detailed metrics",
        "parameters": {
            "type": "object",
            "properties": {
                "ticker": {
                    "type": "string",
                    "description": "Stock ticker symbol (e.g., AAPL, GOOGL)"
                },
                "analysis_type": {
                    "type": "string",
                    "enum": ["technical", "fundamental", "comprehensive"],
                    "description": "Type of analysis to perform"
                },
                "time_period": {
                    "type": "string",
                    "enum": ["1d", "1w", "1m", "3m", "1y"],
                    "description": "Time period for analysis"
                },
                "metrics": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": ["price", "volume", "pe_ratio", "market_cap", "volatility"]
                    },
                    "description": "Metrics to include in analysis"
                }
            },
            "required": ["ticker", "analysis_type"]
        }
    }
}

portfolio_optimization_schema = {
    "type": "function",
    "function": {
        "name": "optimize_portfolio",
        "description": "Optimize portfolio allocation based on risk and return",
        "parameters": {
            "type": "object",
            "properties": {
                "assets": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "symbol": {"type": "string"},
                            "current_weight": {"type": "number"},
                            "expected_return": {"type": "number"},
                            "risk_level": {"type": "string", "enum": ["low", "medium", "high"]}
                        },
                        "required": ["symbol", "current_weight"]
                    }
                },
                "risk_tolerance": {
                    "type": "string",
                    "enum": ["conservative", "moderate", "aggressive"]
                },
                "investment_horizon": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 30,
                    "description": "Investment time horizon in years"
                }
            },
            "required": ["assets", "risk_tolerance"]
        }
    }
}

# Create agent with structured outputs
structured_agent = Agent(
    agent_name="Structured-Financial-Agent",
    agent_description="Financial analysis agent with structured output capabilities",
    system_prompt="""You are a financial analysis expert that provides structured outputs.
    Use the provided function schemas to format your responses consistently.""",
    model_name="gpt-4o-mini",
    max_loops=1,
    tools_list_dictionary=[stock_analysis_schema, portfolio_optimization_schema]
)

# Generate structured analysis
response = structured_agent.run(
    "Analyze Apple stock (AAPL) performance with comprehensive analysis for the last 3 months"
)
```

## Advanced Features

### Dynamic Temperature Control

```python
from swarms import Agent

# Agent with dynamic temperature adjustment
adaptive_agent = Agent(
    agent_name="Adaptive-Response-Agent",
    agent_description="Agent that adjusts response creativity based on context",
    system_prompt="You are an adaptive AI that adjusts your response style based on the task complexity.",
    model_name="gpt-4o-mini",
    dynamic_temperature_enabled=True,  # Enable adaptive temperature
    max_loops=1,
    output_type="str"
)
```

### Output Type Configurations

```python
# Different output type examples
json_agent = Agent(
    agent_name="JSON-Agent",
    system_prompt="Always respond in valid JSON format",
    output_type="json"
)

streaming_agent = Agent(
    agent_name="Streaming-Agent", 
    system_prompt="Provide detailed streaming responses",
    output_type="str-all-except-first"
)

final_only_agent = Agent(
    agent_name="Final-Only-Agent",
    system_prompt="Provide only the final result",
    output_type="final"
)
```


### Performance Optimization

```python
from swarms import Agent
import time

# Optimized agent configuration
optimized_agent = Agent(
    agent_name="Optimized-Agent",
    agent_description="Performance-optimized agent configuration",
    system_prompt="You are an efficient AI assistant optimized for performance.",
    model_name="gpt-4o-mini",  # Faster model
    max_loops=1,  # Minimize loops
    max_tokens=2048,  # Reasonable token limit
    temperature=0.5,  # Balanced creativity
    output_type="str"
)

# Batch processing example
def process_tasks_batch(agent, tasks, batch_size=5):
    """Process multiple tasks efficiently."""
    results = []
    for i in range(0, len(tasks), batch_size):
        batch = tasks[i:i + batch_size]
        batch_results = []
        
        for task in batch:
            start_time = time.time()
            result = agent.run(task)
            execution_time = time.time() - start_time
            
            batch_results.append({
                "task": task,
                "result": result,
                "execution_time": execution_time
            })
        
        results.extend(batch_results)
        time.sleep(1)  # Rate limiting
    
    return results
```

## Complete Examples

### Multi-Modal Quality Control System

```python
from swarms import Agent
from swarms.prompts.logistics import Quality_Control_Agent_Prompt

def security_analysis(danger_level: str) -> str:
    """Analyze security danger level and return appropriate response."""
    responses = {
        "low": "✅ No immediate danger detected - Safe to proceed",
        "medium": "⚠️ Moderate security concern - Requires attention",
        "high": "🚨 Critical security threat - Immediate action required",
        None: "❓ No danger level assessment available"
    }
    return responses.get(danger_level, "Unknown danger level")

def quality_assessment(quality_score: int) -> str:
    """Assess quality based on numerical score (1-10)."""
    if quality_score >= 8:
        return "✅ Excellent quality - Meets all standards"
    elif quality_score >= 6:
        return "⚠️ Good quality - Minor improvements needed"
    elif quality_score >= 4:
        return "❌ Poor quality - Significant issues identified"
    else:
        return "🚨 Critical quality failure - Immediate attention required"

# Advanced quality control agent
quality_control_system = Agent(
    agent_name="Advanced-Quality-Control-System",
    agent_description="Comprehensive quality control and security analysis system",
    system_prompt=f"""
    {Quality_Control_Agent_Prompt}
    
    You are an advanced quality control system with the following capabilities:
    
    1. Visual Inspection: Analyze images for defects, compliance, and safety
    2. Security Assessment: Identify potential security threats and hazards
    3. Quality Scoring: Provide numerical quality ratings (1-10 scale)
    4. Detailed Reporting: Generate comprehensive analysis reports
    
    When analyzing images:
    - Identify specific defects or issues
    - Assess compliance with safety standards
    - Determine appropriate danger levels (low, medium, high)
    - Provide quality scores and recommendations
    - Use available tools for detailed analysis
    
    Always provide specific, actionable feedback.
    """,
    model_name="gpt-4o-mini",
    multi_modal=True,
    max_loops=1,
    tools=[security_analysis, quality_assessment],
    output_type="str"
)

# Process factory images
factory_images = ["factory_floor.jpg", "assembly_line.jpg", "safety_equipment.jpg"]

for image in factory_images:
    print(f"\n--- Analyzing {image} ---")
    response = quality_control_system.run(
        task=f"Perform comprehensive quality control analysis of this image. Assess safety, quality, and provide specific recommendations.",
        img=image
    )
    print(response)
```

### Advanced Financial Analysis Agent

```python
from swarms import Agent
import json
import requests

def get_market_data(symbol: str, period: str = "1y") -> str:
    """Get comprehensive market data for a symbol."""
    # Simulated market data (replace with real API)
    market_data = {
        "symbol": symbol,
        "current_price": 150.25,
        "change_percent": 2.5,
        "volume": 1000000,
        "market_cap": 2500000000,
        "pe_ratio": 25.5,
        "dividend_yield": 1.8,
        "52_week_high": 180.50,
        "52_week_low": 120.30
    }
    return json.dumps(market_data, indent=2)

def calculate_risk_metrics(prices: list, benchmark_prices: list) -> str:
    """Calculate risk metrics for a portfolio."""
    import numpy as np
    
    try:
        returns = np.diff(prices) / prices[:-1]
        benchmark_returns = np.diff(benchmark_prices) / benchmark_prices[:-1]
        
        volatility = np.std(returns) * np.sqrt(252)  # Annualized
        sharpe_ratio = (np.mean(returns) / np.std(returns)) * np.sqrt(252)
        max_drawdown = np.max(np.maximum.accumulate(prices) - prices) / np.max(prices)
        
        beta = np.cov(returns, benchmark_returns)[0, 1] / np.var(benchmark_returns)
        
        risk_metrics = {
            "volatility": float(volatility),
            "sharpe_ratio": float(sharpe_ratio),
            "max_drawdown": float(max_drawdown),
            "beta": float(beta)
        }
        
        return json.dumps(risk_metrics, indent=2)
    
    except Exception as e:
        return json.dumps({"error": f"Risk calculation error: {str(e)}"})

# Financial analysis schemas
financial_analysis_schema = {
    "type": "function",
    "function": {
        "name": "comprehensive_financial_analysis",
        "description": "Perform comprehensive financial analysis with structured output",
        "parameters": {
            "type": "object",
            "properties": {
                "analysis_summary": {
                    "type": "object",
                    "properties": {
                        "overall_rating": {"type": "string", "enum": ["buy", "hold", "sell"]},
                        "confidence_level": {"type": "number", "minimum": 0, "maximum": 100},
                        "key_strengths": {"type": "array", "items": {"type": "string"}},
                        "key_concerns": {"type": "array", "items": {"type": "string"}},
                        "price_target": {"type": "number"},
                        "risk_level": {"type": "string", "enum": ["low", "medium", "high"]}
                    }
                },
                "technical_analysis": {
                    "type": "object",
                    "properties": {
                        "trend_direction": {"type": "string", "enum": ["bullish", "bearish", "neutral"]},
                        "support_levels": {"type": "array", "items": {"type": "number"}},
                        "resistance_levels": {"type": "array", "items": {"type": "number"}},
                        "momentum_indicators": {"type": "array", "items": {"type": "string"}}
                    }
                }
            },
            "required": ["analysis_summary", "technical_analysis"]
        }
    }
}

# Advanced financial agent
financial_analyst = Agent(
    agent_name="Advanced-Financial-Analyst",
    agent_description="Comprehensive financial analysis and investment advisory agent",
    system_prompt="""You are an expert financial analyst with advanced capabilities in:
    
    - Fundamental analysis and valuation
    - Technical analysis and chart patterns
    - Risk assessment and portfolio optimization
    - Market sentiment analysis
    - Economic indicator interpretation
    
    Your analysis should be:
    - Data-driven and objective
    - Risk-aware and practical
    - Clearly structured and actionable
    - Compliant with financial regulations
    
    Use available tools to gather market data and calculate risk metrics.
    Provide structured outputs using the defined schemas.""",
    model_name="gpt-4o-mini",
    max_loops=1,
    tools=[get_market_data, calculate_risk_metrics],
    tools_list_dictionary=[financial_analysis_schema],
    output_type="json"
)

# Comprehensive financial analysis
analysis_response = financial_analyst.run(
    "Perform a comprehensive analysis of Apple Inc. (AAPL) including technical and fundamental analysis with structured recommendations"
)

print(json.dumps(json.loads(analysis_response), indent=2))
```

### Multi-Agent Collaboration System

```python
from swarms import Agent
import json

# Specialized agents for different tasks
research_agent = Agent(
    agent_name="Research-Specialist",
    agent_description="Market research and data analysis specialist",
    system_prompt="You are a market research expert specializing in data collection and analysis.",
    model_name="gpt-4o-mini",
    max_loops=1,
    temperature=0.3
)

strategy_agent = Agent(
    agent_name="Strategy-Advisor", 
    agent_description="Strategic planning and recommendation specialist",
    system_prompt="You are a strategic advisor providing high-level recommendations based on research.",
    model_name="gpt-4o-mini",
    max_loops=1,
    temperature=0.5
)

execution_agent = Agent(
    agent_name="Execution-Planner",
    agent_description="Implementation and execution planning specialist", 
    system_prompt="You are an execution expert creating detailed implementation plans.",
    model_name="gpt-4o-mini",
    max_loops=1,
    temperature=0.4
)

def collaborative_analysis(topic: str):
    """Perform collaborative analysis using multiple specialized agents."""
    
    # Step 1: Research Phase
    research_task = f"Conduct comprehensive research on {topic}. Provide key findings, market data, and trends."
    research_results = research_agent.run(research_task)
    
    # Step 2: Strategy Phase
    strategy_task = f"Based on this research: {research_results}\n\nDevelop strategic recommendations for {topic}."
    strategy_results = strategy_agent.run(strategy_task)
    
    # Step 3: Execution Phase
    execution_task = f"Create a detailed implementation plan based on:\nResearch: {research_results}\nStrategy: {strategy_results}"
    execution_results = execution_agent.run(execution_task)
    
    return {
        "research": research_results,
        "strategy": strategy_results,
        "execution": execution_results
    }

# Example: Collaborative investment analysis
investment_analysis = collaborative_analysis("renewable energy sector investment opportunities")

for phase, results in investment_analysis.items():
    print(f"\n=== {phase.upper()} PHASE ===")
    print(results)
```

## Support and Resources

Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights!

| Platform | Description | Link |
|----------|-------------|------|
| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) |
| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) |
| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/EamjgSaEQf) |
| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) |
| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) |
| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) |
| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |

### Getting Help

If you encounter issues or need assistance:

1. **Check the Documentation**: Start with the official docs for comprehensive guides
2. **Search Issues**: Look through existing GitHub issues for similar problems
3. **Join Discord**: Get real-time help from the community
4. **Create an Issue**: Report bugs or request features on GitHub
5. **Follow Updates**: Stay informed about new releases and improvements

### Contributing

We welcome contributions! Here's how to get involved:

| Contribution Type        | Description                                      |
|-------------------------|--------------------------------------------------|
| **Report Bugs**         | Help us improve by reporting issues              |
| **Suggest Features**    | Share your ideas for new capabilities            |
| **Submit Code**         | Contribute improvements and new features         |
| **Improve Documentation** | Help make our docs better                      |
| **Share Examples**      | Show how you're using Swarms in your projects    |

---

*This guide covers the essential aspects of the Swarms Agent class. For the most up-to-date information and advanced features, please refer to the official documentation and community resources.*

--------------------------------------------------

# File: swarms/agents/iterative_agent.md

# Iterative Reflective Expansion (IRE) Algorithm Documentation

The Iterative Reflective Expansion (IRE) Algorithm is a sophisticated reasoning framework that employs iterative hypothesis generation, simulation, and refinement to solve complex problems. It leverages a multi-step approach where an AI agent generates initial solution paths, evaluates their effectiveness through simulation, reflects on errors, and dynamically revises reasoning strategies. Through continuous cycles of hypothesis testing and meta-cognitive reflection, the algorithm progressively converges on optimal solutions by learning from both successful and unsuccessful reasoning attempts.


## Architecture

```mermaid
graph TD
    Problem_Input["🧩 Problem Input"] --> Generate_Hypotheses
    Generate_Hypotheses["Generate Initial Hypotheses"] --> Simulate
    subgraph Iterative Reflective Expansion Loop
        Simulate["Simulate Reasoning Paths"] --> Evaluate
        Evaluate["Evaluate Outcomes"] --> Reflect{Is solution satisfactory?}
        Reflect -->|No, issues found| Meta_Reflect
        Reflect -->|Yes| Promising
        Meta_Reflect["Meta-Cognitive Reflection"] --> Revise_Paths
        Meta_Reflect --> Memory[(Reasoning Memory)]
        Meta_Reflect --> Memory
        Revise_Paths["Revise Paths Based on Feedback"] --> Expand_Paths
        Meta_Reflect --> Revise_Path
        Revise_Path["Revise Paths"] --> Expand_Paths
        Expand_Paths["Iterative Expansion & Pruning"] --> Simulate
    end
    Promising["Promising Paths Selected"] --> Memory
    Memory["Memory Integration"] --> Synthesize
    Synthesize["Synthesize Final Solution"] --> Final["Final Solution ✅"]

```

---

## Workflow

1. Generate initial hypotheses
2. Simulate paths
3. Reflect on errors
4. Revise paths
5. Select promising paths
6. Synthesize solution

## Class: IterativeReflectiveExpansion

### Arguments

| Argument       | Type   | Default | Description |
|----------------|--------|---------|-------------|
| agent          | Agent  | None    | The Swarms agent instance used to perform reasoning tasks. |
| max_iterations | int    | 5       | Maximum number of iterations for the reasoning process. |
| return_list    | bool   | False   | If True, returns the conversation as a list of messages. |
| return_dict    | bool   | False   | If True, returns the conversation as a dictionary of messages. |
| prompt         | str    | GENERAL_REASONING_AGENT_SYS_PROMPT | The system prompt for the agent. |

### Methods

| Method                        | Description |
|-------------------------------|-------------|
| generate_initial_hypotheses   | Generates an initial set of reasoning hypotheses based on the problem input. |
| simulate_path                 | Simulates a given reasoning path and evaluates its effectiveness. |
| meta_reflect                  | Performs meta-cognitive reflection on the provided error information. |
| revise_path                   | Revises the reasoning path based on the provided feedback. |
| select_promising_paths        | Selects the most promising reasoning paths from a list of candidates. |
| synthesize_solution           | Synthesizes a final solution from the promising reasoning paths and historical memory. |
| run                           | Executes the Iterative Reflective Expansion process on the provided problem. |

## Use-Cases

### Example 1: Solving a Mathematical Problem

```python
from swarms import IterativeReflectiveExpansion

agent = IterativeReflectiveExpansion(
    max_iterations=3,
)

agent.run("What is the 40th prime number?")
```

## Conclusion

The Iterative Reflective Expansion (IRE) Algorithm is a powerful tool for solving complex problems through iterative reasoning and reflection. By leveraging the capabilities of a Swarms agent, it can dynamically adapt and refine its approach to converge on optimal solutions.


--------------------------------------------------

# File: swarms/agents/message.md

# The Module/Class Name: Message

In the swarms.agents framework, the class `Message` is used to represent a message with timestamp and optional metadata.

## Overview and Introduction

The `Message` class is a fundamental component that enables the representation of messages within an agent system. Messages contain essential information such as the sender, content, timestamp, and optional metadata.

## Class Definition

### Constructor: `__init__`

The constructor of the `Message` class takes three parameters:

1. `sender` (str): The sender of the message.
2. `content` (str): The content of the message.
3. `metadata` (dict or None): Optional metadata associated with the message.

### Methods

1. `__repr__(self)`: Returns a string representation of the `Message` object, including the timestamp, sender, and content.

```python
class Message:
    """
    Represents a message with timestamp and optional metadata.

    Usage
    --------------
    mes = Message(
        sender = "Kye",
        content = "message"
    )

    print(mes)
    """

    def __init__(self, sender, content, metadata=None):
        self.timestamp = datetime.datetime.now()
        self.sender = sender
        self.content = content
        self.metadata = metadata or {}

    def __repr__(self):
        """
        __repr__ represents the string representation of the Message object.

        Returns:
        (str) A string containing the timestamp, sender, and content of the message.
        """
        return f"{self.timestamp} - {self.sender}: {self.content}"
```

## Functionality and Usage

The `Message` class represents a message in the agent system. Upon initialization, the `timestamp` is set to the current date and time, and the `metadata` is set to an empty dictionary if no metadata is provided.

### Usage Example 1

Creating a `Message` object and displaying its string representation.

```python
mes = Message(sender="Kye", content="Hello! How are you?")

print(mes)
```

Output:
```
2023-09-20 13:45:00 - Kye: Hello! How are you?
```

### Usage Example 2

Creating a `Message` object with metadata.

```python
metadata = {"priority": "high", "category": "urgent"}
mes_with_metadata = Message(
    sender="Alice", content="Important update", metadata=metadata
)

print(mes_with_metadata)
```

Output:
```
2023-09-20 13:46:00 - Alice: Important update
```

### Usage Example 3

Creating a `Message` object without providing metadata.

```python
mes_no_metadata = Message(sender="Bob", content="Reminder: Meeting at 2PM")

print(mes_no_metadata)
```

Output:
```
2023-09-20 13:47:00 - Bob: Reminder: Meeting at 2PM
```

## Additional Information and Tips

When creating a new `Message` object, ensure that the required parameters `sender` and `content` are provided. The `timestamp` will automatically be assigned the current date and time. Optional `metadata` can be included to provide additional context or information associated with the message.

## References and Resources

For further information on the `Message` class and its usage, refer to the official swarms.agents documentation and relevant tutorials related to message handling and communication within the agent system.


--------------------------------------------------

# File: swarms/agents/new_agent.md

# How to Create Good Agents

This guide will walk you through the steps to build high-quality agents by extending the `Agent` class. It emphasizes best practices, the use of type annotations, comprehensive documentation, and modular design to ensure maintainability and scalability. Additionally, you will learn how to incorporate a callable `llm` parameter or specify a `model_name` attribute to enhance flexibility and functionality. These principles ensure that agents are not only functional but also robust and adaptable to future requirements.

## Overview

A good agent is a modular and reusable component designed to perform specific tasks efficiently. By inheriting from the base `Agent` class, developers can extend its functionality while adhering to standardized principles. Each custom agent should:

- Inherit from the `Agent` class to maintain compatibility with swarms.
- Define a `run(task: str, img: str)` method to execute tasks effectively.
- Include descriptive attributes such as `name`, `system_prompt`, and `description` to enhance clarity.
- Optionally, include an `llm` parameter (callable) or a `model_name` to enable seamless integration with language models.
- Emphasize modularity, allowing the agent to be reused across various contexts and tasks.

By following these guidelines, you can create agents that integrate well with broader systems and exhibit high reliability in real-world applications.

---

## Creating a Custom Agent

Here is a detailed template for creating a custom agent by inheriting the `Agent` class. This template demonstrates how to structure an agent with extendable and reusable features:

```python
from typing import Callable, Any
from swarms import Agent

class MyNewAgent(Agent):
    """
    A custom agent class for specialized tasks.

    Attributes:
        name (str): The name of the agent.
        system_prompt (str): The prompt guiding the agent's behavior.
        description (str): A brief description of the agent's purpose.
        llm (Callable, optional): A callable representing the language model to use.
    """

    def __init__(self, name: str, system_prompt: str, model_name: str = None, description: str, llm: Callable = None):
        """
        Initialize the custom agent.

        Args:
            name (str): The name of the agent.
            system_prompt (str): The prompt guiding the agent.
            model_name (str): The name of your model can use litellm [openai/gpt-4o]
            description (str): A description of the agent's purpose.
            llm (Callable, optional): A callable representing the language model to use.
        """
        super().__init__(agent_name=name, system_prompt=system_prompt, model_name=model_name)
        self.agent_name = agent_name
        self.system_prompt system_prompt
        self.description = description
        self.model_name = model_name

    def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any:
        """
        Execute the task assigned to the agent.

        Args:
            task (str): The task description.
            img (str): The image input for processing.
            *args: Additional positional arguments.
            **kwargs: Additional keyword arguments.

        Returns:
            Any: The result of the task execution.
        """
        # Your custom logic 
        ...
```

This design ensures a seamless extension of functionality while maintaining clear and maintainable code.

---

## Key Considerations

### 1. **Type Annotations**
Always use type hints for method parameters and return values. This improves code readability, supports static analysis tools, and reduces bugs, ensuring long-term reliability.

### 2. **Comprehensive Documentation**
Provide detailed docstrings for all classes, methods, and attributes. Clear documentation ensures that your agent's functionality is understandable to both current and future collaborators.

### 3. **Modular Design**
Keep the agent logic modular and reusable. Modularity simplifies debugging, testing, and extending functionalities, making the code more adaptable to diverse scenarios.

### 4. **Flexible Model Integration**
Use either an `llm` callable or `model_name` attribute for integrating language models. This flexibility ensures your agent can adapt to various tasks, environments, and system requirements.

### 5. **Error Handling**
Incorporate robust error handling to manage unexpected inputs or issues during execution. This not only ensures reliability but also builds user trust in your system.

### 6. **Scalability Considerations**
Ensure your agent design can scale to accommodate increased complexity or a larger number of tasks without compromising performance.

---

## Example Usage

Here is an example of how to use your custom agent effectively:

```python
# Example LLM callable
class MockLLM:
    """
    A mock language model class for simulating LLM behavior.

    Methods:
        run(task: str, img: str, *args: Any, **kwargs: Any) -> str:
            Processes the task and image input to return a simulated response.
    """

    def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> str:
        return f"Processed task '{task}' with image '{img}'"

# Create an instance of MyNewAgent
agent = MyNewAgent(
    name="ImageProcessor",
    system_prompt="Process images and extract relevant details.",
    description="An agent specialized in processing images and extracting insights.",
    llm=MockLLM().run
)

# Run a task
result = agent.run(task="Analyze content", img="path/to/image.jpg")
print(result)
```

This example showcases the practical application of the `MyNewAgent` class and highlights its extensibility.


## Production-Grade Example with **Griptape Agent Integration Example**

In this example, we will create a **Griptape** agent by inheriting from the Swarms `Agent` class and implementing the `run` method.

### **Griptape Integration Steps**:

1. **Inherit from Swarms Agent**: Inherit from the `SwarmsAgent` class.
2. **Create Griptape Agent**: Initialize the **Griptape** agent inside your class and provide it with the necessary tools.
3. **Override the `run()` method**: Implement logic to process a task string and execute the Griptape agent.

## **Griptape Example Code**:

```python
from swarms import (
    Agent as SwarmsAgent,
)  # Import the base Agent class from Swarms
from griptape.structures import Agent as GriptapeAgent
from griptape.tools import (
    WebScraperTool,
    FileManagerTool,
    PromptSummaryTool,
)

# Create a custom agent class that inherits from SwarmsAgent
class GriptapeSwarmsAgent(SwarmsAgent):
    def __init__(self, name: str, system_prompt: str: str, *args, **kwargs):
        super().__init__(agent_name=name, system_prompt=system_prompt)
        # Initialize the Griptape agent with its tools
        self.agent = GriptapeAgent(
            input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.",
            tools=[
                WebScraperTool(off_prompt=True),
                PromptSummaryTool(off_prompt=True),
                FileManagerTool(),
            ],
            *args,
            **kwargs,
        )

    # Override the run method to take a task and execute it using the Griptape agent
    def run(self, task: str) -> str:
        # Extract URL and filename from task
        url, filename = task.split(",")  # Example task string: "https://example.com, output.txt"
        # Execute the Griptape agent
        result = self.agent.run(url.strip(), filename.strip())
        # Return the final result as a string
        return str(result)


# Example usage:
griptape_swarms_agent = GriptapeSwarmsAgent()
output = griptape_swarms_agent.run("https://griptape.ai, griptape.txt")
print(output)
```


---

## Best Practices

1. **Test Extensively:**
   Validate your agent with various task inputs to ensure it performs as expected under different conditions.

2. **Follow the Single Responsibility Principle:**
   Design each agent to focus on a specific task or role, ensuring clarity and modularity in implementation.

3. **Log Actions:**
   Include detailed logging within the `run` method to capture key actions, inputs, and results for debugging and monitoring.

4. **Use Open-Source Contributions:**
   Contribute your custom agents to the Swarms repository at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms). Sharing your innovations helps advance the ecosystem and encourages collaboration.

5. **Iterate and Refactor:**
   Continuously improve your agents based on feedback, performance evaluations, and new requirements to maintain relevance and functionality.

---

## Conclusion

By following these guidelines, you can create powerful and flexible agents tailored to specific tasks. Leveraging inheritance from the `Agent` class ensures compatibility and standardization across swarms. Emphasize modularity, thorough testing, and clear documentation to build agents that are robust, scalable, and easy to integrate. Collaborate with the community by submitting your innovative agents to the Swarms repository, contributing to a growing ecosystem of intelligent solutions. With a well-designed agent, you are equipped to tackle diverse challenges efficiently and effectively.



--------------------------------------------------

# File: swarms/agents/openai_assistant.md

# OpenAI Assistant

The OpenAI Assistant class provides a wrapper around OpenAI's Assistants API, integrating it with the swarms framework.

## Overview

The `OpenAIAssistant` class allows you to create and interact with OpenAI Assistants, providing a simple interface for:

- Creating assistants with specific roles and capabilities
- Adding custom functions that the assistant can call
- Managing conversation threads
- Handling tool calls and function execution
- Getting responses from the assistant

## Insstallation

```bash
pip install swarms
```
## Basic Usage

```python

from swarms import OpenAIAssistant

#Create an assistant
assistant = OpenAIAssistant(
    name="Math Tutor",
    instructions="You are a helpful math tutor.",
    model="gpt-4o",
    tools=[{"type": "code_interpreter"}]
)

#Run a Task
response = assistant.run("Solve the equation: 3x + 11 = 14")
print(response)

# Continue the conversation in the same thread
follow_up = assistant.run("Now explain how you solved it")
print(follow_up)
```

## Function Calling

The assistant supports custom function integration:

```python

def get_weather(location: str, unit: str = "celsius") -> str:
    # Mock weather function
    return f"The weather in {location} is 22 degrees {unit}"

# Add function to assistant
assistant.add_function(
    description="Get the current weather in a location",
    parameters={
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City name"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "default": "celsius"
            }
        },
        "required": ["location"]
    }
)
```

## API Reference

### Constructor

```python
OpenAIAssistant(
    name: str,
    instructions: Optional[str] = None,
    model: str = "gpt-4o",
    tools: Optional[List[Dict[str, Any]]] = None,
    file_ids: Optional[List[str]] = None,
    metadata: Optional[Dict[str, Any]] = None,
    functions: Optional[List[Dict[str, Any]]] = None,
)
```

### Methods

#### run(task: str) -> str
Sends a task to the assistant and returns its response. The conversation thread is maintained between calls.

#### add_function(func: Callable, description: str, parameters: Dict[str, Any]) -> None
Adds a callable function that the assistant can use during conversations.

#### add_message(content: str, file_ids: Optional[List[str]] = None) -> None
Adds a message to the current conversation thread.

## Error Handling

The assistant implements robust error handling:
- Retries on rate limits
- Graceful handling of API errors
- Clear error messages for debugging
- Status monitoring for runs and completions

## Best Practices

1. Thread Management
   - Use the same assistant instance for related conversations
   - Create new instances for unrelated tasks
   - Monitor thread status during long-running operations

2. Function Integration
   - Keep functions simple and focused
   - Provide clear descriptions and parameter schemas
   - Handle errors gracefully in custom functions
   - Test functions independently before integration

3. Performance
   - Reuse assistant instances when possible
   - Monitor and handle rate limits appropriately
   - Use appropriate polling intervals for status checks
   - Consider implementing timeouts for long-running operations

## References

- [OpenAI Assistants API Documentation](https://platform.openai.com/docs/assistants/overview)
- [OpenAI Function Calling Guide](https://platform.openai.com/docs/guides/function-calling)
- [OpenAI Rate Limits](https://platform.openai.com/docs/guides/rate-limits)





--------------------------------------------------

# File: swarms/agents/reasoning_agent_router.md

# ReasoningAgentRouter

!!! abstract "Overview"
    The ReasoningAgentRouter is a sophisticated agent routing system that enables dynamic selection and execution of different reasoning strategies based on the task requirements. It provides a flexible interface to work with multiple reasoning approaches including Reasoning Duo, Self-Consistency, IRE (Iterative Reflective Expansion), Reflexion, GKP (Generated Knowledge Prompting), and Agent Judge.

## Architecture

```mermaid
graph TD
    Task[Task Input] --> Router[ReasoningAgentRouter]
    Router --> SelectSwarm{Select Swarm Type}
    SelectSwarm -->|Reasoning Duo| RD[ReasoningDuo]
    SelectSwarm -->|Self Consistency| SC[SelfConsistencyAgent]
    SelectSwarm -->|IRE| IRE[IterativeReflectiveExpansion]
    SelectSwarm -->|Reflexion| RF[ReflexionAgent]
    SelectSwarm -->|GKP| GKP[GKPAgent]
    SelectSwarm -->|Agent Judge| AJ[AgentJudge]
    RD --> Output[Task Output]
    SC --> Output
    IRE --> Output
    RF --> Output
    GKP --> Output
    AJ --> Output
```

## Configuration

### Arguments

!!! info "Constructor Parameters"

    | Argument | Type | Default | Description |
    |----------|------|---------|-------------|
    | `agent_name` | str | "reasoning_agent" | Name identifier for the agent |
    | `description` | str | "A reasoning agent..." | Description of the agent's capabilities |
    | `model_name` | str | "gpt-4o-mini" | The underlying language model to use |
    | `system_prompt` | str | "You are a helpful..." | System prompt for the agent |
    | `max_loops` | int | 1 | Maximum number of reasoning loops |
    | `swarm_type` | agent_types | "reasoning_duo" | Type of reasoning swarm to use |
    | `num_samples` | int | 1 | Number of samples for self-consistency |
    | `output_type` | OutputType | "dict-all-except-first" | Format of the output |
    | `num_knowledge_items` | int | 6 | Number of knowledge items for GKP agent |
    | `memory_capacity` | int | 6 | Memory capacity for agents that support it |
    | `eval` | bool | False | Enable evaluation mode for self-consistency |
    | `random_models_on` | bool | False | Enable random model selection for diversity |
    | `majority_voting_prompt` | Optional[str] | None | Custom prompt for majority voting |
    | `reasoning_model_name` | Optional[str] | "claude-3-5-sonnet-20240620" | Model to use for reasoning in ReasoningDuo |

### Available Agent Types

!!! note "Supported Types"
    The following agent types are supported through the `swarm_type` parameter:

    - `"reasoning-duo"` or `"reasoning-agent"`
    - `"self-consistency"` or `"consistency-agent"` 
    - `"ire"` or `"ire-agent"`
    - `"ReflexionAgent"`
    - `"GKPAgent"`
    - `"AgentJudge"`

### Agent Types Comparison

=== "Reasoning Duo"
    **Key Features**
    
    - Dual agent system
    - Collaborative reasoning
    - Split between reasoning and execution
    
    **Best Use Cases**
    
    - Complex tasks requiring both analysis and action
    - Multi-step problem solving
    - Tasks needing verification
    
    **Required Parameters**
    
    - model_name
    - system_prompt
    
    **Optional Parameters**
    
    - output_type
    - reasoning_model_name (default: "claude-3-5-sonnet-20240620")
    - max_loops
    - img (for image input support)

=== "Self Consistency"
    **Key Features**
    
    - Multiple solution generation
    - Consensus building
    - Solution verification
    - Concurrent execution
    - AI-powered aggregation
    
    **Best Use Cases**
    
    - Tasks requiring high reliability
    - Problems with multiple approaches
    - Validation-heavy tasks
    - Mathematical problem solving
    - Decision making scenarios
    
    **Required Parameters**
    
    - model_name
    - system_prompt
    
    **Optional Parameters**
    
    - num_samples (default: 5)
    - max_loops (default: 1)
    - output_type (default: "dict")
    - eval (default: False) - Enable answer validation
    - random_models_on (default: False) - Enable model diversity
    - majority_voting_prompt (default: None) - Custom aggregation prompt

=== "IRE"
    **Key Features**
    
    - Iterative improvement
    - Self-reflection
    - Progressive refinement
    
    **Best Use Cases**
    
    - Complex reasoning tasks
    - Problems requiring refinement
    - Learning from previous iterations
    
    **Required Parameters**
    
    - model_name
    - system_prompt
    
    **Optional Parameters**
    
    - max_loops
    - max_iterations
    - output_type

=== "ReflexionAgent"
    **Key Features**
    
    - Self-reflection capabilities
    - Learning from experience
    - Adaptive reasoning
    
    **Best Use Cases**
    
    - Tasks requiring introspection
    - Continuous improvement scenarios
    - Learning-based tasks
    
    **Required Parameters**
    
    - model_name
    - system_prompt
    
    **Optional Parameters**
    
    - max_loops

=== "GKPAgent"
    **Key Features**
    
    - Knowledge generation
    - Information synthesis
    - Knowledge base management
    
    **Best Use Cases**
    
    - Knowledge-intensive tasks
    - Information gathering
    - Research-based problems
    
    **Required Parameters**
    
    - model_name
    - num_knowledge_items
    
    **Optional Parameters**
    
    - memory_capacity

=== "AgentJudge"
    **Key Features**
    
    - Solution evaluation
    - Quality assessment
    - Decision making
    
    **Best Use Cases**
    
    - Quality control tasks
    - Solution validation
    - Performance evaluation
    
    **Required Parameters**
    
    - model_name
    - system_prompt
    
    **Optional Parameters**
    
    - max_loops

## Usage

### Methods

!!! tip "Available Methods"
    | Method | Description |
    |--------|-------------|
    | `select_swarm()` | Selects and initializes the appropriate reasoning swarm based on specified type |
    | `run(task: str, img: Optional[str] = None, **kwargs)` | Executes the selected swarm's reasoning process on the given task |
    | `batched_run(tasks: List[str], imgs: Optional[List[str]] = None, **kwargs)` | Executes the reasoning process on a batch of tasks |

### Image Support

!!! info "Multi-modal Capabilities"
    The ReasoningAgentRouter supports image inputs for compatible agent types:

    **Supported Parameters:**
    
    - `img` (str, optional): Path or URL to a single image file for single task execution
    - `imgs` (List[str], optional): List of image paths/URLs for batch task execution

    **Compatible Agent Types:**
    
    - `reasoning-duo` / `reasoning-agent`: Full image support for both reasoning and execution phases
    - Other agent types may have varying levels of image support depending on their underlying implementation

    **Usage Example:**
    ```python
    # Single image with task
    router = ReasoningAgentRouter(swarm_type="reasoning-duo")
    result = router.run(
        task="Describe what you see in this image",
        img="path/to/image.jpg"
    )

    # Batch processing with images
    results = router.batched_run(
        tasks=["Analyze this chart", "Describe this photo"],
        imgs=["chart.png", "photo.jpg"]
    )
    ```

### Code Examples

=== "Basic Usage"
    ```python
    from swarms.agents.reasoning_agents import ReasoningAgentRouter

    # Initialize the router
    router = ReasoningAgentRouter(
        agent_name="reasoning-agent",
        description="A reasoning agent that can answer questions and help with tasks.",
        model_name="gpt-4o-mini",
        system_prompt="You are a helpful assistant that can answer questions and help with tasks.",
        max_loops=1,
        swarm_type="self-consistency",
        num_samples=3,
        eval=False,
        random_models_on=False,
        majority_voting_prompt=None
    )

    # Run a single task
    result = router.run("What is the best approach to solve this problem?")
    
    # Run with image input
    result_with_image = router.run(
        "Analyze this image and provide insights",
        img="path/to/image.jpg"
    )
    ```

=== "Self-Consistency Examples"
    ```python
    # Basic self-consistency
    router = ReasoningAgentRouter(
        swarm_type="self-consistency",
        num_samples=3,
        model_name="gpt-4o-mini"
    )
    
    # Self-consistency with evaluation mode
    router = ReasoningAgentRouter(
        swarm_type="self-consistency",
        num_samples=5,
        model_name="gpt-4o-mini",
        eval=True,
        random_models_on=True
    )
    
    # Self-consistency with custom majority voting
    router = ReasoningAgentRouter(
        swarm_type="self-consistency",
        num_samples=3,
        model_name="gpt-4o-mini",
        majority_voting_prompt="Analyze the responses and provide the most accurate answer."
    )
    ```

=== "ReflexionAgent"
    ```python
    router = ReasoningAgentRouter(
        swarm_type="ReflexionAgent",
        max_loops=3,
        model_name="gpt-4o-mini"
    )
    ```

=== "GKPAgent"
    ```python
    router = ReasoningAgentRouter(
        swarm_type="GKPAgent",
        model_name="gpt-4o-mini",
        num_knowledge_items=6
    )
    ```

=== "ReasoningDuo Examples"
    ```python
    # Basic ReasoningDuo
    router = ReasoningAgentRouter(
        swarm_type="reasoning-duo",
        model_name="gpt-4o-mini",
        reasoning_model_name="claude-3-5-sonnet-20240620"
    )
    
    # ReasoningDuo with image support
    router = ReasoningAgentRouter(
        swarm_type="reasoning-duo",
        model_name="gpt-4o-mini",
        reasoning_model_name="gpt-4-vision-preview",
        max_loops=2
    )
    
    result = router.run(
        "Analyze this image and explain the patterns you see",
        img="data_visualization.png"
    )
    ```

=== "AgentJudge"
    ```python
    router = ReasoningAgentRouter(
        swarm_type="AgentJudge",
        model_name="gpt-4o-mini",
        max_loops=2
    )
    ```

## Best Practices

!!! tip "Optimization Tips"
    1. **Swarm Type Selection**
        - Use ReasoningDuo for tasks requiring both analysis and action
        
        - Use SelfConsistency for tasks requiring high reliability
        
        - Use IRE for complex problem-solving requiring iterative refinement

    2. **Performance Optimization**
        - Adjust max_loops based on task complexity
        
        - Increase num_samples for higher reliability (3-7 for most tasks)
        
        - Choose appropriate model_name based on task requirements
        
        - Enable random_models_on for diverse reasoning approaches
        
        - Use eval mode for validation tasks with known answers

    3. **Output Handling**
        - Use appropriate output_type for your needs
        
        - Process batched results appropriately
        
        - Handle errors gracefully
        
    4. **Self-Consistency Specific**
        - Use 3-5 samples for most tasks, 7+ for critical decisions
        
        - Enable eval mode when you have expected answers for validation
        
        - Customize majority_voting_prompt for domain-specific aggregation
        
        - Consider random_models_on for diverse model perspectives

    5. **Multi-modal and Reasoning Configuration**
        - Use vision-capable models when processing images (e.g., "gpt-4-vision-preview")
        
        - For ReasoningDuo, set different models for reasoning vs execution via reasoning_model_name
        
        - Ensure image paths are accessible and in supported formats (JPG, PNG, etc.)
        
        - Consider using reasoning_model_name with specialized reasoning models for complex tasks

## Limitations

!!! warning "Known Limitations"
    1. Processing time increases with:
        - Higher num_samples
        
        - Larger max_loops
        
        - More complex tasks

    2. Model-specific limitations based on:
        - Token limits
        
        - Model capabilities
        
        - API rate limits

## Contributing

!!! note "Development Guidelines"
    When extending the ReasoningAgentRouter:
    
    1. Follow the existing swarm interface
    2. Add comprehensive tests
    3. Update documentation
    4. Maintain error handling


--------------------------------------------------

# File: swarms/agents/reasoning_agents_overview.md

# Reasoning Agents Overview


Reasoning agents are sophisticated agents that employ advanced cognitive strategies to improve problem-solving performance beyond standard language model capabilities. Unlike traditional prompt-based approaches, reasoning agents implement structured methodologies that enable them to think more systematically, self-reflect, collaborate, and iteratively refine their responses.

These agents are inspired by cognitive science and human reasoning processes, incorporating techniques such as:

- **Multi-step reasoning**: Breaking down complex problems into manageable components

- **Self-reflection**: Evaluating and critiquing their own outputs

- **Iterative refinement**: Progressively improving solutions through multiple iterations

- **Collaborative thinking**: Using multiple reasoning pathways or agent perspectives

- **Memory integration**: Learning from past experiences and building knowledge over time

- **Meta-cognitive awareness**: Understanding their own thinking processes and limitations




## Available Reasoning Agents

| Agent Name | Type | Research Paper | Key Features | Best Use Cases | Implementation | Documentation |
|------------|------|----------------|---------------|----------------|----------------|---------------|
| **Self-Consistency Agent** | Consensus-based | [Self-Consistency Improves Chain of Thought Reasoning](https://arxiv.org/abs/2203.07870) (Wang et al., 2022) | • Multiple independent reasoning paths<br/>• Majority voting aggregation<br/>• Concurrent execution<br/>• Validation mode | • Mathematical problem solving<br/>• High-accuracy requirements<br/>• Decision making scenarios<br/>• Answer validation | `SelfConsistencyAgent` | [Guide](consistency_agent.md) |
| **Reasoning Duo** | Collaborative | Novel dual-agent architecture | • Separate reasoning and execution agents<br/>• Collaborative problem solving<br/>• Task decomposition<br/>• Cross-validation | • Complex analysis tasks<br/>• Multi-step problem solving<br/>• Tasks requiring verification<br/>• Research and planning | `ReasoningDuo` | [Guide](reasoning_duo.md) |
| **IRE Agent** | Iterative | Iterative Reflective Expansion framework | • Hypothesis generation<br/>• Path simulation<br/>• Error reflection<br/>• Dynamic revision | • Complex reasoning tasks<br/>• Research problems<br/>• Learning scenarios<br/>• Strategy development | `IterativeReflectiveExpansion` | [Guide](iterative_agent.md) |
| **Reflexion Agent** | Self-reflective | [Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366) (Shinn et al., 2023) | • Self-evaluation<br/>• Experience memory<br/>• Adaptive improvement<br/>• Learning from failures | • Continuous improvement tasks<br/>• Long-term projects<br/>• Learning scenarios<br/>• Quality refinement | `ReflexionAgent` | [Guide](reflexion_agent.md) |
| **GKP Agent** | Knowledge-based | [Generated Knowledge Prompting](https://arxiv.org/abs/2110.08387) (Liu et al., 2022) | • Knowledge generation<br/>• Multi-perspective reasoning<br/>• Information synthesis<br/>• Fact integration | • Knowledge-intensive tasks<br/>• Research questions<br/>• Fact-based reasoning<br/>• Information synthesis | `GKPAgent` | [Guide](gkp_agent.md) |
| **Agent Judge** | Evaluation | [Agent-as-a-Judge: Evaluate Agents with Agents](https://arxiv.org/abs/2410.10934) | • Quality assessment<br/>• Structured evaluation<br/>• Performance metrics<br/>• Feedback generation | • Quality control<br/>• Output evaluation<br/>• Performance assessment<br/>• Model comparison | `AgentJudge` | [Guide](agent_judge.md) |
| **REACT Agent** | Action-based | [ReAct: Synergizing Reasoning and Acting](https://arxiv.org/abs/2210.03629) (Yao et al., 2022) | • Reason-Act-Observe cycle<br/>• Memory integration<br/>• Action planning<br/>• Experience building | • Interactive tasks<br/>• Tool usage scenarios<br/>• Planning problems<br/>• Learning environments | `ReactAgent` | [Guide](react_agent.md) |

## Agent Architectures

### Self-Consistency Agent

**Description**: Implements multiple independent reasoning paths with consensus-building to improve response reliability and accuracy through majority voting mechanisms.

**Key Features**:

- Concurrent execution of multiple reasoning instances

- AI-powered aggregation and consensus analysis

- Validation mode for answer verification

- Configurable sample sizes and output formats


**Architecture Diagram**:

```mermaid
graph TD
    A[Task Input] --> B[Agent Pool]
    B --> C[Response 1]
    B --> D[Response 2]
    B --> E[Response 3]
    B --> F[Response N]
    C --> G[Aggregation Agent]
    D --> G
    E --> G
    F --> G
    G --> H[Majority Voting Analysis]
    H --> I[Consensus Evaluation]
    I --> J[Final Answer]
    
    style A fill:#e1f5fe
    style J fill:#c8e6c9
    style G fill:#fff3e0
```

**Use Cases**: Mathematical problem solving, high-stakes decision making, answer validation, quality assurance processes

**Implementation**: `SelfConsistencyAgent`

**Documentation**: [Self-Consistency Agent Guide](consistency_agent.md)

---

### Reasoning Duo

**Description**: Dual-agent collaborative system that separates reasoning and execution phases, enabling specialized analysis and task completion through coordinated agent interaction.

**Key Features**:

- Separate reasoning and execution agents

- Collaborative problem decomposition

- Cross-validation between agents

- Configurable model selection for each agent


**Architecture Diagram**:

```mermaid
graph TD
    A[Task Input] --> B[Reasoning Agent]
    B --> C[Deep Analysis]
    C --> D[Strategy Planning]
    D --> E[Reasoning Output]
    E --> F[Main Agent]
    F --> G[Task Execution]
    G --> H[Response Generation]
    H --> I[Final Output]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style F fill:#e8f5e8
    style I fill:#c8e6c9
```

**Use Cases**: Complex analysis tasks, multi-step problem solving, research and planning, verification workflows

**Implementation**: `ReasoningDuo`

**Documentation**: [Reasoning Duo Guide](reasoning_duo.md)

---

### IRE Agent (Iterative Reflective Expansion)

**Description**: Sophisticated reasoning framework employing iterative hypothesis generation, simulation, and refinement through continuous cycles of testing and meta-cognitive reflection.

**Key Features**:

- Hypothesis generation and testing

- Path simulation and evaluation

- Meta-cognitive reflection capabilities

- Dynamic strategy revision based on feedback


**Architecture Diagram**:

```mermaid
graph TD
    A[Problem Input] --> B[Hypothesis Generation]
    B --> C[Path Simulation]
    C --> D[Outcome Evaluation]
    D --> E{Satisfactory?}
    E -->|No| F[Meta-Cognitive Reflection]
    F --> G[Path Revision]
    G --> H[Knowledge Integration]
    H --> C
    E -->|Yes| I[Solution Synthesis]
    I --> J[Final Answer]
    
    style A fill:#e1f5fe
    style F fill:#fff3e0
    style J fill:#c8e6c9
```

**Use Cases**: Complex reasoning tasks, research problems, strategy development, iterative learning scenarios

**Implementation**: `IterativeReflectiveExpansion`

**Documentation**: [IRE Agent Guide](iterative_agent.md)

---

### Reflexion Agent

**Description**: Advanced self-reflective system implementing actor-evaluator-reflector architecture for continuous improvement through experience-based learning and memory integration.

**Key Features**:

- Actor-evaluator-reflector sub-agent architecture

- Self-evaluation and quality assessment

- Experience memory and learning capabilities

- Adaptive improvement through reflection


**Architecture Diagram**:

```mermaid
graph TD
    A[Task Input] --> B[Actor Agent]
    B --> C[Initial Response]
    C --> D[Evaluator Agent]
    D --> E[Quality Assessment]
    E --> F[Performance Score]
    F --> G[Reflector Agent]
    G --> H[Self-Reflection]
    H --> I[Experience Memory]
    I --> J{Max Iterations?}
    J -->|No| K[Refined Response]
    K --> D
    J -->|Yes| L[Final Response]
    
    style A fill:#e1f5fe
    style B fill:#e8f5e8
    style D fill:#fff3e0
    style G fill:#f3e5f5
    style L fill:#c8e6c9
```

**Use Cases**: Continuous improvement tasks, long-term projects, adaptive learning, quality refinement processes

**Implementation**: `ReflexionAgent`

**Documentation**: [Reflexion Agent Guide](reflexion_agent.md)

---

### GKP Agent (Generated Knowledge Prompting)

**Description**: Knowledge-driven reasoning system that generates relevant information before answering queries, implementing multi-perspective analysis through coordinated knowledge synthesis.

**Key Features**:

- Dynamic knowledge generation

- Multi-perspective reasoning coordination

- Information synthesis and integration

- Configurable knowledge item generation


**Architecture Diagram**:

```mermaid
graph TD
    A[Query Input] --> B[Knowledge Generator]
    B --> C[Generate Knowledge Item 1]
    B --> D[Generate Knowledge Item 2]
    B --> E[Generate Knowledge Item N]
    C --> F[Reasoner Agent]
    D --> F
    E --> F
    F --> G[Knowledge Integration]
    G --> H[Reasoning Process]
    H --> I[Response Generation]
    I --> J[Coordinator]
    J --> K[Final Answer]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style F fill:#e8f5e8
    style J fill:#f3e5f5
    style K fill:#c8e6c9
```

**Use Cases**: Knowledge-intensive tasks, research questions, fact-based reasoning, information synthesis

**Implementation**: `GKPAgent`

**Documentation**: [GKP Agent Guide](gkp_agent.md)

---

### Agent Judge

**Description**: Specialized evaluation system for assessing agent outputs and system performance, providing structured feedback and quality metrics through comprehensive assessment frameworks.

**Key Features**:

- Structured evaluation methodology

- Quality assessment and scoring

- Performance metrics generation

- Configurable evaluation criteria


**Architecture Diagram**:

```mermaid
graph TD
    A[Output to Evaluate] --> B[Evaluation Criteria]
    A --> C[Judge Agent]
    B --> C
    C --> D[Quality Analysis]
    D --> E[Criteria Assessment]
    E --> F[Scoring Framework]
    F --> G[Feedback Generation]
    G --> H[Evaluation Report]
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style H fill:#c8e6c9
```

**Use Cases**: Quality control, output evaluation, performance assessment, model comparison

**Implementation**: `AgentJudge`

**Documentation**: [Agent Judge Guide](agent_judge.md)

---

### REACT Agent (Reason-Act-Observe)

**Description**: Action-oriented reasoning system implementing iterative reason-act-observe cycles with memory integration for interactive task completion and environmental adaptation.

**Key Features**:

- Reason-Act-Observe cycle implementation

- Memory integration and experience building

- Action planning and execution

- Environmental state observation


**Architecture Diagram**:

```mermaid
graph TD
    A[Task Input] --> B[Memory Review]
    B --> C[Current State Observation]
    C --> D[Reasoning Process]
    D --> E[Action Planning]
    E --> F[Action Execution]
    F --> G[Outcome Observation]
    G --> H[Experience Storage]
    H --> I{Task Complete?}
    I -->|No| C
    I -->|Yes| J[Final Response]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style D fill:#fff3e0
    style J fill:#c8e6c9
```

**Use Cases**: Interactive tasks, tool usage scenarios, planning problems, learning environments

**Implementation**: `ReactAgent`

**Documentation**: [REACT Agent Guide](react_agent.md)


## Implementation Guide

### Unified Interface via Reasoning Agent Router

The `ReasoningAgentRouter` provides a centralized interface for accessing all reasoning agent implementations:

```python
from swarms.agents import ReasoningAgentRouter

# Initialize router with specific reasoning strategy
router = ReasoningAgentRouter(
    swarm_type="self-consistency",  # Select reasoning methodology
    model_name="gpt-4o-mini",
    num_samples=5,                  # Configuration for consensus-based methods
    max_loops=3                     # Configuration for iterative methods
)

# Execute reasoning process
result = router.run("Analyze the optimal solution for this complex business problem")
print(result)
```

### Direct Agent Implementation

```python
from swarms.agents import SelfConsistencyAgent, ReasoningDuo, ReflexionAgent

# Self-Consistency Agent for high-accuracy requirements
consistency_agent = SelfConsistencyAgent(
    model_name="gpt-4o-mini",
    num_samples=5
)

# Reasoning Duo for collaborative analysis workflows
duo_agent = ReasoningDuo(
    model_names=["gpt-4o-mini", "gpt-4o"]
)

# Reflexion Agent for adaptive learning scenarios
reflexion_agent = ReflexionAgent(
    model_name="gpt-4o-mini",
    max_loops=3,
    memory_capacity=100
)
```

## Choosing the Right Reasoning Agent

| Scenario | Recommended Agent | Why? |
|----------|------------------|-------|
| **High-stakes decisions** | Self-Consistency | Multiple validation paths ensure reliability |
| **Complex research tasks** | Reasoning Duo + GKP | Collaboration + knowledge synthesis |
| **Learning & improvement** | Reflexion | Built-in self-improvement mechanisms |
| **Mathematical problems** | Self-Consistency | Proven effectiveness on logical reasoning |
| **Quality assessment** | Agent Judge | Specialized evaluation capabilities |
| **Interactive planning** | REACT | Action-oriented reasoning cycle |
| **Iterative refinement** | IRE | Designed for progressive improvement |


## Technical Documentation

For comprehensive technical documentation on each reasoning agent implementation:

- [Self-Consistency Agent](consistency_agent.md)

- [Reasoning Duo](reasoning_duo.md)

- [IRE Agent](iterative_agent.md)

- [Reflexion Agent](reflexion_agent.md)

- [GKP Agent](gkp_agent.md)

- [Agent Judge](agent_judge.md)

- [Reasoning Agent Router](reasoning_agent_router.md)



---

Reasoning agents represent a significant advancement in enterprise agent capabilities, implementing sophisticated cognitive architectures that deliver enhanced reliability, consistency, and performance compared to traditional language model implementations. 

--------------------------------------------------

# File: swarms/agents/reasoning_duo.md

# ReasoningDuo

The ReasoningDuo class implements a dual-agent reasoning system that combines a reasoning agent and a main agent to provide well-thought-out responses to complex tasks. This architecture enables more robust and reliable outputs by separating the reasoning process from the final response generation.


## Class Overview

### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| model_name | str | "reasoning-agent-01" | Name identifier for the reasoning agent |
| description | str | "A highly intelligent..." | Description of the reasoning agent's capabilities |
| model_names | list[str] | ["gpt-4o-mini", "gpt-4o"] | Model names for reasoning and main agents |
| system_prompt | str | "You are a helpful..." | System prompt for the main agent |

### Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | str | Processes a single task through both agents |
| batched_run | tasks: List[str] | List[str] | Processes multiple tasks sequentially |



## Quick Start

```python
from swarms.agents.reasoning_duo import ReasoningDuo

# Initialize the ReasoningDuo
duo = ReasoningDuo(
    model_name="reasoning-agent-01",
    model_names=["gpt-4o-mini", "gpt-4o"]
)

# Run a single task
result = duo.run("Explain the concept of gravitational waves")

# Run multiple tasks
tasks = [
    "Calculate compound interest for $1000 over 5 years",
    "Explain quantum entanglement"
]
results = duo.batched_run(tasks)
```

## Examples

### 1. Mathematical Analysis

```python
duo = ReasoningDuo()

# Complex mathematical problem
math_task = """
Solve the following differential equation:
dy/dx + 2y = x^2, y(0) = 1
"""

solution = duo.run(math_task)
```

### 2. Physics Problem

```python
# Quantum mechanics problem
physics_task = """
Calculate the wavelength of an electron with kinetic energy of 50 eV 
using the de Broglie relationship.
"""

result = duo.run(physics_task)
```

### 3. Financial Analysis

```python
# Complex financial analysis
finance_task = """
Calculate the Net Present Value (NPV) of a project with:
- Initial investment: $100,000
- Annual cash flows: $25,000 for 5 years
- Discount rate: 8%
"""

analysis = duo.run(finance_task)
```

## Advanced Usage

### Customizing Agent Behavior

You can customize both agents by modifying their initialization parameters:

```python
duo = ReasoningDuo(
    model_name="custom-reasoning-agent",
    description="Specialized financial analysis agent",
    model_names=["gpt-4o-mini", "gpt-4o"],
    system_prompt="You are a financial expert AI assistant..."
)
```

### Batch Processing with Progress Tracking

```python
tasks = [
    "Analyze market trends for tech stocks",
    "Calculate risk metrics for a portfolio",
    "Forecast revenue growth"
]

# Process multiple tasks with logging
results = duo.batched_run(tasks)
```

## Implementation Details

The ReasoningDuo uses a two-stage process:

1. **Reasoning Stage**: The reasoning agent analyzes the task and develops a structured approach
2. **Execution Stage**: The main agent uses the reasoning output to generate the final response

### Internal Architecture

```
Task Input → Reasoning Agent → Structured Analysis → Main Agent → Final Output
```

## Best Practices

1. **Task Formulation**
   - Be specific and clear in task descriptions
   - Include relevant context and constraints
   - Break complex problems into smaller subtasks

2. **Performance Optimization**
   - Use batched_run for multiple related tasks
   - Monitor agent outputs for consistency
   - Adjust model parameters based on task complexity

## Error Handling

The ReasoningDuo includes built-in logging using the `loguru` library:

```python
from loguru import logger

# Logs are automatically generated for each task
logger.info("Task processing started")
```

## Limitations

- Processing time may vary based on task complexity
- Model response quality depends on input clarity
- Resource usage scales with batch size

## Example Script

For a runnable demonstration, see the [reasoning_duo_batched.py](https://github.com/kyegomez/swarms/blob/master/examples/models/reasoning_duo_batched.py) example.


--------------------------------------------------

# File: swarms/agents/reflexion_agent.md

# ReflexionAgent

The ReflexionAgent is an advanced AI agent that implements the Reflexion framework to improve through self-reflection. It follows a process of acting on tasks, evaluating its performance, generating self-reflections, and using these reflections to improve future responses.

## Overview

The ReflexionAgent consists of three specialized sub-agents:
- **Actor**: Generates initial responses to tasks
- **Evaluator**: Critically assesses responses against quality criteria
- **Reflector**: Generates self-reflections to improve future responses

## Initialization

```python
from swarms.agents import ReflexionAgent

agent = ReflexionAgent(
    agent_name="reflexion-agent",
    system_prompt="...",  # Optional custom system prompt
    model_name="openai/o1",
    max_loops=3,
    memory_capacity=100
)
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agent_name` | `str` | `"reflexion-agent"` | Name of the agent |
| `system_prompt` | `str` | `REFLEXION_PROMPT` | System prompt for the agent |
| `model_name` | `str` | `"openai/o1"` | Model name for generating responses |
| `max_loops` | `int` | `3` | Maximum number of reflection iterations per task |
| `memory_capacity` | `int` | `100` | Maximum capacity of long-term memory |

## Methods

### act

Generates a response to the given task using the actor agent.

```python
response = agent.act(task: str, relevant_memories: List[Dict[str, Any]] = None) -> str
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | The task to respond to |
| `relevant_memories` | `List[Dict[str, Any]]` | Optional relevant past memories to consider |

### evaluate

Evaluates the quality of a response to a task.

```python
evaluation, score = agent.evaluate(task: str, response: str) -> Tuple[str, float]
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | The original task |
| `response` | `str` | The response to evaluate |

Returns:
- `evaluation`: Detailed feedback on the response
- `score`: Numerical score between 0 and 1

### reflect

Generates a self-reflection based on the task, response, and evaluation.

```python
reflection = agent.reflect(task: str, response: str, evaluation: str) -> str
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | The original task |
| `response` | `str` | The generated response |
| `evaluation` | `str` | The evaluation feedback |

### refine

Refines the original response based on evaluation and reflection.

```python
refined_response = agent.refine(
    task: str,
    original_response: str,
    evaluation: str,
    reflection: str
) -> str
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | The original task |
| `original_response` | `str` | The original response |
| `evaluation` | `str` | The evaluation feedback |
| `reflection` | `str` | The self-reflection |

### step

Processes a single task through one iteration of the Reflexion process.

```python
result = agent.step(
    task: str,
    iteration: int = 0,
    previous_response: str = None
) -> Dict[str, Any]
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | The task to process |
| `iteration` | `int` | Current iteration number |
| `previous_response` | `str` | Response from previous iteration |

Returns a dictionary containing:
- `task`: The original task
- `response`: The generated response
- `evaluation`: The evaluation feedback
- `reflection`: The self-reflection
- `score`: Numerical score
- `iteration`: Current iteration number

### run

Executes the Reflexion process for a list of tasks.

```python
results = agent.run(
    tasks: List[str],
    include_intermediates: bool = False
) -> List[Any]
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `tasks` | `List[str]` | List of tasks to process |
| `include_intermediates` | `bool` | Whether to include intermediate iterations in results |

Returns:
- If `include_intermediates=False`: List of final responses
- If `include_intermediates=True`: List of complete iteration histories

## Example Usage

```python
from swarms.agents import ReflexionAgent

# Initialize the Reflexion Agent
agent = ReflexionAgent(
    agent_name="reflexion-agent",
    model_name="openai/o1",
    max_loops=3
)

# Example tasks
tasks = [
    "Explain quantum computing to a beginner.",
    "Write a Python function to sort a list of dictionaries by a specific key."
]

# Run the agent
results = agent.run(tasks)

# Print results
for i, result in enumerate(results):
    print(f"\nTask {i+1}: {tasks[i]}")
    print(f"Response: {result}")
```

## Memory System

The ReflexionAgent includes a sophisticated memory system (`ReflexionMemory`) that maintains both short-term and long-term memories of past experiences, reflections, and feedback. This system helps the agent learn from past interactions and improve its responses over time.

### Memory Features
- Short-term memory for recent interactions
- Long-term memory for important reflections and patterns
- Automatic memory management with capacity limits
- Relevance-based memory retrieval
- Similarity-based deduplication

## Best Practices

1. **Task Clarity**: Provide clear, specific tasks to get the best results
2. **Iteration Count**: Adjust `max_loops` based on task complexity (more complex tasks may benefit from more iterations)
3. **Memory Management**: Monitor memory usage and adjust `memory_capacity` as needed
4. **Model Selection**: Choose an appropriate model based on your specific use case and requirements
5. **Error Handling**: Implement proper error handling when using the agent in production


--------------------------------------------------

# File: swarms/agents/structured_outputs.md

# :material-code-json: Agentic Structured Outputs

!!! abstract "Overview"
    Structured outputs help ensure that your agents return data in a consistent, predictable format that can be easily parsed and processed by your application. This is particularly useful when building complex applications that require standardized data handling.

## :material-file-document-outline: Schema Definition

Structured outputs are defined using JSON Schema format. Here's the basic structure:

=== "Basic Schema"

    ```python title="Basic Tool Schema"
    tools = [
        {
            "type": "function",
            "function": {
                "name": "function_name",
                "description": "Description of what the function does",
                "parameters": {
                    "type": "object",
                    "properties": {
                        # Define your parameters here
                    },
                    "required": [
                        # List required parameters
                    ]
                }
            }
        }
    ]
    ```

=== "Advanced Schema"

    ```python title="Advanced Tool Schema with Multiple Parameters"
    tools = [
        {
            "type": "function",
            "function": {
                "name": "advanced_function",
                "description": "Advanced function with multiple parameter types",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "text_param": {
                            "type": "string",
                            "description": "A text parameter"
                        },
                        "number_param": {
                            "type": "number",
                            "description": "A numeric parameter"
                        },
                        "boolean_param": {
                            "type": "boolean",
                            "description": "A boolean parameter"
                        },
                        "array_param": {
                            "type": "array",
                            "items": {"type": "string"},
                            "description": "An array of strings"
                        }
                    },
                    "required": ["text_param", "number_param"]
                }
            }
        }
    ]
    ```

### :material-format-list-bulleted-type: Parameter Types

The following parameter types are supported:

| Type | Description | Example |
|------|-------------|---------|
| `string` | Text values | `"Hello World"` |
| `number` | Numeric values | `42`, `3.14` |
| `boolean` | True/False values | `true`, `false` |
| `object` | Nested objects | `{"key": "value"}` |
| `array` | Lists or arrays | `[1, 2, 3]` |
| `null` | Null values | `null` |

## :material-cog: Implementation Steps

!!! tip "Quick Start Guide"
    Follow these steps to implement structured outputs in your agent:

### Step 1: Define Your Schema

```python 
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "Retrieve stock price information",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "Stock ticker symbol"
                    },
                    "include_volume": {
                        "type": "boolean",
                        "description": "Include trading volume data"
                    }
                },
                "required": ["ticker"]
            }
        }
    }
]
```

### Step 2: Initialize the Agent

```
from swarms import Agent

agent = Agent(
    agent_name="Your-Agent-Name",
    agent_description="Agent description",
    system_prompt="Your system prompt",
    tools_list_dictionary=tools
)
```

### Step 3: Run the Agent

```python
response = agent.run("Your query here")
```

### Step 4: Parse the Output

```python
from swarms.utils.str_to_dict import str_to_dict

parsed_output = str_to_dict(response)
```

## :material-code-braces: Example Usage

!!! example "Complete Financial Agent Example"
    Here's a comprehensive example using a financial analysis agent:

=== "Python Implementation"

    ```python
    from dotenv import load_dotenv
    from swarms import Agent
    from swarms.utils.str_to_dict import str_to_dict
    
    # Load environment variables
    load_dotenv()
    
    # Define tools with structured output schema
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_stock_price",
                "description": "Retrieve the current stock price and related information",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "ticker": {
                            "type": "string",
                            "description": "Stock ticker symbol (e.g., AAPL, GOOGL)"
                        },
                        "include_history": {
                            "type": "boolean",
                            "description": "Include historical data in the response"
                        },
                        "time": {
                            "type": "string",
                            "format": "date-time",
                            "description": "Specific time for stock data (ISO format)"
                        }
                    },
                    "required": ["ticker", "include_history", "time"]
                }
            }
        }
    ]
    
    # Initialize agent
    agent = Agent(
        agent_name="Financial-Analysis-Agent",
        agent_description="Personal finance advisor agent",
        system_prompt="You are a helpful financial analysis assistant.",
        max_loops=1,
        tools_list_dictionary=tools
    )
    
    # Run agent
    response = agent.run("What is the current stock price for AAPL?")
    
    # Parse structured output
    parsed_data = str_to_dict(response)
    print(f"Parsed response: {parsed_data}")
    ```

=== "Expected Output"

    ```json
    {
        "function_calls": [
            {
                "name": "get_stock_price",
                "arguments": {
                    "ticker": "AAPL",
                    "include_history": true,
                    "time": "2024-01-15T10:30:00Z"
                }
            }
        ]
    }
    ```

## :material-check-circle: Best Practices

!!! success "Schema Design"
    
    - **Keep it simple**: Design schemas that are as simple as possible while meeting your needs
    
    - **Clear naming**: Use descriptive parameter names that clearly indicate their purpose
    
    - **Detailed descriptions**: Include comprehensive descriptions for each parameter
    
    - **Required fields**: Explicitly specify all required parameters

!!! info "Error Handling"
    
    - **Validate output**: Always validate the output format before processing
    
    - **Exception handling**: Implement proper error handling for parsing failures
    
    - **Safety first**: Use try-except blocks when converting strings to dictionaries

!!! performance "Performance Tips"
    
    - **Minimize requirements**: Keep the number of required parameters to a minimum
    
    - **Appropriate types**: Use the most appropriate data types for each parameter
    
    - **Caching**: Consider caching parsed results if they're used frequently

## :material-alert-circle: Troubleshooting

!!! warning "Common Issues"

### Invalid Output Format

!!! failure "Problem"
    The agent returns data in an unexpected format

!!! success "Solution"
    
    - Ensure your schema matches the expected output structure
    
    - Verify all required fields are present in the response
    
    - Check for proper JSON formatting in the output

### Parsing Errors

!!! failure "Problem"
    Errors occur when trying to parse the agent's response

!!! success "Solution"
    
    ```python
    from swarms.utils.str_to_dict import str_to_dict
    
    try:
        parsed_data = str_to_dict(response)
    except Exception as e:
        print(f"Parsing error: {e}")
        # Handle the error appropriately
    ```

### Missing Fields

!!! failure "Problem"
    Required fields are missing from the output

!!! success "Solution"
    - Verify all required fields are defined in the schema
    - Check if the agent is properly configured with the tools
    - Review the system prompt for clarity and completeness

## :material-lightbulb: Advanced Features

!!! note "Pro Tips"
    
    === "Nested Objects"
    
        ```python title="nested_schema.py"
        "properties": {
            "user_info": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "number"},
                    "preferences": {
                        "type": "array",
                        "items": {"type": "string"}
                    }
                }
            }
        }
        ```
    
    === "Conditional Fields"
    
        ```python title="conditional_schema.py"
        "properties": {
            "data_type": {
                "type": "string",
                "enum": ["stock", "crypto", "forex"]
            },
            "symbol": {"type": "string"},
            "exchange": {
                "type": "string",
                "description": "Required for crypto and forex"
            }
        }
        ```

---



--------------------------------------------------

# File: swarms/agents/third_party.md

# Swarms Framework: Integrating and Customizing Agent Libraries

Agent-based systems have emerged as a powerful paradigm for solving complex problems and automating tasks. 

The swarms framework offers a flexible and extensible approach to working with various agent libraries, allowing developers to create custom agents and integrate them seamlessly into their projects. 

In this comprehensive guide, we'll explore the swarms framework, discuss agent handling, and demonstrate how to build custom agents using swarms. We'll also cover the integration of popular agent libraries such as Langchain, Griptape, CrewAI, and Autogen.

## Table of Contents

1. [Introduction to the Swarms Framework](#introduction-to-the-swarms-framework)
2. [The Need for Wrappers](#the-need-for-wrappers)
3. [Building Custom Agents with Swarms](#building-custom-agents-with-swarms)
4. [Integrating Third-Party Agent Libraries](#integrating-third-party-agent-libraries)
   - [Griptape Integration](#griptape-integration)
   - [Langchain Integration](#langchain-integration)
   - [CrewAI Integration](#crewai-integration)
   - [Autogen Integration](#autogen-integration)
5. [Advanced Agent Handling Techniques](#advanced-agent-handling-techniques)
6. [Best Practices for Custom Agent Development](#best-practices-for-custom-agent-development)
7. [Future Directions and Challenges](#future-directions-and-challenges)
8. [Conclusion](#conclusion)

## 1. Introduction to the Swarms Framework

The swarms framework is a powerful and flexible system designed to facilitate the creation, management, and coordination of multiple AI agents. It provides a standardized interface for working with various agent types, allowing developers to leverage the strengths of different agent libraries while maintaining a consistent programming model.

At its core, the swarms framework is built around the concept of a parent `Agent` class, which serves as a foundation for creating custom agents and integrating third-party agent libraries. This approach offers several benefits:

1. **Consistency**: By wrapping different agent implementations with a common interface, developers can work with a unified API across various agent types.
2. **Extensibility**: The framework makes it easy to add new agent types or customize existing ones without affecting the overall system architecture.
3. **Interoperability**: Agents from different libraries can communicate and collaborate seamlessly within the swarms ecosystem.
4. **Scalability**: The standardized approach allows for easier scaling of agent-based systems, from simple single-agent applications to complex multi-agent swarms.

## 2. The Need for Wrappers

As the field of AI and agent-based systems continues to grow, numerous libraries and frameworks have emerged, each with its own strengths and specialized features. While this diversity offers developers a wide range of tools to choose from, it also presents challenges in terms of integration and interoperability.

This is where the concept of wrappers becomes crucial. By creating wrappers around different agent libraries, we can:

1. **Unify interfaces**: Standardize the way we interact with agents, regardless of their underlying implementation.
2. **Simplify integration**: Make it easier to incorporate new agent libraries into existing projects.
3. **Enable composition**: Allow for the creation of complex agent systems that leverage the strengths of multiple libraries.
4. **Facilitate maintenance**: Centralize the management of agent-related code and reduce the impact of library-specific changes.

In the context of the swarms framework, wrappers take the form of custom classes that inherit from the parent `Agent` class. These wrapper classes encapsulate the functionality of specific agent libraries while exposing a consistent interface that aligns with the swarms framework.

## 3. Building Custom Agents with Swarms

To illustrate the process of building custom agents using the swarms framework, let's start with a basic example of creating a custom agent class:

```python
from swarms import Agent

class MyCustomAgent(Agent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # Custom initialization logic

    def custom_method(self, *args, **kwargs):
        # Implement custom logic here
        pass

    def run(self, task, *args, **kwargs):
        # Customize the run method
        response = super().run(task, *args, **kwargs)
        # Additional custom logic
        return response
```

This example demonstrates the fundamental structure of a custom agent class within the swarms framework. Let's break down the key components:

1. **Inheritance**: The class inherits from the `Agent` parent class, ensuring it adheres to the swarms framework's interface.

2. **Initialization**: The `__init__` method calls the parent class's initializer and can include additional custom initialization logic.

3. **Custom methods**: You can add any number of custom methods to extend the agent's functionality.

4. **Run method**: The `run` method is a key component of the agent interface. By overriding this method, you can customize how the agent processes tasks while still leveraging the parent class's functionality.

To create more sophisticated custom agents, you can expand on this basic structure by adding features such as:

- **State management**: Implement methods to manage the agent's internal state.
- **Communication protocols**: Define how the agent interacts with other agents in the swarm.
- **Learning capabilities**: Incorporate machine learning models or adaptive behaviors.
- **Specialized task handling**: Create methods for dealing with specific types of tasks or domains.

By leveraging these custom agent classes, developers can create highly specialized and adaptive agents tailored to their specific use cases while still benefiting from the standardized interface provided by the swarms framework.

## 4. Integrating Third-Party Agent Libraries

One of the key strengths of the swarms framework is its ability to integrate with various third-party agent libraries. In this section, we'll explore how to create wrappers for popular agent libraries, including Griptape, Langchain, CrewAI, and Autogen.

### Griptape Integration

Griptape is a powerful library for building AI agents with a focus on composability and tool use. Let's create a wrapper for a Griptape agent:

```python
from typing import List, Optional

from griptape.structures import Agent as GriptapeAgent
from griptape.tools import FileManager, TaskMemoryClient, WebScraper

from swarms import Agent


class GriptapeAgentWrapper(Agent):
    """
    A wrapper class for the GriptapeAgent from the griptape library.
    """

    def __init__(self, name: str, tools: Optional[List] = None, *args, **kwargs):
        """
        Initialize the GriptapeAgentWrapper.

        Parameters:
        - name: The name of the agent.
        - tools: A list of tools to be used by the agent. If not provided, default tools will be used.
        - *args, **kwargs: Additional arguments to be passed to the parent class constructor.
        """
        super().__init__(*args, **kwargs)
        self.name = name
        self.tools = tools or [
            WebScraper(off_prompt=True),
            TaskMemoryClient(off_prompt=True),
            FileManager()
        ]
        self.griptape_agent = GriptapeAgent(
            input=f"I am {name}, an AI assistant. How can I help you?",
            tools=self.tools
        )

    def run(self, task: str, *args, **kwargs) -> str:
        """
        Run a task using the GriptapeAgent.

        Parameters:
        - task: The task to be performed by the agent.

        Returns:
        - The response from the GriptapeAgent as a string.
        """
        response = self.griptape_agent.run(task, *args, **kwargs)
        return str(response)

    def add_tool(self, tool) -> None:
        """
        Add a tool to the agent.

        Parameters:
        - tool: The tool to be added.
        """
        self.tools.append(tool)
        self.griptape_agent = GriptapeAgent(
            input=f"I am {self.name}, an AI assistant. How can I help you?",
            tools=self.tools
        )

# Usage example
griptape_wrapper = GriptapeAgentWrapper("GriptapeAssistant")
result = griptape_wrapper.run("Load https://example.com, summarize it, and store it in a file called example_summary.txt.")
print(result)

```

This wrapper encapsulates the functionality of a Griptape agent while exposing it through the swarms framework's interface. It allows for easy customization of tools and provides a simple way to execute tasks using the Griptape agent.

### Langchain Integration

Langchain is a popular framework for developing applications powered by language models. Here's an example of how we can create a wrapper for a Langchain agent:

```python
from typing import List, Optional

from langchain.agents import AgentExecutor, LLMSingleActionAgent, Tool
from langchain.chains import LLMChain
from langchain_community.llms import OpenAI
from langchain.prompts import StringPromptTemplate
from langchain.tools import DuckDuckGoSearchRun

from swarms import Agent


class LangchainAgentWrapper(Agent):
    """
    Initialize the LangchainAgentWrapper.

    Args:
        name (str): The name of the agent.
        tools (List[Tool]): The list of tools available to the agent.
        llm (Optional[OpenAI], optional): The OpenAI language model to use. Defaults to None.
    """
    def __init__(
        self,
        name: str,
        tools: List[Tool],
        llm: Optional[OpenAI] = None,
        *args,
        **kwargs,
    ):
        super().__init__(*args, **kwargs)
        self.name = name
        self.tools = tools
        self.llm = llm or OpenAI(temperature=0)

        prompt = StringPromptTemplate.from_template(
            "You are {name}, an AI assistant. Answer the following question: {question}"
        )

        llm_chain = LLMChain(llm=self.llm, prompt=prompt)
        tool_names = [tool.name for tool in self.tools]

        self.agent = LLMSingleActionAgent(
            llm_chain=llm_chain,
            output_parser=None,
            stop=["\nObservation:"],
            allowed_tools=tool_names,
        )

        self.agent_executor = AgentExecutor.from_agent_and_tools(
            agent=self.agent, tools=self.tools, verbose=True
        )

    def run(self, task: str, *args, **kwargs):
        """
        Run the agent with the given task.

        Args:
            task (str): The task to be performed by the agent.

        Returns:
            Any: The result of the agent's execution.
        """
        try:
            return self.agent_executor.run(task)
        except Exception as e:
            print(f"An error occurred: {e}")


# Usage example

search_tool = DuckDuckGoSearchRun()
tools = [
    Tool(
        name="Search",
        func=search_tool.run,
        description="Useful for searching the internet",
    )
]

langchain_wrapper = LangchainAgentWrapper("LangchainAssistant", tools)
result = langchain_wrapper.run("What is the capital of France?")
print(result)
```

This wrapper integrates a Langchain agent into the swarms framework, allowing for easy use of Langchain's powerful features such as tool use and multi-step reasoning.

### CrewAI Integration

CrewAI is a library focused on creating and managing teams of AI agents. Let's create a wrapper for a CrewAI agent:

```python
from swarms import Agent
from crewai import Agent as CrewAIAgent
from crewai import Task, Crew, Process

class CrewAIAgentWrapper(Agent):
    def __init__(self, name, role, goal, backstory, tools=None, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name
        self.crewai_agent = CrewAIAgent(
            role=role,
            goal=goal,
            backstory=backstory,
            verbose=True,
            allow_delegation=False,
            tools=tools or []
        )

    def run(self, task, *args, **kwargs):
        crew_task = Task(
            description=task,
            agent=self.crewai_agent
        )
        crew = Crew(
            agents=[self.crewai_agent],
            tasks=[crew_task],
            process=Process.sequential
        )
        result = crew.kickoff()
        return result

# Usage example
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

crewai_wrapper = CrewAIAgentWrapper(
    "ResearchAnalyst",
    role='Senior Research Analyst',
    goal='Uncover cutting-edge developments in AI and data science',
    backstory="""You work at a leading tech think tank.
    Your expertise lies in identifying emerging trends.
    You have a knack for dissecting complex data and presenting actionable insights.""",
    tools=[search_tool]
)

result = crewai_wrapper.run("Analyze the latest trends in quantum computing and summarize the key findings.")
print(result)
```

This wrapper allows us to use CrewAI agents within the swarms framework, leveraging CrewAI's focus on role-based agents and collaborative task execution.

### Autogen Integration

Autogen is a framework for building conversational AI agents. Here's how we can create a wrapper for an Autogen agent:

```python
from swarms import Agent
from autogen import ConversableAgent

class AutogenAgentWrapper(Agent):
    def __init__(self, name, llm_config, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name
        self.autogen_agent = ConversableAgent(
            name=name,
            llm_config=llm_config,
            code_execution_config=False,
            function_map=None,
            human_input_mode="NEVER"
        )

    def run(self, task, *args, **kwargs):
        messages = [{"content": task, "role": "user"}]
        response = self.autogen_agent.generate_reply(messages)
        return response

# Usage example
import os

llm_config = {
    "config_list": [{"model": "gpt-4", "api_key": os.environ.get("OPENAI_API_KEY")}]
}

autogen_wrapper = AutogenAgentWrapper("AutogenAssistant", llm_config)
result = autogen_wrapper.run("Tell me a joke about programming.")
print(result)
```

This wrapper integrates Autogen's ConversableAgent into the swarms framework, allowing for easy use of Autogen's conversational AI capabilities.

By creating these wrappers, we can seamlessly integrate agents from various libraries into the swarms framework, allowing for a unified approach to agent management and task execution.

## 5. Advanced Agent Handling Techniques

As you build more complex systems using the swarms framework and integrated agent libraries, you'll need to employ advanced techniques for agent handling. Here are some strategies to consider:

### 1. Dynamic Agent Creation

Implement a factory pattern to create agents dynamically based on task requirements:

```python
class AgentFactory:
    @staticmethod
    def create_agent(agent_type, *args, **kwargs):
        if agent_type == "griptape":
            return GriptapeAgentWrapper(*args, **kwargs)
        elif agent_type == "langchain":
            return LangchainAgentWrapper(*args, **kwargs)
        elif agent_type == "crewai":
            return CrewAIAgentWrapper(*args, **kwargs)
        elif agent_type == "autogen":
            return AutogenAgentWrapper(*args, **kwargs)
        else:
            raise ValueError(f"Unknown agent type: {agent_type}")

# Usage
agent = AgentFactory.create_agent("griptape", "DynamicGriptapeAgent")
```


### 2. Agent Pooling

Implement an agent pool to manage and reuse agents efficiently:

```python
from queue import Queue

class AgentPool:
    def __init__(self, pool_size=5):
        self.pool = Queue(maxsize=pool_size)
        self.pool_size = pool_size

    def get_agent(self, agent_type, *args, **kwargs):
        if not self.pool.empty():
            return self.pool.get()
        else:
            return AgentFactory.create_agent(agent_type, *args, **kwargs)

    def release_agent(self, agent):
        if self.pool.qsize() < self.pool_size:
            self.pool.put(agent)

# Usage
pool = AgentPool()
agent = pool.get_agent("langchain", "PooledLangchainAgent")
result = agent.run("Perform a task")
pool.release_agent(agent)
```

### 3. Agent Composition

Create composite agents that combine the capabilities of multiple agent types:

```python
class CompositeAgent(Agent):
    def __init__(self, name, agents):
        super().__init__()
        self.name = name
        self.agents = agents

    def run(self, task):
        results = []
        for agent in self.agents:
            results.append(agent.run(task))
        return self.aggregate_results(results)

    def aggregate_results(self, results):
        # Implement your own logic to combine results
        return "\n".join(results)

# Usage
griptape_agent = GriptapeAgentWrapper("GriptapeComponent")
langchain_agent = LangchainAgentWrapper("LangchainComponent", [])
composite_agent = CompositeAgent("CompositeAssistant", [griptape_agent, langchain_agent])
result = composite_agent.run("Analyze the pros and cons of quantum computing")
```

### 4. Agent Specialization

Create specialized agents for specific domains or tasks:

```python
class DataAnalysisAgent(Agent):
    def __init__(self, name, analysis_tools):
        super().__init__()
        self.name = name
        self.analysis_tools = analysis_tools

    def run(self, data):
        results = {}
        for tool in self.analysis_tools:
            results[tool.name] = tool.analyze(data)
        return results

# Usage
import pandas as pd
from sklearn.preprocessing import StandardScaler
from sklearn.decomposition import PCA

class AnalysisTool:
    def __init__(self, name, func):
        self.name = name
        self.func = func

    def analyze(self, data):
        return self.func(data)

tools = [
    AnalysisTool("Descriptive Stats", lambda data: data.describe()),
    AnalysisTool("Correlation", lambda data: data.corr()),
    AnalysisTool("PCA", lambda data: PCA().fit_transform(StandardScaler().fit_transform(data)))
]

data_agent = DataAnalysisAgent("DataAnalyst", tools)
df = pd.read_csv("sample_data.csv")
analysis_results = data_agent.run(df)
```

### 5. Agent Monitoring and Logging

Implement a monitoring system to track agent performance and log their activities:

```python
import logging
from functools import wraps

def log_agent_activity(func):
    @wraps(func)
    def wrapper(self, *args, **kwargs):
        logging.info(f"Agent {self.name} started task: {args[0]}")
        result = func(self, *args, **kwargs)
        logging.info(f"Agent {self.name} completed task. Result length: {len(str(result))}")
        return result
    return wrapper

class MonitoredAgent(Agent):
    def __init__(self, name, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name

    @log_agent_activity
    def run(self, task, *args, **kwargs):
        return super().run(task, *args, **kwargs)

# Usage
logging.basicConfig(level=logging.INFO)
monitored_agent = MonitoredAgent("MonitoredGriptapeAgent")
result = monitored_agent.run("Summarize the latest AI research papers")
```
Additionally the Agent class now includes built-in logging functionality and the ability to switch between JSON and string output. 

To switch between JSON and string output:
- Use `output_type="str"` for string output (default)
- Use `output_type="json"` for JSON output

The `output_type` parameter determines the format of the final result returned by the `run` method. When set to "str", it returns a string representation of the agent's response. When set to "json", it returns a JSON object containing detailed information about the agent's run, including all steps and metadata.

## 6. Best Practices for Custom Agent Development

When developing custom agents using the swarms framework, consider the following best practices:

1. **Modular Design**: Design your agents with modularity in mind. Break down complex functionality into smaller, reusable components.

2. **Consistent Interfaces**: Maintain consistent interfaces across your custom agents to ensure interoperability within the swarms framework.

3. **Error Handling**: Implement robust error handling and graceful degradation in your agents to ensure system stability.

4. **Performance Optimization**: Optimize your agents for performance, especially when dealing with resource-intensive tasks or large-scale deployments.

5. **Testing and Validation**: Develop comprehensive test suites for your custom agents to ensure their reliability and correctness.

6. **Documentation**: Provide clear and detailed documentation for your custom agents, including their capabilities, limitations, and usage examples.

7. **Versioning**: Implement proper versioning for your custom agents to manage updates and maintain backwards compatibility.

8. **Security Considerations**: Implement security best practices, especially when dealing with sensitive data or integrating with external services.

Here's an example that incorporates some of these best practices:

```python
import logging
from typing import Dict, Any
from swarms import Agent

class SecureCustomAgent(Agent):
    def __init__(self, name: str, api_key: str, version: str = "1.0.0", *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.name = name
        self._api_key = api_key  # Store sensitive data securely
        self.version = version
        self.logger = logging.getLogger(f"{self.__class__.__name__}.{self.name}")

    def run(self, task: str, *args, **kwargs) -> Dict[str, Any]:
        try:
            self.logger.info(f"Agent {self.name} (v{self.version}) starting task: {task}")
            result = self._process_task(task)
            self.logger.info(f"Agent {self.name} completed task successfully")
            return {"status": "success", "result": result}
        except Exception as e:
            self.logger.error(f"Error in agent {self.name}: {str(e)}")
            return {"status": "error", "message": str(e)}

    def _process_task(self, task: str) -> str:
        # Implement the core logic of your agent here
        # This is a placeholder implementation
        return f"Processed task: {task}"

    @property
    def api_key(self) -> str:
        # Provide a secure way to access the API key
        return self._api_key

    def __repr__(self) -> str:
        return f"<{self.__class__.__name__} name='{self.name}' version='{self.version}'>"

# Usage
logging.basicConfig(level=logging.INFO)
secure_agent = SecureCustomAgent("SecureAgent", api_key="your-api-key-here")
result = secure_agent.run("Perform a secure operation")
print(result)
```

This example demonstrates several best practices:
- Modular design with separate methods for initialization and task processing
- Consistent interface adhering to the swarms framework
- Error handling and logging
- Secure storage of sensitive data (API key)
- Version tracking
- Type hinting for improved code readability and maintainability
- Informative string representation of the agent

## 7. Future Directions and Challenges

As the field of AI and agent-based systems continues to evolve, the swarms framework and its ecosystem of integrated agent libraries will face new opportunities and challenges. Some potential future directions and areas of focus include:

1. **Enhanced Interoperability**: Developing more sophisticated protocols for agent communication and collaboration across different libraries and frameworks.

2. **Scalability**: Improving the framework's ability to handle large-scale swarms of agents, potentially leveraging distributed computing techniques.

3. **Adaptive Learning**: Incorporating more advanced machine learning techniques to allow agents to adapt and improve their performance over time.

4. **Ethical AI**: Integrating ethical considerations and safeguards into the agent development process to ensure responsible AI deployment.

5. **Human-AI Collaboration**: Exploring new paradigms for human-AI interaction and collaboration within the swarms framework.

6. **Domain-Specific Optimizations**: Developing specialized agent types and tools for specific industries or problem domains.

7. **Explainability and Transparency**: Improving the ability to understand and explain agent decision-making processes.

8. **Security and Privacy**: Enhancing the framework's security features to protect against potential vulnerabilities and ensure data privacy.

As these areas develop, developers working with the swarms framework will need to stay informed about new advancements and be prepared to adapt their agent implementations accordingly.

## 8. Conclusion

The swarms framework provides a powerful and flexible foundation for building custom agents and integrating various agent libraries. By leveraging the techniques and best practices discussed in this guide, developers can create sophisticated, efficient, and scalable agent-based systems.

The ability to seamlessly integrate agents from libraries like Griptape, Langchain, CrewAI, and Autogen opens up a world of possibilities for creating diverse and specialized AI applications. Whether you're building a complex multi-agent system for data analysis, a conversational AI platform, or a collaborative problem-solving environment, the swarms framework offers the tools and flexibility to bring your vision to life.

As you embark on your journey with the swarms framework, remember that the field of AI and agent-based systems is rapidly evolving. Stay curious, keep experimenting, and don't hesitate to push the boundaries of what's possible with custom agents and integrated libraries.

By embracing the power of the swarms framework and the ecosystem of agent libraries it supports, you're well-positioned to create the next generation of intelligent, adaptive, and collaborative AI systems. Happy agent building!


--------------------------------------------------

# File: swarms/agents/tool_agent.md

# ToolAgent Documentation

The `ToolAgent` class is a specialized agent that facilitates the execution of specific tasks using a model and tokenizer. It is part of the `swarms` module and inherits from the `Agent` class. This agent is designed to generate functions based on a given JSON schema and task, making it highly adaptable for various use cases, including natural language processing and data generation.

The `ToolAgent` class plays a crucial role in leveraging pre-trained models and tokenizers to automate tasks that require the interpretation and generation of structured data. By providing a flexible interface and robust error handling, it ensures smooth integration and efficient task execution.

### Parameters

| Parameter          | Type                              | Description                                                                     |
|--------------------|-----------------------------------|---------------------------------------------------------------------------------|
| `name`             | `str`                             | The name of the tool agent. Default is "Function Calling Agent".                |
| `description`      | `str`                             | A description of the tool agent. Default is "Generates a function based on the input json schema and the task". |
| `model`            | `Any`                             | The model used by the tool agent.                                               |
| `tokenizer`        | `Any`                             | The tokenizer used by the tool agent.                                           |
| `json_schema`      | `Any`                             | The JSON schema used by the tool agent.                                         |
| `max_number_tokens`| `int`                             | The maximum number of tokens for generation. Default is 500.                    |
| `parsing_function` | `Optional[Callable]`              | An optional parsing function to process the output of the tool agent.           |
| `llm`              | `Any`                             | An optional large language model to be used by the tool agent.                  |
| `*args`            | Variable length argument list     | Additional positional arguments.                                                |
| `**kwargs`         | Arbitrary keyword arguments       | Additional keyword arguments.                                                   |

### Attributes

| Attribute          | Type  | Description                                  |
|--------------------|-------|----------------------------------------------|
| `name`             | `str` | The name of the tool agent.                  |
| `description`      | `str` | A description of the tool agent.             |
| `model`            | `Any` | The model used by the tool agent.            |
| `tokenizer`        | `Any` | The tokenizer used by the tool agent.        |
| `json_schema`      | `Any` | The JSON schema used by the tool agent.      |

### Methods

#### `run`

```python
def run(self, task: str, *args, **kwargs) -> Any:
```

**Parameters:**

| Parameter  | Type                      | Description                                                      |
|------------|---------------------------|------------------------------------------------------------------|
| `task`     | `str`                     | The task to be performed by the tool agent.                      |
| `*args`    | Variable length argument list | Additional positional arguments.                                 |
| `**kwargs` | Arbitrary keyword arguments | Additional keyword arguments.                                    |

**Returns:** 

- The output of the tool agent.

**Raises:** 

- `Exception`: If an error occurs during the execution of the tool agent.

## Functionality and Usage

The `ToolAgent` class provides a structured way to perform tasks using a model and tokenizer. It initializes with essential parameters and attributes, and the `run` method facilitates the execution of the specified task.

### Initialization

The initialization of a `ToolAgent` involves specifying its name, description, model, tokenizer, JSON schema, maximum number of tokens, optional parsing function, and optional large language model.

```python
agent = ToolAgent(
    name="My Tool Agent",
    description="A tool agent for specific tasks",
    model=model,
    tokenizer=tokenizer,
    json_schema=json_schema,
    max_number_tokens=1000,
    parsing_function=my_parsing_function,
    llm=my_llm
)
```

### Running a Task

To execute a task using the `ToolAgent`, the `run` method is called with the task description and any additional arguments or keyword arguments.

```python
result = agent.run("Generate a person's information based on the given schema.")
print(result)
```

### Detailed Examples

#### Example 1: Basic Usage

```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from swarms import ToolAgent

model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b")
tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b")

json_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "is_student": {"type": "boolean"},
        "courses": {
            "type": "array",
            "items": {"type": "string"}
        }
    }
}

task = "Generate a person's information based on the following schema:"
agent = ToolAgent(model=model, tokenizer=tokenizer, json_schema=json_schema)
generated_data = agent.run(task)

print(generated_data)
```

#### Example 2: Using a Parsing Function

```python
def parse_output(output):
    # Custom parsing logic
    return output

agent = ToolAgent(
    name="Parsed Tool Agent",
    description="A tool agent with a parsing function",
    model=model,
    tokenizer=tokenizer,
    json_schema=json_schema,
    parsing_function=parse_output
)

task = "Generate a person's information with custom parsing:"
parsed_data = agent.run(task)

print(parsed_data)
```

#### Example 3: Specifying Maximum Number of Tokens

```python
agent = ToolAgent(
    name="Token Limited Tool Agent",
    description="A tool agent with a token limit",
    model=model,
    tokenizer=tokenizer,
    json_schema=json_schema,
    max_number_tokens=200
)

task = "Generate a concise person's information:"
limited_data = agent.run(task)

print(limited_data)
```


## Full Usage
```python

from pydantic import BaseModel, Field
from transformers import AutoModelForCausalLM, AutoTokenizer

from swarms import ToolAgent
from swarms.tools.json_utils import base_model_to_json

# Model name
model_name = "CohereForAI/c4ai-command-r-v01-4bit"

# Load the pre-trained model and tokenizer
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",
)

# Load the pre-trained model and tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_name)


# Initialize the schema for the person's information
class APIExampleRequestSchema(BaseModel):
    endpoint: str = Field(
        ..., description="The API endpoint for the example request"
    )
    method: str = Field(
        ..., description="The HTTP method for the example request"
    )
    headers: dict = Field(
        ..., description="The headers for the example request"
    )
    body: dict = Field(..., description="The body of the example request")
    response: dict = Field(
        ...,
        description="The expected response of the example request",
    )


# Convert the schema to a JSON string
api_example_schema = base_model_to_json(APIExampleRequestSchema)
# Convert the schema to a JSON string

# Define the task to generate a person's information
task = "Generate an example API request using this code:\n"

# Create an instance of the ToolAgent class
agent = ToolAgent(
    name="Command R Tool Agent",
    description=(
        "An agent that generates an API request using the Command R"
        " model."
    ),
    model=model,
    tokenizer=tokenizer,
    json_schema=api_example_schema,
)

# Run the agent to generate the person's information
generated_data = agent.run(task)

# Print the generated data
print(f"Generated data: {generated_data}")



```


## Jamba ++ ToolAgent
```python
from pydantic import BaseModel, Field
from transformers import AutoModelForCausalLM, AutoTokenizer

from swarms import ToolAgent
from swarms.tools.json_utils import base_model_to_json

# Model name
model_name = "ai21labs/Jamba-v0.1"

# Load the pre-trained model and tokenizer
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",
)

# Load the pre-trained model and tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_name)


# Initialize the schema for the person's information
class APIExampleRequestSchema(BaseModel):
    endpoint: str = Field(
        ..., description="The API endpoint for the example request"
    )
    method: str = Field(
        ..., description="The HTTP method for the example request"
    )
    headers: dict = Field(
        ..., description="The headers for the example request"
    )
    body: dict = Field(..., description="The body of the example request")
    response: dict = Field(
        ...,
        description="The expected response of the example request",
    )


# Convert the schema to a JSON string
api_example_schema = base_model_to_json(APIExampleRequestSchema)
# Convert the schema to a JSON string

# Define the task to generate a person's information
task = "Generate an example API request using this code:\n"

# Create an instance of the ToolAgent class
agent = ToolAgent(
    name="Command R Tool Agent",
    description=(
        "An agent that generates an API request using the Command R"
        " model."
    ),
    model=model,
    tokenizer=tokenizer,
    json_schema=api_example_schema,
)

# Run the agent to generate the person's information
generated_data = agent(task)

# Print the generated data
print(f"Generated data: {generated_data}")
```

## Additional Information and Tips

- Ensure that either the `model` or `llm` parameter is provided during initialization. If neither is provided, the `ToolAgent` will raise an exception.
- The `parsing_function` parameter is optional but can be very useful for post-processing the output of the tool agent.
- Adjust the `max_number_tokens` parameter to control the length of the generated output, depending on the requirements of the task.

## References and Resources

- [Transformers Documentation](https://huggingface.co/transformers/)
- [Loguru Logger](https://loguru.readthedocs.io/en/stable/)

This documentation provides a comprehensive guide to the `ToolAgent` class, including its initialization, usage, and practical examples. By following the detailed instructions and examples, developers can effectively utilize the `ToolAgent` for various tasks involving model and tokenizer-based operations.

--------------------------------------------------

# File: swarms/artifacts/artifact.md

# `Artifact`

The `Artifact` class represents a file artifact, encapsulating the file's path, type, contents, versions, and edit count. This class provides a comprehensive way to manage file versions, edit contents, and handle various file-related operations such as saving, loading, and exporting to JSON.

The `Artifact` class is particularly useful in contexts where file version control and content management are essential. By keeping track of the number of edits and maintaining a version history, it allows for robust file handling and auditability.

## Class Definition

### Artifact


| Attribute   | Type                | Default Value    | Description                                      |
|-------------|---------------------|------------------|--------------------------------------------------|
| `file_path` | `str`               | N/A              | The path to the file.                            |
| `file_type` | `str`               | N/A              | The type of the file.                            |
| `contents`  | `str`               | `""`             | The contents of the file.                        |
| `versions`  | `List[FileVersion]` | `[]`             | The list of file versions.                       |
| `edit_count`| `int`               | `0`              | The number of times the file has been edited.    |

### Parameters and Validation

- `file_path`: A string representing the file path.
- `file_type`: A string representing the file type. This attribute is validated to ensure it matches supported file types based on the file extension if not provided.
- `contents`: A string representing the contents of the file. Defaults to an empty string.
- `versions`: A list of `FileVersion` instances representing the version history of the file. Defaults to an empty list.
- `edit_count`: An integer representing the number of edits made to the file. Defaults to 0.

### Methods

The `Artifact` class includes various methods for creating, editing, saving, loading, and exporting file artifacts.

#### `create`

| Parameter          | Type   | Description                            |
|--------------------|--------|----------------------------------------|
| `initial_content`  | `str`  | The initial content of the file.       |

**Usage Example:**

```python
artifact = Artifact(file_path="example.txt", file_type="txt")
artifact.create(initial_content="Initial file content")
```
The file type parameter supports the following file types: `.txt`, `.md`, `.py`, `.pdf`.
#### `edit`


| Parameter     | Type   | Description                            |
|---------------|--------|----------------------------------------|
| `new_content` | `str`  | The new content of the file.           |

**Usage Example:**

```python
artifact.edit(new_content="Updated file content")
```

#### `save`

**Usage Example:**

```python
artifact.save()
```

#### `load`

**Usage Example:**

```python
artifact.load()
```

#### `get_version`


| Parameter         | Type  | Description                             |
|-------------------|-------|-----------------------------------------|
| `version_number`  | `int` | The version number to retrieve.         |

**Usage Example:**

```python
version = artifact.get_version(version_number=1)
```

#### `get_contents`

**Usage Example:**

```python
current_contents = artifact.get_contents()
```

#### `get_version_history`


**Usage Example:**

```python
version_history = artifact.get_version_history()
```

#### `export_to_json`


| Parameter   | Type  | Description                                  |
|-------------|-------|----------------------------------------------|
| `file_path` | `str` | The path to the JSON file to save the artifact.|

**Usage Example:**

```python
artifact.export_to_json(file_path="artifact.json")
```

#### `import_from_json`


| Parameter   | Type  | Description                                      |
|-------------|-------|--------------------------------------------------|
| `file_path` | `str` | The path to the JSON file to import the artifact from.|

**Usage Example:**

```python
imported_artifact = Artifact.import_from_json(file_path="artifact.json")
```

#### `get_metrics`

**Usage Example:**

```python
metrics = artifact.get_metrics()
```

#### `to_dict`

**Usage Example:**

```python
artifact_dict = artifact.to_dict()
```

#### `from_dict`

| Parameter | Type             | Description                                      |
|-----------|------------------|--------------------------------------------------|
| `data`    | `Dict[str, Any]` | The dictionary representation of the artifact.   |

**Usage Example:**

```python
artifact_data = {
    "file_path": "example.txt",
    "file_type": "txt",
    "contents": "File content",
    "versions": [],
    "edit_count": 0
}
artifact = Artifact.from_dict(artifact_data)
```

## Additional Information and Tips

- The `Artifact` class uses the `pydantic` library to handle data validation and serialization.
- When editing the artifact, ensure that the `file_path` is set correctly to avoid file operation errors.
- Use the `get_version` and `get_version_history` methods to maintain a clear audit trail of changes to the file.
- The `export_to_json` and `import_from_json` methods are useful for backing up and restoring the state of an artifact.

## References and Resources

- [Pydantic Documentation](https://pydantic-docs.helpmanual.io/)
- [Python os.path module](https://docs.python.org/3/library/os.path.html)
- [JSON Documentation](https://docs.python.org/3/library/json.html)

## Examples of Usage

### Example 1: Creating and Editing an Artifact

```python
from datetime import datetime
from pydantic import BaseModel, Field, validator
from typing import List, Dict, Any, Union
import os
import json

# Define FileVersion class
class FileVersion(BaseModel):
    version_number: int
    content: str
    timestamp: datetime

# Artifact class definition goes here

# Create an artifact
artifact = Artifact(file_path="example.txt", file_type="txt")
artifact.create(initial_content="Initial file content")

# Edit the artifact
artifact.edit(new_content="Updated file content")

# Save the artifact to a file
artifact.save()

# Load the artifact from the file
artifact.load()

# Print the current contents of the artifact
print(artifact.get_contents())

# Print the version history
print(artifact.get_version_history())
```

### Example 2: Exporting and Importing an Artifact

```python
# Export the artifact to a JSON file
artifact.export_to_json(file_path="artifact.json")

# Import

 the artifact from a JSON file
imported_artifact = Artifact.import_from_json(file_path="artifact.json")

# Print the metrics of the imported artifact
print(imported_artifact.get_metrics())
```

### Example 3: Converting an Artifact to and from a Dictionary

```python
# Convert the artifact to a dictionary
artifact_dict = artifact.to_dict()

# Create a new artifact from the dictionary
new_artifact = Artifact.from_dict(artifact_dict)

# Print the metrics of the new artifact
print(new_artifact.get_metrics())
```


--------------------------------------------------

# File: swarms/cli/cli_examples.md

# Swarms CLI Examples

This document provides comprehensive examples of how to use the Swarms CLI for various scenarios. Each example includes the complete command, expected output, and explanation.

## Table of Contents

- [Basic Usage Examples](#basic-usage-examples)
- [Agent Management Examples](#agent-management-examples)
- [Multi-Agent Workflow Examples](#multi-agent-workflow-examples)
- [Configuration Examples](#configuration-examples)
- [Advanced Usage Examples](#advanced-usage-examples)
- [Troubleshooting Examples](#troubleshooting-examples)

## Basic Usage Examples

### 1. Getting Started

#### Check CLI Installation

```bash
swarms help
```

**Expected Output:**
```
  _________                                     
 /   _____/_  _  _______ _______  _____   ______
 \_____  \\ \/ \/ /\__  \\_  __ \/     \ /  ___/
 /        \\     /  / __ \|  | \/  Y Y  \\___ \ 
/_______  / \/\_/  (____  /__|  |__|_|  /____  >
        \/              \/            \/     \/                                

Available Commands
┌─────────────────┬─────────────────────────────────────────────────────────────┐
│ Command         │ Description                                                 │
├─────────────────┼─────────────────────────────────────────────────────────────┤
│ onboarding      │ Start the interactive onboarding process                   │
│ help            │ Display this help message                                  │
│ get-api-key     │ Retrieve your API key from the platform                   │
│ check-login     │ Verify login status and initialize cache                   │
│ run-agents      │ Execute agents from your YAML configuration                │
│ load-markdown   │ Load agents from markdown files with YAML frontmatter     │
│ agent           │ Create and run a custom agent with specified parameters   │
│ auto-upgrade    │ Update Swarms to the latest version                       │
│ book-call       │ Schedule a strategy session with our team                 │
│ autoswarm       │ Generate and execute an autonomous swarm                  │
└─────────────────┴─────────────────────────────────────────────────────────────┘
```

#### Start Onboarding Process
```bash
swarms onboarding
```

This will start an interactive setup process to configure your environment.

#### Get API Key

```bash
swarms get-api-key
```

**Expected Output:**
```
✓ API key page opened in your browser
```

#### Check Login Status

```bash
swarms check-login
```

**Expected Output:**
```
✓ Authentication verified
```

#### Run Environment Setup Check

```bash
swarms setup-check
```

**Expected Output:**
```
🔍 Running Swarms Environment Setup Check

┌─────────────────────────────────────────────────────────────────────────────┐
│ Environment Check Results                                                  │
├─────────┬─────────────────────────┬─────────────────────────────────────────┤
│ Status  │ Check                   │ Details                                │
├─────────┼─────────────────────────┼─────────────────────────────────────────┤
│ ✓       │ Python Version          │ Python 3.11.5                          │
│ ✓       │ Swarms Version          │ Current version: 8.1.1                 │
│ ✓       │ API Keys                │ API keys found: OPENAI_API_KEY         │
│ ✓       │ Dependencies            │ All required dependencies available     │
│ ✓       │ Environment File        │ .env file exists with 1 API key(s)     │
│ ⚠       │ Workspace Directory     │ WORKSPACE_DIR environment variable is not set │
└─────────┴─────────────────────────┴─────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ Setup Check Complete                                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ ⚠️ Some checks failed. Please review the issues above.                    │
└─────────────────────────────────────────────────────────────────────────────┘

💡 Recommendations:
  1. Set WORKSPACE_DIR environment variable: export WORKSPACE_DIR=/path/to/your/workspace

Run 'swarms setup-check' again after making changes to verify.
```

## Agent Management Examples

### 2. Creating Custom Agents

#### Basic Research Agent

```bash
swarms agent \
  --name "Research Assistant" \
  --description "AI research specialist for academic papers" \
  --system-prompt "You are an expert research assistant specializing in academic research. You help users find, analyze, and synthesize information from various sources. Always provide well-structured, evidence-based responses." \
  --task "Research the latest developments in quantum computing and provide a summary of key breakthroughs in the last 2 years" \
  --model-name "gpt-4" \
  --temperature 0.1 \
  --max-loops 3
```

**Expected Output:**
```
Creating custom agent: Research Assistant
[✓] Agent 'Research Assistant' completed the task successfully!

┌─────────────────────────────────────────────────────────────────────────────┐
│ Agent Execution Results                                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│ Agent Name: Research Assistant                                            │
│ Model: gpt-4                                                              │
│ Task: Research the latest developments in quantum computing...            │
│ Result:                                                                   │
│ Recent breakthroughs in quantum computing include:                        │
│ 1. Google's 53-qubit Sycamore processor achieving quantum supremacy      │
│ 2. IBM's 433-qubit Osprey processor...                                   │
│ ...                                                                       │
└─────────────────────────────────────────────────────────────────────────────┘
```

#### Code Review Agent

```bash
swarms agent \
  --name "Code Reviewer" \
  --description "Expert code review assistant with security focus" \
  --system-prompt "You are a senior software engineer specializing in code review, security analysis, and best practices. Review code for bugs, security vulnerabilities, performance issues, and adherence to coding standards." \
  --task "Review this Python code for security vulnerabilities and suggest improvements: def process_user_input(data): return eval(data)" \
  --model-name "gpt-4" \
  --temperature 0.05 \
  --max-loops 2 \
  --verbose
```

#### Financial Analysis Agent

```bash
swarms agent \
  --name "Financial Analyst" \
  --description "Expert financial analyst for market research and investment advice" \
  --system-prompt "You are a certified financial analyst with expertise in market analysis, investment strategies, and risk assessment. Provide data-driven insights and recommendations based on current market conditions." \
  --task "Analyze the current state of the technology sector and provide investment recommendations for the next quarter" \
  --model-name "gpt-4" \
  --temperature 0.2 \
  --max-loops 2 \
  --output-type "json"
```

### 3. Advanced Agent Configuration

#### Agent with Dynamic Features

```bash
swarms agent \
  --name "Adaptive Writer" \
  --description "Content writer with dynamic temperature and context adjustment" \
  --system-prompt "You are a professional content writer who adapts writing style based on audience and context. You can write in various tones from formal to casual, and adjust complexity based on the target audience." \
  --task "Write a blog post about artificial intelligence for a general audience, explaining complex concepts in simple terms" \
  --model-name "gpt-4" \
  --dynamic-temperature-enabled \
  --dynamic-context-window \
  --context-length 8000 \
  --retry-attempts 3 \
  --return-step-meta \
  --autosave \
  --saved-state-path "./agent_states/"
```

#### Agent with MCP Integration

```bash
swarms agent \
  --name "MCP Agent" \
  --description "Agent with Model Context Protocol integration" \
  --system-prompt "You are a agent with access to external tools and data sources through MCP. Use these capabilities to provide comprehensive and up-to-date information." \
  --task "Search for recent news about climate change and summarize the key findings" \
  --model-name "gpt-4" \
  --mcp-url "https://api.example.com/mcp" \
  --temperature 0.1 \
  --max-loops 5
```

## Multi-Agent Workflow Examples

### 4. Running Agents from YAML Configuration

#### Create `research_team.yaml`

```yaml
agents:
  - name: "Data Collector"
    description: "Specialist in gathering and organizing data from various sources"
    model_name: "gpt-4"
    system_prompt: "You are a data collection specialist. Your role is to gather relevant information from multiple sources and organize it in a structured format."
    temperature: 0.1
    max_loops: 3
    
  - name: "Data Analyzer"
    description: "Expert in analyzing and interpreting complex datasets"
    model_name: "gpt-4"
    system_prompt: "You are a data analyst. Take the collected data and perform comprehensive analysis to identify patterns, trends, and insights."
    temperature: 0.2
    max_loops: 4
    
  - name: "Report Writer"
    description: "Professional writer who creates clear, compelling reports"
    model_name: "gpt-4"
    system_prompt: "You are a report writer. Take the analyzed data and create a comprehensive, well-structured report that communicates findings clearly."
    temperature: 0.3
    max_loops: 3
```

#### Execute the Team

```bash
swarms run-agents --yaml-file research_team.yaml
```

**Expected Output:**
```
Loading agents from research_team.yaml...
[✓] Agents completed their tasks successfully!

Results:
Data Collector: [Collected data from 15 sources...]
Data Analyzer: [Identified 3 key trends and 5 significant patterns...]
Report Writer: [Generated comprehensive 25-page report...]
```

### 5. Loading Agents from Markdown

#### Create `agents/researcher.md`

```markdown
---
name: Market Researcher
description: Expert in market research and competitive analysis
model_name: gpt-4
temperature: 0.1
max_loops: 3
---

You are an expert market researcher with 15+ years of experience in competitive analysis, market sizing, and trend identification. You specialize in technology markets and have deep knowledge of consumer behavior, pricing strategies, and market dynamics.

Your approach includes:
- Systematic data collection from multiple sources
- Quantitative and qualitative analysis
- Competitive landscape mapping
- Market opportunity identification
- Risk assessment and mitigation strategies
```

#### Create `agents/analyst.md`

```markdown
---
name: Business Analyst
description: Strategic business analyst focusing on growth opportunities
model_name: gpt-4
temperature: 0.2
max_loops: 4
---

You are a senior business analyst specializing in strategic planning and growth strategy. You excel at identifying market opportunities, analyzing competitive advantages, and developing actionable business recommendations.

Your expertise covers:
- Market opportunity analysis
- Competitive positioning
- Business model innovation
- Risk assessment
- Strategic planning frameworks
```

#### Load and Use Agents

```bash
swarms load-markdown --markdown-path ./agents/ --concurrent
```

**Expected Output:**
```
Loading agents from markdown: ./agents/
✓ Successfully loaded 2 agents!

┌─────────────────────────────────────────────────────────────────────────────┐
│ Loaded Agents                                                              │
├─────────────────┬──────────────┬───────────────────────────────────────────┤
│ Name            │ Model        │ Description                               │
├─────────────────┼──────────────┼───────────────────────────────────────────┤
│ Market Researcher│ gpt-4        │ Expert in market research and competitive │
│                 │              │ analysis                                  │
├─────────────────┼──────────────┼───────────────────────────────────────────┤
│ Business Analyst│ gpt-4        │ Strategic business analyst focusing on    │
│                 │              │ growth opportunities                      │
└─────────────────┴──────────────┴───────────────────────────────────────────┘

Ready to use 2 agents!
You can now use these agents in your code or run them interactively.
```

## Configuration Examples

### 6. YAML Configuration Templates

#### Simple Agent Configuration

```yaml
# simple_agent.yaml
agents:
  - name: "Simple Assistant"
    description: "Basic AI assistant for general tasks"
    model_name: "gpt-3.5-turbo"
    system_prompt: "You are a helpful AI assistant."
    temperature: 0.7
    max_loops: 1
```

#### Advanced Multi-Agent Configuration

```yaml
# advanced_team.yaml
agents:
  - name: "Project Manager"
    description: "Coordinates team activities and ensures project success"
    model_name: "gpt-4"
    system_prompt: "You are a senior project manager with expertise in agile methodologies, risk management, and team coordination."
    temperature: 0.1
    max_loops: 5
    auto_generate_prompt: true
    dynamic_temperature_enabled: true
    
  - name: "Technical Lead"
    description: "Provides technical guidance and architecture decisions"
    model_name: "gpt-4"
    system_prompt: "You are a technical lead with deep expertise in software architecture, system design, and technical decision-making."
    temperature: 0.2
    max_loops: 4
    context_length: 12000
    retry_attempts: 3
    
  - name: "Quality Assurance"
    description: "Ensures quality standards and testing coverage"
    model_name: "gpt-4"
    system_prompt: "You are a QA specialist focused on quality assurance, testing strategies, and process improvement."
    temperature: 0.1
    max_loops: 3
    return_step_meta: true
    dashboard: true
```

### 7. Markdown Configuration Templates

#### Research Agent Template

```markdown
---
name: Research Specialist
description: Academic research and literature review expert
model_name: gpt-4
temperature: 0.1
max_loops: 5
context_length: 16000
auto_generate_prompt: true
---

You are a research specialist with expertise in academic research methodologies, literature review, and scholarly writing. You excel at:

- Systematic literature reviews
- Research methodology design
- Data analysis and interpretation
- Academic writing and citation
- Research gap identification

Always provide evidence-based responses and cite relevant sources when possible.
```

#### Creative Writing Agent Template

```markdown
---
name: Creative Writer
description: Professional creative writer and storyteller
model_name: gpt-4
temperature: 0.8
max_loops: 3
dynamic_temperature_enabled: true
output_type: markdown
---

You are a creative writer with a passion for storytelling, character development, and engaging narratives. You specialize in:

- Fiction writing across multiple genres
- Character development and dialogue
- Plot structure and pacing
- Creative problem-solving
- Engaging opening hooks and satisfying conclusions

Your writing style is adaptable, engaging, and always focused on creating memorable experiences for readers.
```

## Advanced Usage Examples

### 8. Autonomous Swarm Generation

#### Simple Task
```bash
swarms autoswarm \
  --task "Create a weekly meal plan for a family of 4 with dietary restrictions" \
  --model "gpt-4"
```

#### Complex Research Task
```bash
swarms autoswarm \
  --task "Conduct a comprehensive analysis of the impact of artificial intelligence on job markets, including historical trends, current state, and future projections. Include case studies from different industries and recommendations for workforce adaptation." \
  --model "gpt-4"
```

### 9. Integration Examples

#### CI/CD Pipeline Integration
```yaml
# .github/workflows/swarms-test.yml
name: Swarms Agent Testing
on: [push, pull_request]

jobs:
  test-agents:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: |
          pip install swarms
             - name: Run Swarms Agents
         run: |
           swarms run-agents --yaml-file ci_agents.yaml
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
```

#### Shell Script Integration
```bash
#!/bin/bash
# run_daily_analysis.sh

echo "Starting daily market analysis..."

# Run market research agent
swarms agent \
  --name "Daily Market Analyzer" \
  --description "Daily market analysis and reporting" \
  --system-prompt "You are a market analyst providing daily market insights." \
  --task "Analyze today's market movements and provide key insights" \
  --model-name "gpt-4" \
  --temperature 0.1

# Run risk assessment agent
swarms agent \
  --name "Risk Assessor" \
  --description "Risk assessment and mitigation specialist" \
  --system-prompt "You are a risk management expert." \
  --task "Assess current market risks and suggest mitigation strategies" \
  --model-name "gpt-4" \
  --temperature 0.2

echo "Daily analysis complete!"
```

## Troubleshooting Examples

### 10. Common Error Scenarios

#### Missing API Key
```bash
swarms agent \
  --name "Test Agent" \
  --description "Test" \
  --system-prompt "Test" \
  --task "Test"
```

**Expected Error:**
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ Error                                                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│ Failed to create or run agent: No API key found                           │
└─────────────────────────────────────────────────────────────────────────────┘

Please check:
1. Your API keys are set correctly
2. The model name is valid
3. All required parameters are provided
4. Your system prompt is properly formatted
```

**Resolution:**
```bash
export OPENAI_API_KEY="your-api-key-here"
```

#### Invalid YAML Configuration
```bash
swarms run-agents --yaml-file invalid.yaml
```

**Expected Error:**
```
┌─────────────────────────────────────────────────────────────────────────────┘
│ Configuration Error                                                        │
├─────────────────────────────────────────────────────────────────────────────┤
│ Error parsing YAML: Invalid YAML syntax                                   │
└─────────────────────────────────────────────────────────────────────────────┘

Please check your agents.yaml file format.
```

#### File Not Found
```bash
swarms load-markdown --markdown-path ./nonexistent/
```

**Expected Error:**
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ File Error                                                                │
├─────────────────────────────────────────────────────────────────────────────┤
│ Markdown file/directory not found: ./nonexistent/                         │
└─────────────────────────────────────────────────────────────────────────────┘

Please make sure the path exists and you're in the correct directory.
```

### 11. Debug Mode Usage

#### Enable Verbose Output
```bash
swarms agent \
  --name "Debug Agent" \
  --description "Agent for debugging" \
  --system-prompt "You are a debugging assistant." \
  --task "Help debug this issue" \
  --model-name "gpt-4" \
  --verbose
```

This will provide detailed output including:
- Step-by-step execution details
- API call information
- Internal state changes
- Performance metrics

## Environment Setup

### 12. Environment Verification

The `setup-check` command is essential for ensuring your environment is properly configured:

```bash
# Run comprehensive environment check
swarms setup-check
```

This command checks:
- Python version compatibility (3.10+)
- Swarms package version and updates
- API key configuration
- Required dependencies
- Environment file setup
- Workspace directory configuration

**Use Cases:**
- **Before starting a new project**: Verify all requirements are met
- **After environment changes**: Confirm configuration updates
- **Troubleshooting**: Identify missing dependencies or configuration issues
- **Team onboarding**: Ensure consistent environment setup across team members

## Best Practices

### 13. Performance Optimization

#### Use Concurrent Processing
```bash
# For multiple markdown files
swarms load-markdown \
  --markdown-path ./large_agent_directory/ \
  --concurrent
```

#### Optimize Model Selection
```bash
# For simple tasks
--model-name "gpt-3.5-turbo" --temperature 0.1

# For complex reasoning
--model-name "gpt-4" --temperature 0.1 --max-loops 5
```

#### Context Length Management
```bash
# For long documents
--context-length 16000 --dynamic-context-window

# For concise responses
--context-length 4000 --max-loops 2
```

### 14. Security Considerations

#### Environment Variable Usage
```bash
# Secure API key management
export OPENAI_API_KEY="your-secure-key"
export ANTHROPIC_API_KEY="your-secure-key"

# Use in CLI
swarms agent [options]
```

#### File Permissions
```bash
# Secure configuration files
chmod 600 agents.yaml
chmod 600 .env
```

## Summary

The Swarms CLI provides a powerful and flexible interface for managing AI agents and multi-agent workflows. These examples demonstrate:

| Feature                | Description                                             |
|------------------------|---------------------------------------------------------|
| **Basic Usage**        | Getting started with the CLI                            |
| **Agent Management**   | Creating and configuring custom agents                  |
| **Multi-Agent Workflows** | Coordinating multiple agents                        |
| **Configuration**      | YAML and markdown configuration formats                 |
| **Environment Setup**  | Environment verification and setup checks               |
| **Advanced Features**  | Dynamic configuration and MCP integration               |
| **Troubleshooting**    | Common issues and solutions                             |
| **Best Practices**     | Performance and security considerations                 |

For more information, refer to the [CLI Reference](cli_reference.md) documentation.


--------------------------------------------------

# File: swarms/cli/cli_guide.md

# The Ultimate Technical Guide to the Swarms CLI: A Step-by-Step Developer’s Guide

Welcome to the definitive technical guide for using the Swarms Command Line Interface (CLI). The Swarms CLI enables developers, engineers, and business professionals to seamlessly manage and run Swarms of agents from the command line. This guide will walk you through the complete process of installing, configuring, and using the Swarms CLI to orchestrate intelligent agents for your needs.

By following this guide, you will not only understand how to install and use the Swarms CLI but also learn about real-world use cases, including how the CLI is used to automate tasks across various industries, from finance to marketing, operations, and beyond.

Explore the official [Swarms GitHub repository](https://github.com/kyegomez/swarms), dive into the comprehensive documentation at [Swarms Docs](https://docs.swarms.world), and explore the vast marketplace of agents on [swarms.ai](https://swarms.ai) to kickstart your journey with Swarms!

---

## 1. Installing the Swarms CLI

Before we explore the Swarms CLI commands, let’s get it installed and running on your machine.

### 1.1. Installation Using `pip`

For most users, the simplest way to install the Swarms CLI is through `pip`:

```bash
pip3 install -U swarms
```

This command installs the latest version of the Swarms CLI package, ensuring that you have the newest features and fixes.

### 1.2. Installation Using `Poetry`

Alternatively, if you are using `Poetry` as your Python package manager, you can add the Swarms package like this:

```bash
poetry add swarms
```

Once installed, you can run the Swarms CLI directly using:

```bash
poetry run swarms help
```

This command shows all the available options and commands, as we will explore in-depth below.

---

## 2. Understanding Swarms CLI Commands

With the Swarms CLI installed, the next step is to explore its key functionalities. Here are the most essential commands:

### 2.1. `onboarding`: Setup Your Environment

The `onboarding` command guides you through setting up your environment and configuring the agents for your Swarms.

```bash
swarms onboarding
```

This is the first step when you begin working with the Swarms platform. It helps to:

- Authenticate your Swarms account.
- Download any necessary configurations.
- Ensure everything is in place to launch agents seamlessly.

### 2.2. `help`: Learn Available Commands

Running `help` displays the various commands you can use:

```bash
swarms help
```

This command will output a helpful list like the one shown below, including detailed descriptions of each command.

```plaintext
Swarms CLI - Help

Commands:
onboarding    : Starts the onboarding process
help          : Shows this help message
get-api-key   : Retrieves your API key from the platform
check-login   : Checks if you're logged in and starts the cache
read-docs     : Redirects you to swarms cloud documentation
run-agents    : Run your Agents from your agents.yaml
```

### 2.3. `get-api-key`: Access API Integration

One of the key functionalities of the Swarms platform is integrating your agents with the Swarms API. To retrieve your unique API key for communication, use this command:

```bash
swarms get-api-key
```

Your API key is essential to enable agent workflows and access various services through the Swarms platform.

### 2.4. `check-login`: Verify Authentication

Use the `check-login` command to verify if you're logged in and ensure that your credentials are cached:

```bash
swarms check-login
```

This ensures seamless operation, allowing agents to execute tasks securely on the Swarms platform without needing to log in repeatedly.

### 2.5. `read-docs`: Explore Official Documentation

Easily access the official documentation with this command:

```bash
swarms read-docs
```

You’ll be redirected to the Swarms documentation site, [Swarms Docs](https://docs.swarms.world), where you'll find in-depth explanations, advanced use-cases, and more.

### 2.6. `run-agents`: Orchestrate Agents

Perhaps the most important command in the CLI is `run-agents`, which allows you to execute your agents as defined in your `agents.yaml` configuration file.

```bash
swarms run-agents --yaml-file agents.yaml
```

If you want to specify a custom configuration file, just pass in the YAML file using the `--yaml-file` flag.

---

## 3. Working with the `agents.yaml` Configuration File

The `agents.yaml` file is at the heart of your Swarms setup. This file allows you to define the structure and behavior of each agent you want to run. Below is an example YAML configuration for two agents.

### 3.1. Example `agents.yaml` Configuration:

```yaml
agents:
  - agent_name: "Financial-Advisor-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.3
      max_tokens: 2500
    system_prompt: |
      You are a highly knowledgeable financial advisor with expertise in tax strategies, investment management, and retirement planning. 
      Provide concise and actionable advice based on the user's financial goals and situation.
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "financial_advisor_state.json"
    user_name: "finance_user"
    retry_attempts: 2
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    task: "I am 35 years old with a moderate risk tolerance. How should I diversify my portfolio for retirement in 20 years?"

  - agent_name: "Stock-Market-Analysis-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.25
      max_tokens: 1800
    system_prompt: |
      You are an expert stock market analyst with a deep understanding of technical analysis, market trends, and long-term investment strategies. 
      Provide well-reasoned investment advice, taking current market conditions into account.
    max_loops: 2
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: false
    saved_state_path: "stock_market_analysis_state.json"
    user_name: "market_analyst"
    retry_attempts: 3
    context_length: 150000
    return_step_meta: true
    output_type: "json"
    task: "Analyze the current market trends for tech stocks and suggest the best long-term investment options."

  - agent_name: "Marketing-Strategy-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.4
      max_tokens: 2200
    system_prompt: |
      You are a marketing strategist with expertise in digital campaigns, customer engagement, and branding. 
      Provide a comprehensive marketing strategy to increase brand awareness and drive customer acquisition for an e-commerce business.
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "marketing_strategy_state.json"
    user_name: "marketing_user"
    retry_attempts: 2
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    task: "Create a 6-month digital marketing strategy for a new eco-friendly e-commerce brand targeting millennial consumers."

  - agent_name: "Operations-Optimizer-Agent"
    model:
      model_name: "gpt-4o-mini"
      temperature: 0.2
      max_tokens: 2000
    system_prompt: |
      You are an operations expert with extensive experience in optimizing workflows, reducing costs, and improving efficiency in supply chains. 
      Provide actionable recommendations to streamline business operations.
    max_loops: 1
    autosave: true
    dashboard: false
    verbose: true
    dynamic_temperature_enabled: true
    saved_state_path: "operations_optimizer_state.json"
    user_name: "operations_user"
    retry_attempts: 1
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    task: "Identify ways to improve the efficiency of a small manufacturing company’s supply chain to reduce costs by 15% within one year."
```

### 3.2. Explanation of Key Fields

- **agent_name**: The name of your agent (e.g., Financial-Analysis-Agent).
- **model**: Specifies which model to use. In this case, `gpt-4o-mini` is used.
  - **temperature**: Controls the randomness of the model’s responses.
  - **max_tokens**: The maximum number of tokens to generate.
- **system_prompt**: Defines the prompt that instructs the agent.
- **max_loops**: Limits the number of times the agent will retry tasks.
- **autosave**: Saves the agent's state automatically after each run.
- **dashboard**: Set to `true` or `false` depending on whether you want to enable the agent’s dashboard.
- **saved_state_path**: Path to save agent's state, enabling future runs to resume from the last state.
- **task**: The primary task or question that the agent will address.

### 3.3. Running Agents Using `agents.yaml`

After configuring the agents, you can execute them directly from the CLI:

```bash
swarms run-agents --yaml-file agents_config.yaml
```

This command will run the specified agents, allowing them to perform their tasks and return results according to your configuration.

---

## 4. Use Cases for the Swarms CLI

Now that you have a solid understanding of the basic commands and the `agents.yaml` configuration, let's explore how the Swarms CLI can be applied in real-world scenarios.

### 4.1. Financial Data Analysis

For financial firms or hedge funds, agents like the "Financial-Analysis-Agent" can be set up to automate complex financial analyses. You could have agents analyze market trends, recommend portfolio adjustments, or perform tax optimizations.

Example Task: Automating long-term investment analysis using historical stock data.

```bash
swarms run-agents --yaml-file finance_analysis.yaml
```

### 4.2. Marketing Automation

Marketing departments can utilize Swarms agents to optimize campaigns, generate compelling ad copy, or provide detailed marketing insights. You can create a `Marketing-Agent` to process customer feedback, perform sentiment analysis, and suggest marketing strategies.

Example Task: Running multiple agents to analyze customer sentiment from recent surveys.

```bash
swarms run-agents --yaml-file marketing_agents.yaml
```

### 4.3. Operations and Task Management

Companies can create agents for automating internal task management. For example, you might have a set of agents responsible for managing deadlines, employee tasks, and progress tracking.

Example Task: Automating a task management system using Swarms agents.

```bash
swarms run-agents --yaml-file operations_agents.yaml
```

---

## 5. Advanced Usage: Customizing and Scaling Agents

The Swarms CLI is flexible and scalable. As your needs grow, you can start running agents across multiple machines, scale workloads dynamically, and even run multiple swarms in parallel.

### 5.1. Running Agents in Parallel

To run multiple agents concurrently, you can utilize different YAML configurations for each agent or group of agents. This allows for extensive scaling, especially when dealing with large datasets or complex workflows.

```bash
swarms run-agents --yaml-file agents_batch_1.yaml &
swar

ms run-agents --yaml-file agents_batch_2.yaml &
```

### 5.2. Integration with Other Tools

The Swarms CLI integrates with many tools and platforms via APIs. You can connect Swarms with external platforms such as AWS, Azure, or your custom cloud setup for enterprise-level automation.

---

## 6. Conclusion and Next Steps

The Swarms CLI is a powerful tool for automating agent workflows in various industries, including finance, marketing, and operations. By following this guide, you should now have a thorough understanding of how to install and use the CLI, configure agents, and apply it to real-world use cases.

To further explore Swarms, be sure to check out the official [Swarms GitHub repository](https://github.com/kyegomez/swarms), where you can contribute to the framework or build your own custom agents. Dive deeper into the documentation at [Swarms Docs](https://docs.swarms.world), and browse the extensive agent marketplace at [swarms.ai](https://swarms.ai).

With the Swarms CLI, the future of automation is within reach.



--------------------------------------------------

# File: swarms/cli/cli_reference.md

# Swarms CLI Reference

The Swarms CLI is a comprehensive command-line interface for managing and executing Swarms agents and multi-agent architectures. This reference documents all available commands, arguments, and features.

## Table of Contents

- [Installation](#installation)

- [Basic Usage](#basic-usage)

- [Commands Reference](#commands-reference)

- [Global Arguments](#global-arguments)

- [Command-Specific Arguments](#command-specific-arguments)

- [Error Handling](#error-handling)

- [Examples](#examples)

- [Configuration](#configuration)


## Installation

The CLI is included with the Swarms package installation:

```bash
pip install swarms
```

## Basic Usage

```bash
swarms <command> [options]
```

## Commands Reference

### Core Commands

| Command | Description | Required Arguments |
|---------|-------------|-------------------|
| `onboarding` | Start interactive onboarding process | None |
| `help` | Display help message | None |
| `get-api-key` | Open API key portal in browser | None |
| `check-login` | Verify login status and initialize cache | None |
| `run-agents` | Execute agents from YAML configuration | `--yaml-file` |
| `load-markdown` | Load agents from markdown files | `--markdown-path` |
| `agent` | Create and run custom agent | `--name`, `--description`, `--system-prompt`, `--task` |
| `auto-upgrade` | Update Swarms to latest version | None |
| `book-call` | Schedule strategy session | None |
| `autoswarm` | Generate and execute autonomous swarm | `--task`, `--model` |
| `setup-check` | Run comprehensive environment setup check | None |

## Global Arguments

All commands support these global options:

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `--verbose` | `bool` | `False` | Enable verbose output |
| `--help`, `-h` | `bool` | `False` | Show help message |

## Command-Specific Arguments

### `run-agents` Command

Execute agents from YAML configuration files.

```bash
python -m swarms.cli.main run-agents [options]
```

| Argument | Type | Default | Required | Description |
|----------|------|---------|----------|-------------|
| `--yaml-file` | `str` | `"agents.yaml"` | No | Path to YAML configuration file |

**Example:**
```bash
swarms run-agents --yaml-file my_agents.yaml
```

### `load-markdown` Command

Load agents from markdown files with YAML frontmatter.

```bash
python -m swarms.cli.main load-markdown [options]
```

| Argument | Type | Default | Required | Description |
|----------|------|---------|----------|-------------|
| `--markdown-path` | `str` | `None` | **Yes** | Path to markdown file or directory |
| `--concurrent` | `bool` | `True` | No | Enable concurrent processing for multiple files |

**Example:**
```bash
swarms load-markdown --markdown-path ./agents/ --concurrent
```

### `agent` Command

Create and run a custom agent with specified parameters.

```bash
python -m swarms.cli.main agent [options]
```

#### Required Arguments

| Argument | Type | Description |
|----------|------|-------------|
| `--name` | `str` | Name of the custom agent |
| `--description` | `str` | Description of the custom agent |
| `--system-prompt` | `str` | System prompt for the custom agent |
| `--task` | `str` | Task for the custom agent to execute |

#### Optional Arguments

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| `--model-name` | `str` | `"gpt-4"` | Model name for the custom agent |
| `--temperature` | `float` | `None` | Temperature setting (0.0-2.0) |
| `--max-loops` | `int` | `None` | Maximum number of loops for the agent |
| `--auto-generate-prompt` | `bool` | `False` | Enable auto-generation of prompts |
| `--dynamic-temperature-enabled` | `bool` | `False` | Enable dynamic temperature adjustment |
| `--dynamic-context-window` | `bool` | `False` | Enable dynamic context window |
| `--output-type` | `str` | `None` | Output type (e.g., 'str', 'json') |
| `--verbose` | `bool` | `False` | Enable verbose mode for the agent |
| `--streaming-on` | `bool` | `False` | Enable streaming mode for the agent |
| `--context-length` | `int` | `None` | Context length for the agent |
| `--retry-attempts` | `int` | `None` | Number of retry attempts for the agent |
| `--return-step-meta` | `bool` | `False` | Return step metadata from the agent |
| `--dashboard` | `bool` | `False` | Enable dashboard for the agent |
| `--autosave` | `bool` | `False` | Enable autosave for the agent |
| `--saved-state-path` | `str` | `None` | Path for saving agent state |
| `--user-name` | `str` | `None` | Username for the agent |
| `--mcp-url` | `str` | `None` | MCP URL for the agent |

**Example:**
```bash
swarms agent \
  --name "Trading Agent" \
  --description "Advanced trading agent for market analysis" \
  --system-prompt "You are an expert trader..." \
  --task "Analyze market trends for AAPL" \
  --model-name "gpt-4" \
  --temperature 0.1 \
  --max-loops 5
```

### `autoswarm` Command

Generate and execute an autonomous swarm configuration.

```bash
swarms autoswarm [options]
```

| Argument | Type | Default | Required | Description |
|----------|------|---------|----------|-------------|
| `--task` | `str` | `None` | **Yes** | Task description for the swarm |
| `--model` | `str` | `None` | **Yes** | Model name to use for the swarm |

**Example:**

```bash
swarms autoswarm --task "analyze this data" --model "gpt-4"
```

### `setup-check` Command

Run a comprehensive environment setup check to verify your Swarms installation and configuration.

```bash
swarms setup-check [--verbose]
```

**Arguments:**
- `--verbose`: Enable detailed debug output showing version detection methods

This command performs the following checks:
- **Python Version**: Verifies Python 3.10+ compatibility
- **Swarms Version**: Checks current version and compares with latest available
- **API Keys**: Verifies presence of common API keys in environment variables
- **Dependencies**: Ensures required packages are available
- **Environment File**: Checks for .env file existence and content
- **Workspace Directory**: Verifies WORKSPACE_DIR environment variable

**Examples:**
```bash
# Basic setup check
swarms setup-check

# Verbose setup check with debug information
swarms setup-check --verbose
```

**Expected Output:**
```
🔍 Running Swarms Environment Setup Check

┌─────────────────────────────────────────────────────────────────────────────┐
│ Environment Check Results                                                  │
├─────────┬─────────────────────────┬─────────────────────────────────────────┤
│ Status  │ Check                   │ Details                                │
├─────────┼─────────────────────────┼─────────────────────────────────────────┤
│ ✓       │ Python Version          │ Python 3.11.5                          │
│ ✓       │ Swarms Version          │ Current version: 8.1.1                 │
│ ✓       │ API Keys                │ API keys found: OPENAI_API_KEY         │
│ ✓       │ Dependencies            │ All required dependencies available     │
│ ✓       │ Environment File        │ .env file exists with 1 API key(s)     │
│ ✓       │ Workspace Directory     │ WORKSPACE_DIR is set to: /path/to/ws   │
└─────────┴─────────────────────────┴─────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│ Setup Check Complete                                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│ 🎉 All checks passed! Your environment is ready for Swarms.               │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Error Handling

The CLI provides comprehensive error handling with formatted error messages:

### Error Types

| Error Type | Description | Resolution |
|------------|-------------|------------|
| `FileNotFoundError` | Configuration file not found | Check file path and permissions |
| `ValueError` | Invalid configuration format | Verify YAML/markdown syntax |
| `SwarmCLIError` | Custom CLI-specific errors | Check command arguments and API keys |
| `API Key Error` | Authentication issues | Verify API key configuration |
| `Context Length Error` | Model context exceeded | Reduce input size or use larger model |

### Error Display Format

Errors are displayed in formatted panels with:

- **Error Title**: Clear error identification

- **Error Message**: Detailed error description

- **Help Text**: Suggested resolution steps

- **Color Coding**: Red borders for errors, yellow for warnings


## Examples

### Basic Agent Creation

```bash
# Create a simple agent
swarms agent \
  --name "Code Reviewer" \
  --description "AI code review assistant" \
  --system-prompt "You are an expert code reviewer..." \
  --task "Review this Python code for best practices" \
  --model-name "gpt-4" \
  --temperature 0.1
```

### Loading Multiple Agents

```bash
# Load agents from markdown directory
swarms load-markdown \
  --markdown-path ./my_agents/ \
  --concurrent
```

### Running YAML Configuration

```bash
# Execute agents from YAML file
swarms run-agents \
  --yaml-file production_agents.yaml
```

### Autonomous Swarm Generation

```bash
# Generate swarm for complex task
swarms autoswarm \
  --task "Create a comprehensive market analysis report for tech stocks" \
  --model "gpt-4"
```

## Configuration

### YAML Configuration Format

For `run-agents` command, use this YAML structure:

```yaml
agents:
  - name: "Research Agent"

    description: "Research and analysis specialist"
    model_name: "gpt-4"
    system_prompt: "You are a research specialist..."
    temperature: 0.1
    max_loops: 3
    
  - name: "Analysis Agent"

    description: "Data analysis expert"
    model_name: "gpt-4"
    system_prompt: "You are a data analyst..."
    temperature: 0.2
    max_loops: 5
```

### Markdown Configuration Format

For `load-markdown` command, use YAML frontmatter:

```markdown
---
name: Research Agent
description: AI research specialist
model_name: gpt-4
temperature: 0.1
max_loops: 3
---

You are an expert research agent specializing in...
```

## Advanced Features

### Progress Indicators

The CLI provides rich progress indicators for long-running operations:

- **Spinner Animations**: Visual feedback during execution


- **Progress Bars**: For operations with known completion states

- **Status Updates**: Real-time operation status


### Concurrent Processing

Multiple markdown files can be processed concurrently:

- **Parallel Execution**: Improves performance for large directories

- **Resource Management**: Automatic thread management

- **Error Isolation**: Individual file failures don't affect others


### Auto-upgrade System

```bash
swarms auto-upgrade
```

Automatically updates Swarms to the latest version with:

- Version checking

- Dependency resolution

- Safe update process


### Interactive Onboarding

```bash
swarms onboarding
```

Guided setup process including:

- API key configuration

- Environment setup

- Basic agent creation

- Usage examples


## Troubleshooting

### Common Issues

1. **API Key Not Set**

   ```bash
   export OPENAI_API_KEY="your-api-key-here"
   ```

2. **File Permissions**
   ```bash
   chmod 644 agents.yaml
   ```

3. **Model Not Available**
   - Verify model name spelling

   - Check API key permissions

   - Ensure sufficient quota


### Debug Mode

Enable verbose output for debugging:

```bash
swarms <command> --verbose
```

## Integration

### CI/CD Integration

The CLI can be integrated into CI/CD pipelines:

```yaml
# GitHub Actions example
- name: Run Swarms Agents

  run: |
    swarms run-agents --yaml-file ci_agents.yaml
```

### Scripting

Use in shell scripts:

```bash
#!/bin/bash
# Run multiple agent configurations
swarms run-agents --yaml-file agents1.yaml
swarms run-agents --yaml-file agents2.yaml
```

## Performance Considerations

| Consideration           | Recommendation                                      |
|------------------------|-----------------------------------------------------|
| Concurrent Processing  | Use `--concurrent` for multiple files               |
| Model Selection        | Choose appropriate models for task complexity        |
| Context Length         | Monitor and optimize input sizes                    |
| Rate Limiting          | Respect API provider limits                         |

## Security

| Security Aspect         | Recommendation                                         |
|------------------------|--------------------------------------------------------|
| API Key Management     | Store keys in environment variables                    |
| File Permissions       | Restrict access to configuration files                 |
| Input Validation       | CLI validates all inputs before execution              |
| Error Sanitization     | Sensitive information is not exposed in errors         |

## Support

For additional support:

| Support Option        | Link                                                                                  |
|----------------------|---------------------------------------------------------------------------------------|
| **Community**        | [Discord](https://discord.gg/EamjgSaEQf)                                              |
| **Issues**           | [GitHub Issues](https://github.com/kyegomez/swarms/issues)                            |
| **Strategy Sessions**| [Book a Call](https://cal.com/swarms/swarms-strategy-session)                         |


--------------------------------------------------

# File: swarms/cli/main.md

# Swarms CLI Documentation

The Swarms Command Line Interface (CLI) allows you to easily manage and run your Swarms of agents from the command line. This page will guide you through the installation process and provide a breakdown of the available commands.

## Installation

You can install the `swarms` package using `pip` or `poetry`.

### Using pip

```bash
pip3 install -U swarms
```

### Using poetry

```bash
poetry add swarms
```

Once installed, you can run the Swarms CLI with the following command:

```bash
poetry run swarms help
```

## Swarms CLI - Help

When running `swarms help`, you'll see the following output:

```
  _________                                     
 /   _____/_  _  _______ _______  _____   ______
 \_____  \ \/ \/ /\__  \_  __ \/     \ /  ___/
 /        \     /  / __ \|  | \/  Y Y  \___ \ 
/_______  / \/\_/  (____  /__|  |__|_|  /____  >
        \/              \/            \/     \/ 



    Swarms CLI - Help

    Commands:
    onboarding    : Starts the onboarding process
    help          : Shows this help message
    get-api-key   : Retrieves your API key from the platform
    check-login   : Checks if you're logged in and starts the cache
    read-docs     : Redirects you to swarms cloud documentation!
    run-agents    : Run your Agents from your agents.yaml

    For more details, visit: https://docs.swarms.world
```

### CLI Commands

Below is a detailed explanation of the available commands:

- **onboarding**  
  Starts the onboarding process to help you set up your environment and configure your agents.
  
  Usage:
  ```bash
  swarms onboarding
  ```

- **help**  
  Displays the help message, including a list of available commands.

  Usage:
  ```bash
  swarms help
  ```

- **get-api-key**  
  Retrieves your API key from the platform, allowing your agents to communicate with the Swarms platform.

  Usage:
  ```bash
  swarms get-api-key
  ```

- **check-login**  
  Verifies if you are logged into the platform and starts the cache for storing your login session.

  Usage:
  ```bash
  swarms check-login
  ```

- **read-docs**  
  Redirects you to the official Swarms documentation on the web for further reading.

  Usage:
  ```bash
  swarms read-docs
  ```

- **run-agents**  
  Executes your agents from the `agents.yaml` configuration file, which defines the structure and behavior of your agents. Refer to this document for how to leverage yamls for fast, reliable, and simple agent orchestration. [CLICK HERE](https://docs.swarms.world/en/latest/swarms/agents/create_agents_yaml/) You can customize what yaml file to run with `--yaml-file`

  Usage:
  ```bash
  swarms run-agents --yaml-file agents.yaml
  ```


--------------------------------------------------

# File: swarms/concept/framework_architecture.md

# Swarms Framework Architecture


The Swarms package is designed to orchestrate and manage **swarms of agents**, enabling collaboration between multiple Large Language Models (LLMs) or other agent types to solve complex tasks. The architecture is modular and scalable, facilitating seamless integration of various agents, models, prompts, and tools. Below is an overview of the architectural components, along with instructions on where to find the corresponding documentation.



```
swarms/
├── agents/
├── artifacts/
├── cli/
├── memory/
├── models/ ---> Moved to swarm_models
├── prompts/
├── schemas/
├── structs/
├── telemetry/
├── tools/
├── utils/
└── __init__.py
```



### Role of Folders in the Swarms Framework

The **Swarms framework** is composed of several key folders, each serving a specific role in building, orchestrating, and managing swarms of agents. Below is an in-depth explanation of the role of each folder in the framework's architecture, focusing on how they contribute to the overall system for handling complex multi-agent workflows.

---

### **1. Agents Folder (`agents/`)**
   - **Role:** 
     - The **agents** folder contains the core logic for individual agents within the Swarms framework. Agents are the key functional units responsible for carrying out specific tasks, whether it be text generation, web scraping, data analysis, or more specialized functions like marketing or accounting.
     - **Customization:** Each agent can be specialized for different tasks by defining custom system prompts and behaviors.
     - **Modular Agent System:** New agents can be easily added to this folder to expand the framework's capabilities.
   - **Importance:** This folder allows users to create and manage multiple types of agents that can interact and collaborate to solve complex problems.
   - **Examples:** Accounting agents, marketing agents, and programming agents.

---

### **2. Artifacts Folder (`artifacts/`)**
   - **Role:** 
     - The **artifacts** folder is responsible for storing the results or outputs generated by agents and swarms. This could include reports, logs, or data that agents generate during task execution.
     - **Persistent Storage:** It helps maintain a persistent record of agent interactions, making it easier to retrieve or review past actions and outputs.
     - **Data Handling:** Users can configure this folder to store artifacts that are essential for later analysis or reporting.
   - **Importance:** Acts as a storage mechanism for important task-related outputs, ensuring that no data is lost after tasks are completed.

---

### **3. CLI Folder (`cli/`)**
   - **Role:** 
     - The **CLI** folder contains tools for interacting with the Swarms framework through the command-line interface. This allows users to easily manage and orchestrate swarms without needing a graphical interface.
     - **Command-line Tools:** Commands in this folder enable users to initiate, control, and monitor swarms, making the system accessible and versatile.
     - **Automation and Scriptability:** Enables advanced users to automate swarm interactions and deploy agents programmatically.
   - **Importance:** Provides a flexible way to control the Swarms system for developers who prefer using the command line.

---

### **4. Memory Folder (`memory/`) Deprecated!!**
   - **Role:** 
     - The **memory** folder handles the framework's memory management for agents. This allows agents to retain and recall past interactions or task contexts, enabling continuity in long-running processes or multi-step workflows.
     - **Context Retention:** Agents that depend on historical context to make decisions or carry out tasks can store and access memory using this folder.
     - **Long-Term and Short-Term Memory:** This could be implemented in various ways, such as short-term conversational memory or long-term knowledge storage.
   - **Importance:** Crucial for agents that require memory to handle complex workflows, where decisions are based on prior outputs or interactions.

---

### **5. Models Folder (`models/`) Moved to `swarm_models`**
   - **Role:** 
     - The **models** folder houses pre-trained machine learning models that agents utilize to complete their tasks. These models could include LLMs (Large Language Models), custom-trained models, or fine-tuned models specific to the tasks being handled by the agents.
     - **Plug-and-Play Architecture:** The framework allows users to easily add or switch models depending on the specific needs of their agents.
     - **Custom Model Support:** Users can integrate custom models here for more specialized tasks.
   - **Importance:** Provides the computational backbone for agent decision-making and task execution.

---

### **6. Prompts Folder (`prompts/`)**
   - **Role:** 
     - The **prompts** folder contains reusable prompt templates that agents use to interact with their environment and complete tasks. These system prompts define the behavior and task orientation of the agents.
     - **Template Reusability:** Users can create and store common prompt templates, making it easy to define agent behavior across different tasks without rewriting prompts from scratch.
     - **Task-Specific Prompts:** For example, an accounting agent may have a prompt template that guides its interaction with financial data.
   - **Importance:** Provides the logic and guidance agents need to generate outputs in a coherent and task-focused manner.

---

### **7. Schemas Folder (`schemas/`)**
   - **Role:** 
     - The **schemas** folder defines the data structures and validation logic for inputs and outputs within the framework, using tools like **Pydantic** for data validation.
     - **Standardization and Validation:** This ensures that all interactions between agents and swarms follow consistent data formats, which is critical for large-scale agent coordination and task management.
     - **Error Prevention:** By validating data early, it prevents errors from propagating through the system, improving reliability.
   - **Importance:** Ensures data consistency across the entire framework, making it easier to integrate and manage swarms of agents at scale.

---

### **8. Structs Folder (`structs/`)**
   - **Role:** 
     - The **structs** folder is the core of the Swarms framework, housing the orchestration logic for managing and coordinating swarms of agents. This folder allows for dynamic task assignment, queue management, inter-agent communication, and result aggregation.
     - **Swarm Management:** Agents are grouped into swarms to handle tasks that require multiple agents working in parallel or collaboratively.
     - **Scalability:** The swarm structure is designed to be scalable, allowing thousands of agents to operate together on distributed tasks.
     - **Task Queueing and Execution:** Supports task queueing, task prioritization, and load balancing between agents.
   - **Importance:** This folder is critical for managing how agents interact and collaborate to solve complex, multi-step problems.

---

### **9. Telemetry Folder (`telemetry/`)**
   - **Role:** 
     - The **telemetry** folder provides logging and monitoring tools to capture agent performance metrics, error handling, and real-time activity tracking. It helps users keep track of what each agent or swarm is doing, making it easier to debug, audit, and optimize operations.
     - **Monitoring:** Tracks agent performance and system health.
     - **Logs:** Maintains logs for troubleshooting and operational review.
   - **Importance:** Provides visibility into the system, ensuring smooth operation and enabling fine-tuning of agent behaviors.

---

### **10. Tools Folder (`tools/`)**
   - **Role:** 
     - The **tools** folder contains specialized utility functions or scripts that agents and swarms may require to complete certain tasks, such as web scraping, API interactions, data parsing, or other external resource handling.
     - **Task-Specific Tools:** Agents can call these tools to perform operations outside of their own logic, enabling them to interact with external systems more efficiently.
   - **Importance:** Expands the capabilities of agents, allowing them to complete more sophisticated tasks by relying on these external tools.

---

### **11. Utils Folder (`utils/`)**
   - **Role:** 
     - The **utils** folder contains general-purpose utility functions that are reused throughout the framework. These may include functions for data formatting, validation, logging setup, and configuration management.
     - **Shared Utilities:** Helps keep the codebase clean by providing reusable functions that multiple agents or parts of the framework can call.
   - **Importance:** Provides common functions that help the Swarms framework operate efficiently and consistently.

---

### **Core Initialization File (`__init__.py`)**
   - **Role:** 
     - The `__init__.py` file is the entry point of the Swarms package, ensuring that all necessary modules, agents, and tools are loaded when the Swarms framework is imported. It allows for the modular loading of different components, making it easier for users to work with only the parts of the framework they need.
   - **Importance:** Acts as the bridge that connects all other components in the framework, enabling the entire package to work together seamlessly.

---

### How to Access Documentation

- **Official Documentation Site:**
  - URL: [docs.swarms.world](https://docs.swarms.world)
  - Here, users can find detailed guides, tutorials, and API references on how to use each of the folders mentioned above. The documentation covers setup, agent orchestration, and practical examples of how to leverage swarms for real-world tasks.

- **GitHub Repository:**
  - URL: [Swarms GitHub](https://github.com/kyegomez/swarms)
  - The repository contains code examples, detailed folder explanations, and further resources on how to get started with building and managing agent swarms.

By understanding the purpose and role of each folder in the Swarms framework, users can more effectively build, orchestrate, and manage agents to handle complex tasks and workflows at scale.

## Support:

- **Post Issue On Github**
  - URL: [Submit issue](https://github.com/kyegomez/swarms/issues/new/choose)
  - Post your issue whether it's an issue or a feature request


- **Community Support**
  - URL: [Submit issue](https://discord.gg/EamjgSaEQf)
  - Ask the community for support in real-time and or admin support

--------------------------------------------------

# File: swarms/concept/future_swarm_architectures.md



---

### Federated Swarm

**Overview:**
A Federated Swarm architecture involves multiple independent swarms collaborating to complete a task. Each swarm operates autonomously but can share information and results with other swarms.

**Use-Cases:**
- Distributed learning systems where data is processed across multiple nodes.

- Scenarios requiring collaboration between different teams or departments.

```mermaid
graph TD
    A[Central Coordinator]
    subgraph Swarm1
        B1[Agent 1.1] --> B2[Agent 1.2]
        B2 --> B3[Agent 1.3]
    end
    subgraph Swarm2
        C1[Agent 2.1] --> C2[Agent 2.2]
        C2 --> C3[Agent 2.3]
    end
    subgraph Swarm3
        D1[Agent 3.1] --> D2[Agent 3.2]
        D2 --> D3[Agent 3.3]
    end
    B1 --> A
    C1 --> A
    D1 --> A
```

---

### Star Swarm

**Overview:**
A Star Swarm architecture features a central agent that coordinates the activities of several peripheral agents. The central agent assigns tasks to the peripheral agents and aggregates their results.

**Use-Cases:**
- Centralized decision-making processes.

- Scenarios requiring a central authority to coordinate multiple workers.

```mermaid
graph TD
    A[Central Agent] --> B1[Peripheral Agent 1]
    A --> B2[Peripheral Agent 2]
    A --> B3[Peripheral Agent 3]
    A --> B4[Peripheral Agent 4]
```

---

### Mesh Swarm

**Overview:**
A Mesh Swarm architecture allows for a fully connected network of agents where each agent can communicate with any other agent. This setup provides high flexibility and redundancy.

**Use-Cases:**
- Complex systems requiring high fault tolerance and redundancy.

- Scenarios involving dynamic and frequent communication between agents.

```mermaid
graph TD
    A1[Agent 1] --> A2[Agent 2]
    A1 --> A3[Agent 3]
    A1 --> A4[Agent 4]
    A2 --> A3
    A2 --> A4
    A3 --> A4
```

---

### Cascade Swarm

**Overview:**
A Cascade Swarm architecture involves a chain of agents where each agent triggers the next one in a cascade effect. This is useful for scenarios where tasks need to be processed in stages, and each stage initiates the next.

**Use-Cases:**
- Multi-stage processing tasks such as data transformation pipelines.

- Event-driven architectures where one event triggers subsequent actions.

```mermaid
graph TD
    A[Trigger Agent] --> B[Agent 1]
    B --> C[Agent 2]
    C --> D[Agent 3]
    D --> E[Agent 4]
```

---

### Hybrid Swarm

**Overview:**
A Hybrid Swarm architecture combines elements of various architectures to suit specific needs. It might integrate hierarchical and parallel components, or mix sequential and round robin patterns.

**Use-Cases:**
- Complex workflows requiring a mix of different processing strategies.

- Custom scenarios tailored to specific operational requirements.

```mermaid
graph TD
    A[Root Agent] --> B1[Sub-Agent 1]
    A --> B2[Sub-Agent 2]
    B1 --> C1[Parallel Agent 1]
    B1 --> C2[Parallel Agent 2]
    B2 --> C3[Sequential Agent 1]
    C3 --> C4[Sequential Agent 2]
    C3 --> C5[Sequential Agent 3]
```

---

These swarm architectures provide different models for organizing and orchestrating large language models (LLMs) to perform various tasks efficiently. Depending on the specific requirements of your project, you can choose the appropriate architecture or even combine elements from multiple architectures to create a hybrid solution.

--------------------------------------------------

# File: swarms/concept/how_to_choose_swarms.md

# Choosing the Right Swarm for Your Business Problem

Depending on the complexity and nature of your problem, different swarm configurations can be more effective in achieving optimal performance. This guide provides a detailed explanation of when to use each swarm type, including their strengths and potential drawbacks.

## Swarm Types Overview

- **MajorityVoting**: A swarm structure where agents vote on an outcome, and the majority decision is taken as the final result.
- **AgentRearrange**: Provides the foundation for both sequential and parallel swarms.
- **RoundRobin**: Agents take turns handling tasks in a cyclic manner.
- **Mixture of Agents**: A heterogeneous swarm where agents with different capabilities are combined.
- **GraphWorkflow**: Agents collaborate in a directed acyclic graph (DAG) format.
- **GroupChat**: Agents engage in a chat-like interaction to reach decisions.
- **AgentRegistry**: A centralized registry where agents are stored, retrieved, and invoked.
- **SpreadsheetSwarm**: A swarm designed to manage tasks at scale, tracking agent outputs in a structured format (e.g., CSV files).

---

## MajorityVoting Swarm

### Use-Case
MajorityVoting is ideal for scenarios where accuracy is paramount, and the decision must be determined from multiple perspectives. For instance, choosing the best marketing strategy where various marketing agents vote on the highest predicted performance.

### Advantages
- Ensures robustness in decision-making by leveraging multiple agents.
- Helps eliminate outliers or faulty agent decisions.

### Warnings
!!! warning
    Majority voting can be slow if too many agents are involved. Ensure that your swarm size is manageable for real-time decision-making.

---

## AgentRearrange (Sequential and Parallel)

### Sequential Swarm Use-Case
For linear workflows where each task depends on the outcome of the previous task, such as processing legal documents step by step through a series of checks and validations.

### Parallel Swarm Use-Case
For tasks that can be executed concurrently, such as batch processing customer data in marketing campaigns. Parallel swarms can significantly reduce processing time by dividing tasks across multiple agents.

### Notes
!!! note
    Sequential swarms are slower but ensure strict task dependencies are respected. Parallel swarms are faster but require careful management of task interdependencies.

---

## RoundRobin Swarm

### Use-Case
For balanced task distribution where agents need to handle tasks evenly. An example would be assigning customer support tickets to agents in a cyclic manner, ensuring no single agent is overloaded.

### Advantages
- Fair and even distribution of tasks.
- Simple and effective for balanced workloads.

### Warnings
!!! warning
    Round-robin may not be the best choice when some agents are more competent than others, as it can assign tasks equally regardless of agent performance.

---

## Mixture of Agents

### Use-Case
Ideal for complex problems that require diverse skills. For example, a financial forecasting problem where some agents specialize in stock data, while others handle economic factors.

### Notes
!!! note
    A mixture of agents is highly flexible and can adapt to various problem domains. However, be mindful of coordination overhead.

---

## GraphWorkflow Swarm

### Use-Case
This swarm structure is suited for tasks that can be broken down into a series of dependencies but are not strictly linear, such as an AI-driven software development pipeline where one agent handles front-end development while another handles back-end concurrently.

### Advantages
- Provides flexibility for managing dependencies.
- Agents can work on different parts of the problem simultaneously.

### Warnings
!!! warning
    GraphWorkflow requires clear definition of task dependencies, or it can lead to execution issues and delays.

---

## GroupChat Swarm

### Use-Case
For real-time collaborative decision-making. For instance, agents could participate in group chat for negotiating contracts, each contributing their expertise and adjusting responses based on the collective discussion.

### Advantages
- Facilitates highly interactive problem-solving.
- Ideal for dynamic and unstructured problems.

### Warnings
!!! warning
    High communication overhead between agents may slow down decision-making in large swarms.

---

## AgentRegistry Swarm

### Use-Case
For dynamically managing agents based on the problem domain. An AgentRegistry is useful when new agents can be added or removed as needed, such as adding new machine learning models for an evolving recommendation engine.

### Notes
!!! note
    AgentRegistry is a flexible solution but introduces additional complexity when agents need to be discovered and registered on the fly.

---

## SpreadsheetSwarm

### Use-Case
When dealing with massive-scale data or agent outputs that need to be stored and managed in a tabular format. SpreadsheetSwarm is ideal for businesses handling thousands of agent outputs, such as large-scale marketing analytics or financial audits.

### Advantages
- Provides structure and order for managing massive amounts of agent outputs.
- Outputs are easily saved and tracked in CSV files.

### Warnings
!!! warning
    Ensure the correct configuration of agents in SpreadsheetSwarm to avoid data mismatches and inconsistencies when scaling up to thousands of agents.

---

## Final Thoughts

The choice of swarm depends on:

1. **Nature of the task**: Whether it's sequential or parallel.

2. **Problem complexity**: Simple problems might benefit from RoundRobin, while complex ones may need GraphWorkflow or Mixture of Agents.

3. **Scale of execution**: For large-scale tasks, Swarms like SpreadsheetSwarm or MajorityVoting provide scalability with structured outputs.

When integrating agents in a business workflow, it's crucial to balance task complexity, agent capabilities, and scalability to ensure the optimal swarm architecture.


--------------------------------------------------

# File: swarms/concept/philosophy.md

# Our Philosophy: Simplifying Multi-Agent Collaboration Through Readable Code and Performance Optimization

Our mission is to streamline multi-agent collaboration by emphasizing simplicity, readability, and performance in our codebase. This document outlines our core tactics:

- **Readable Code with Type Annotations, Documentation, and Logging**
- **Bleeding-Edge Performance via Concurrency and Parallelism**
- **Simplified Abstractions for Multi-Agent Collaboration**

By adhering to these principles, we aim to make our systems more maintainable, scalable, and efficient, facilitating easier integration and collaboration among developers and agents alike.

---

## 1. Emphasizing Readable Code

Readable code is the cornerstone of maintainable and scalable systems. It ensures that developers can easily understand, modify, and extend the codebase.

### 1.1 Use of Type Annotations

Type annotations enhance code readability and catch errors early in the development process.

```python
def process_data(data: List[str]) -> Dict[str, int]:
    result = {}
    for item in data:
        result[item] = len(item)
    return result
```

### 1.2 Code Style Guidelines

Adhering to consistent code style guidelines, such as PEP 8 for Python, ensures uniformity across the codebase.

- **Indentation:** Use 4 spaces per indentation level.
- **Variable Naming:** Use `snake_case` for variables and functions.
- **Class Naming:** Use `PascalCase` for class names.

### 1.3 Importance of Documentation

Comprehensive documentation helps new developers understand the purpose and functionality of code modules.

```python
def fetch_user_profile(user_id: str) -> UserProfile:
    """
    Fetches the user profile from the database.

    Args:
        user_id (str): The unique identifier of the user.

    Returns:
        UserProfile: An object containing user profile data.
    """
    # Function implementation
```

### 1.4 Consistent Naming Conventions

Consistent naming reduces confusion and makes the code self-explanatory.

- **Functions:** Should be verbs (e.g., `calculate_total`).
- **Variables:** Should be nouns (e.g., `total_amount`).
- **Constants:** Should be uppercase (e.g., `MAX_RETRIES`).

---

## 2. Effective Logging Practices

Logging is essential for debugging and monitoring the health of applications.

### 2.1 Why Logging is Important

- **Debugging:** Helps identify issues during development and after deployment.
- **Monitoring:** Provides insights into the system's behavior in real-time.
- **Audit Trails:** Keeps a record of events for compliance and analysis.

### 2.2 Best Practices for Logging

- **Use Appropriate Log Levels:** DEBUG, INFO, WARNING, ERROR, CRITICAL.
- **Consistent Log Formatting:** Include timestamps, log levels, and messages.
- **Avoid Sensitive Information:** Do not log passwords or personal data.

### 2.3 Logging Examples

```python
import logging

logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s:%(message)s')

def connect_to_service(url: str) -> bool:
    logging.debug(f"Attempting to connect to {url}")
    try:
        # Connection logic
        logging.info(f"Successfully connected to {url}")
        return True
    except ConnectionError as e:
        logging.error(f"Connection failed to {url}: {e}")
        return False
```

---

## 3. Achieving Bleeding-Edge Performance

Performance is critical, especially when dealing with multiple agents and large datasets.

### 3.1 Concurrency and Parallelism

Utilizing concurrency and parallelism can significantly improve performance.

- **Concurrency:** Dealing with multiple tasks by managing multiple threads.
- **Parallelism:** Executing multiple tasks simultaneously on multiple CPU cores.

### 3.2 Asynchronous Programming

Asynchronous programming allows for non-blocking operations, leading to better resource utilization.

```python
import asyncio

async def fetch_data(endpoint: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(endpoint) as response:
            return await response.json()

async def main():
    endpoints = ['https://api.example.com/data1', 'https://api.example.com/data2']
    tasks = [fetch_data(url) for url in endpoints]
    results = await asyncio.gather(*tasks)
    print(results)

asyncio.run(main())
```

### 3.3 Utilizing Modern Hardware Capabilities

Leverage multi-core processors and GPUs for computationally intensive tasks.

- **Multi-threading:** Use threads for I/O-bound tasks.
- **Multi-processing:** Use processes for CPU-bound tasks.
- **GPU Acceleration:** Utilize GPUs for tasks like machine learning model training.

### 3.4 Code Example: Parallel Processing

```python
from concurrent.futures import ThreadPoolExecutor

def process_item(item):
    # Processing logic
    return result

items = [1, 2, 3, 4, 5]
with ThreadPoolExecutor(max_workers=5) as executor:
    results = list(executor.map(process_item, items))
```

---

## 4. Simplifying Multi-Agent Collaboration

Simplifying the abstraction of multi-agent collaboration makes it accessible and manageable.

### 4.1 Importance of Simple Abstractions

- **Ease of Use:** Simple interfaces make it easier for developers to integrate agents.
- **Maintainability:** Reduces complexity, making the codebase easier to maintain.
- **Scalability:** Simple abstractions can be extended without significant overhauls.

### 4.2 Standardizing Agent Interfaces

Every agent should adhere to a standard interface for consistency.

#### 4.2.1 Agent Base Class

```python
from abc import ABC, abstractmethod

class BaseAgent(ABC):
    @abstractmethod
    def run(self, task: str) -> Any:
        pass

    def __call__(self, task: str) -> Any:
        return self.run(task)

    @abstractmethod
    async def arun(self, task: str) -> Any:
        pass
```

#### 4.2.2 Example Agent Implementation

```python
class DataProcessingAgent(BaseAgent):
    def run(self, task: str) -> str:
        # Synchronous processing logic
        return f"Processed {task}"

    async def arun(self, task: str) -> str:
        # Asynchronous processing logic
        return f"Processed {task} asynchronously"
```

#### 4.2.3 Usage Example

```python
agent = DataProcessingAgent()

# Synchronous call
result = agent.run("data_task")
print(result)  # Output: Processed data_task

# Asynchronous call
async def main():
    result = await agent.arun("data_task")
    print(result)  # Output: Processed data_task asynchronously

asyncio.run(main())
```

### 4.3 Mermaid Diagram: Agent Interaction

```mermaid
sequenceDiagram
    participant User
    participant AgentA
    participant AgentB
    participant AgentC

    User->>AgentA: run(task)
    AgentA-->>AgentB: arun(sub_task)
    AgentB-->>AgentC: run(sub_sub_task)
    AgentC-->>AgentB: result_sub_sub_task
    AgentB-->>AgentA: result_sub_task
    AgentA-->>User: final_result
```

*Agents collaborating to fulfill a user's task.*

### 4.4 Simplified Collaboration Workflow

```mermaid
flowchart TD
    UserRequest["User Request"] --> Agent1["Agent 1"]
    Agent1 -->|"run(task)"| Agent2["Agent 2"]
    Agent2 -->|"arun(task)"| Agent3["Agent 3"]
    Agent3 -->|"result"| Agent2
    Agent2 -->|"result"| Agent1
    Agent1 -->|"result"| UserResponse["User Response"]
```

*Workflow demonstrating how agents process a task collaboratively.*

---

## 5. Bringing It All Together

By integrating these principles, we create a cohesive system where agents can efficiently collaborate while maintaining code quality and performance.

### 5.1 Example: Multi-Agent System

#### 5.1.1 Agent Definitions

```python
class AgentA(BaseAgent):
    def run(self, task: str) -> str:
        # Agent A processing
        return f"AgentA processed {task}"

    async def arun(self, task: str) -> str:
        # Agent A asynchronous processing
        return f"AgentA processed {task} asynchronously"

class AgentB(BaseAgent):
    def run(self, task: str) -> str:
        # Agent B processing
        return f"AgentB processed {task}"

    async def arun(self, task: str) -> str:
        # Agent B asynchronous processing
        return f"AgentB processed {task} asynchronously"
```

#### 5.1.2 Orchestrator Agent

```python
class OrchestratorAgent(BaseAgent):
    def __init__(self):
        self.agent_a = AgentA()
        self.agent_b = AgentB()

    def run(self, task: str) -> str:
        result_a = self.agent_a.run(task)
        result_b = self.agent_b.run(task)
        return f"Orchestrated results: {result_a} & {result_b}"

    async def arun(self, task: str) -> str:
        result_a = await self.agent_a.arun(task)
        result_b = await self.agent_b.arun(task)
        return f"Orchestrated results: {result_a} & {result_b}"
```

#### 5.1.3 Execution

```python
orchestrator = OrchestratorAgent()

# Synchronous execution
result = orchestrator.run("task1")
print(result)
# Output: Orchestrated results: AgentA processed task1 & AgentB processed task1

# Asynchronous execution
async def main():
    result = await orchestrator.arun("task1")
    print(result)
    # Output: Orchestrated results: AgentA processed task1 asynchronously & AgentB processed task1 asynchronously

asyncio.run(main())
```

### 5.2 Mermaid Diagram: Orchestrator Workflow

```mermaid
sequenceDiagram
    participant User
    participant Orchestrator
    participant AgentA
    participant AgentB

    User->>Orchestrator: run(task)
    Orchestrator->>AgentA: run(task)
    Orchestrator->>AgentB: run(task)
    AgentA-->>Orchestrator: result_a
    AgentB-->>Orchestrator: result_b
    Orchestrator-->>User: Orchestrated results
```

*Orchestrator coordinating between Agent A and Agent B.*

---

## 6. Conclusion

Our philosophy centers around making multi-agent collaboration as simple and efficient as possible by:

- **Writing Readable Code:** Through type annotations, consistent styling, and thorough documentation.
- **Implementing Effective Logging:** To aid in debugging and monitoring.
- **Optimizing Performance:** Leveraging concurrency, parallelism, and modern hardware capabilities.
- **Simplifying Abstractions:** Standardizing agent interfaces to `run`, `__call__`, and `arun` methods.

By adhering to these principles, we create a robust foundation for scalable and maintainable systems that can adapt to evolving technological landscapes.



--------------------------------------------------

# File: swarms/concept/purpose/limits_of_individual_agents.md

# The Limits of Individual Agents

![Reliable Agents](docs/assets/img/reliabilitythrough.png)


Individual agents have pushed the boundaries of what machines can learn and accomplish. However, despite their impressive capabilities, these agents face inherent limitations that can hinder their effectiveness in complex, real-world applications. This blog explores the critical constraints of individual agents, such as context window limits, hallucination, single-task threading, and lack of collaboration, and illustrates how multi-agent collaboration can address these limitations. In short,

- Context Window Limits
- Single Task Execution
- Hallucination
- No collaboration



#### Context Window Limits

One of the most significant constraints of individual agents, particularly in the domain of language models, is the context window limit. This limitation refers to the maximum amount of information an agent can consider at any given time. For instance, many language models can only process a fixed number of tokens (words or characters) in a single inference, restricting their ability to understand and generate responses based on longer texts. This limitation can lead to a lack of coherence in longer compositions and an inability to maintain context in extended conversations or documents.

#### Hallucination

Hallucination in AI refers to the phenomenon where an agent generates information that is not grounded in the input data or real-world facts. This can manifest as making up facts, entities, or events that do not exist or are incorrect. Hallucinations pose a significant challenge in ensuring the reliability and trustworthiness of AI-generated content, particularly in critical applications such as news generation, academic research, and legal advice.

#### Single Task Threading

Individual agents are often designed to excel at specific tasks, leveraging their architecture and training data to optimize performance in a narrowly defined domain. However, this specialization can also be a drawback, as it limits the agent's ability to multitask or adapt to tasks that fall outside its primary domain. Single-task threading means an agent may excel in language translation but struggle with image recognition or vice versa, necessitating the deployment of multiple specialized agents for comprehensive AI solutions.

#### Lack of Collaboration

Traditional AI agents operate in isolation, processing inputs and generating outputs independently. This isolation limits their ability to leverage diverse perspectives, share knowledge, or build upon the insights of other agents. In complex problem-solving scenarios, where multiple facets of a problem need to be addressed simultaneously, this lack of collaboration can lead to suboptimal solutions or an inability to tackle multifaceted challenges effectively.

# The Elegant yet Simple Solution

- ## Multi-Agent Collaboration

Recognizing the limitations of individual agents, researchers and practitioners have explored the potential of multi-agent collaboration as a means to transcend these constraints. Multi-agent systems comprise several agents that can interact, communicate, and collaborate to achieve common goals or solve complex problems. This collaborative approach offers several advantages:

#### Overcoming Context Window Limits

By dividing a large task among multiple agents, each focusing on different segments of the problem, multi-agent systems can effectively overcome the context window limits of individual agents. For instance, in processing a long document, different agents could be responsible for understanding and analyzing different sections, pooling their insights to generate a coherent understanding of the entire text.

#### Mitigating Hallucination

Through collaboration, agents can cross-verify facts and information, reducing the likelihood of hallucinations. If one agent generates a piece of information, other agents can provide checks and balances, verifying the accuracy against known data or through consensus mechanisms.

#### Enhancing Multitasking Capabilities

Multi-agent systems can tackle tasks that require a diverse set of skills by leveraging the specialization of individual agents. For example, in a complex project that involves both natural language processing and image analysis, one agent specialized in text can collaborate with another specialized in visual data, enabling a comprehensive approach to the task.

#### Facilitating Collaboration and Knowledge Sharing

Multi-agent collaboration inherently encourages the sharing of knowledge and insights, allowing agents to learn from each other and improve their collective performance. This can be particularly powerful in scenarios where iterative learning and adaptation are crucial, such as dynamic environments or tasks that evolve over time.

### Conclusion

While individual AI agents have made remarkable strides in various domains, their inherent limitations necessitate innovative approaches to unlock the full potential of artificial intelligence. Multi-agent collaboration emerges as a compelling solution, offering a pathway to transcend individual constraints through collective intelligence. By harnessing the power of collaborative AI, we can address more complex, multifaceted problems, paving the way for more versatile, efficient, and effective AI systems in the future.

--------------------------------------------------

# File: swarms/concept/purpose/why.md

# The Swarms Framework: Orchestrating Agents for Enterprise Automation

In the rapidly evolving landscape of artificial intelligence (AI) and automation, a new paradigm is emerging: the orchestration of multiple agents working in collaboration to tackle complex tasks. This approach, embodied by the Swarms Framework, aims to address the fundamental limitations of individual agents and unlocks the true potential of AI-driven automation in enterprise operations.

Individual agents are plagued by the same issues: short term memory constraints, hallucinations, single task limitations, lack of collaboration, and cost inefficiences.

[Learn more here from a list of compiled agent papers](https://github.com/kyegomez/awesome-multi-agent-papers)

## The Purpose of Swarms: Overcoming Agent Limitations

Individual agents, while remarkable in their own right, face several inherent challenges that hinder their ability to effectively automate enterprise operations at scale. These limitations include:

1.  Short-Term Memory Constraints
2.  Hallucination and Factual Inconsistencies
3.  Single-Task Limitations
4.  Lack of Collaborative Capabilities
5.  Cost Inefficiencies

By orchestrating multiple agents to work in concert, the Swarms Framework directly tackles these limitations, paving the way for more efficient, reliable, and cost-effective enterprise automation.

### Limitation 1: Short-Term Memory Constraints

Many AI agents, particularly those based on large language models, suffer from short-term memory constraints. These agents can effectively process and respond to prompts, but their ability to retain and reason over information across multiple interactions or tasks is limited. This limitation can be problematic in enterprise environments, where complex workflows often involve retaining and referencing contextual information over extended periods.

The Swarms Framework addresses this limitation by leveraging the collective memory of multiple agents working in tandem. While individual agents may have limited short-term memory, their combined memory pool becomes significantly larger, enabling the retention and retrieval of contextual information over extended periods. This collective memory is facilitated by agents specializing in information storage and retrieval, such as those based on systems like Llama Index or Pinecone.

### Limitation 2: Hallucination and Factual Inconsistencies

Another challenge faced by many AI agents is the tendency to generate responses that may contain factual inconsistencies or hallucinations -- information that is not grounded in reality or the provided context. This issue can undermine the reliability and trustworthiness of automated systems, particularly in domains where accuracy and consistency are paramount.

The Swarms Framework mitigates this limitation by employing multiple agents with diverse knowledge bases and capabilities. By leveraging the collective intelligence of these agents, the framework can cross-reference and validate information, reducing the likelihood of hallucinations and factual inconsistencies. Additionally, specialized agents can be tasked with fact-checking and verification, further enhancing the overall reliability of the system.

### Limitation 3: Single-Task Limitations

Most individual AI agents are designed and optimized for specific tasks or domains, limiting their ability to handle complex, multi-faceted workflows that often characterize enterprise operations. While an agent may excel at a particular task, such as natural language processing or data analysis, it may struggle with other aspects of a larger workflow, such as task coordination or decision-making.

The Swarms Framework overcomes this limitation by orchestrating a diverse ensemble of agents, each specializing in different tasks or capabilities. By intelligently combining and coordinating these agents, the framework can tackle complex, multi-threaded workflows that span various domains and task types. This modular approach allows for the seamless integration of new agents as they become available, enabling the continuous expansion and enhancement of the system's capabilities.

### Limitation 4: Lack of Collaborative Capabilities

Most AI agents are designed to operate independently, lacking the ability to effectively collaborate with other agents or coordinate their actions towards a common goal. This limitation can hinder the scalability and efficiency of automated systems, particularly in enterprise environments where tasks often require the coordination of multiple agents or systems.

The Swarms Framework addresses this limitation by introducing a layer of coordination and collaboration among agents. Through specialized coordination agents and communication protocols, the framework enables agents to share information, divide tasks, and synchronize their actions. This collaborative approach not only increases efficiency but also enables the emergence of collective intelligence, where the combined capabilities of multiple agents surpass the sum of their individual abilities.

### Limitation 5: Cost Inefficiencies

Running large AI models or orchestrating multiple agents can be computationally expensive, particularly in enterprise environments where scalability and cost-effectiveness are critical considerations. Inefficient resource utilization or redundant computations can quickly escalate costs, making widespread adoption of AI-driven automation financially prohibitive.

The Swarms Framework tackles this limitation by optimizing resource allocation and workload distribution among agents. By intelligently assigning tasks to the most appropriate agents and leveraging agent specialization, the framework minimizes redundant computations and improves overall resource utilization. Additionally, the framework can dynamically scale agent instances based on demand, ensuring that computational resources are allocated efficiently and costs are minimized.

## The Swarms Framework: A Holistic Approach to Enterprise Automation

The Swarms Framework is a comprehensive solution that addresses the limitations of individual agents by orchestrating their collective capabilities. By integrating agents from various frameworks, including LangChain, AutoGPT, Llama Index, and others, the framework leverages the strengths of each agent while mitigating their individual weaknesses.

At its core, the Swarms Framework operates on the principle of multi-agent collaboration. By introducing specialized coordination agents and communication protocols, the framework enables agents to share information, divide tasks, and synchronize their actions towards a common goal. This collaborative approach not only increases efficiency but also enables the emergence of collective intelligence, where the combined capabilities of multiple agents surpass the sum of their individual abilities.

The framework's architecture is modular and extensible, allowing for the seamless integration of new agents as they become available. This flexibility ensures that the system's capabilities can continuously expand and adapt to evolving enterprise needs and technological advancements.


## Benefits of the Swarms Framework

The adoption of the Swarms Framework in enterprise environments offers numerous benefits:

1.  Increased Efficiency and Scalability
2.  Improved Reliability and Accuracy
3.  Adaptability and Continuous Improvement
4.  Cost Optimization
5.  Enhanced Security and Compliance

## Increased Efficiency and Scalability

By orchestrating the collective capabilities of multiple agents, the Swarms Framework enables the efficient execution of complex, multi-threaded workflows. Tasks can be parallelized and distributed across specialized agents, reducing bottlenecks and increasing overall throughput. Additionally, the framework's modular design and ability to dynamically scale agent instances based on demand ensure that the system can adapt to changing workloads and scale seamlessly as enterprise needs evolve.

## Improved Reliability and Accuracy

The collaborative nature of the Swarms Framework reduces the risk of hallucinations and factual inconsistencies that can arise from individual agents. By leveraging the collective knowledge and diverse perspectives of multiple agents, the framework can cross-reference and validate information, enhancing the overall reliability and accuracy of its outputs.

Additionally, the framework's ability to incorporate specialized fact-checking and verification agents further strengthens the trustworthiness of the system's outcomes, ensuring that critical decisions and actions are based on accurate and reliable information.

## Adaptability and Continuous Improvement

The modular architecture of the Swarms Framework allows for the seamless integration of new agents as they become available, enabling the continuous expansion and enhancement of the system's capabilities. As new AI models, algorithms, or data sources emerge, the framework can readily incorporate them, ensuring that enterprise operations remain at the forefront of technological advancements.

Furthermore, the framework's monitoring and analytics capabilities provide valuable insights into system performance, enabling the identification of areas for improvement and the optimization of agent selection, task assignments, and resource allocation strategies over time.

## Cost Optimization

By intelligently orchestrating the collaboration of multiple agents, the Swarms Framework optimizes resource utilization and minimizes redundant computations. This efficient use of computational resources translates into cost savings, making the widespread adoption of AI-driven automation more financially viable for enterprises.

The framework's ability to dynamically scale agent instances based on demand further contributes to cost optimization, ensuring that resources are allocated only when needed and minimizing idle or underutilized instances.

## Enhanced Security and Compliance

In enterprise environments, ensuring the security and compliance of automated systems is paramount. The Swarms Framework addresses these concerns by incorporating robust security measures and compliance controls.

The framework's centralized Memory Manager component enables the implementation of access control mechanisms and data encryption, protecting sensitive information from unauthorized access or breaches. Additionally, the framework's modular design allows for the integration of specialized agents focused on compliance monitoring and auditing, ensuring that enterprise operations adhere to relevant regulations and industry standards.

## Real-World Applications and Use Cases

The Swarms Framework finds applications across a wide range of enterprise domains, enabling organizations to automate complex operations and streamline their workflows. Here are some examples of real-world use cases:

1.  Intelligent Process Automation (IPA)
2.  Customer Service and Support
3.  Fraud Detection and Risk Management
4.  Supply Chain Optimization
5.  Research and Development

## Intelligent Process Automation (IPA)

In the realm of business process automation, the Swarms Framework can orchestrate agents to automate and optimize complex workflows spanning multiple domains and task types. By combining agents specialized in areas such as natural language processing, data extraction, decision-making, and task coordination, the framework can streamline and automate processes that traditionally required manual intervention or coordination across multiple systems.

## Customer Service and Support

The framework's ability to integrate agents with diverse capabilities, such as natural language processing, knowledge retrieval, and decision-making, makes it well-suited for automating customer service and support operations. Agents can collaborate to understand customer inquiries, retrieve relevant information from knowledge bases, and provide accurate and personalized responses, improving customer satisfaction and reducing operational costs.

## Fraud Detection and Risk Management

In the financial and cybersecurity domains, the Swarms Framework can orchestrate agents specialized in data analysis, pattern recognition, and risk assessment to detect and mitigate fraudulent activities or security threats. By combining the collective intelligence of these agents, the framework can identify complex patterns and anomalies that may be difficult for individual agents to detect, enhancing the overall effectiveness of fraud detection and risk management strategies.

## Supply Chain Optimization

The complexity of modern supply chains often requires the coordination of multiple systems and stakeholders. The Swarms Framework can integrate agents specialized in areas such as demand forecasting, inventory management, logistics optimization, and supplier coordination to streamline and optimize supply chain operations. By orchestrating the collective capabilities of these agents, the framework can identify bottlenecks, optimize resource allocation, and facilitate seamless collaboration among supply chain partners.

## Research and Development

In research and development environments, the Swarms Framework can accelerate innovation by enabling the collaboration of agents specialized in areas such as literature review, data analysis, hypothesis generation, and experiment design. By orchestrating these agents, the framework can facilitate the exploration of new ideas, identify promising research directions, and streamline the iterative process of scientific inquiry.

# Conclusion

The Swarms Framework represents a paradigm shift in the field of enterprise automation, addressing the limitations of individual agents by orchestrating their collective capabilities. By integrating agents from various frameworks and enabling multi-agent collaboration, the Swarms Framework overcomes challenges such as short-term memory constraints, hallucinations, single-task limitations, lack of collaboration, and cost inefficiencies.

Through its modular architecture, centralized coordination, and advanced monitoring and analytics capabilities, the Swarms Framework empowers enterprises to automate complex operations with increased efficiency, reliability, and adaptability. It unlocks the true potential of AI-driven automation, enabling organizations to stay ahead of the curve and thrive in an ever-evolving technological landscape.

As the field of artificial intelligence continues to advance, the Swarms Framework stands as a robust and flexible solution, ready to embrace new developments and seamlessly integrate emerging agents and capabilities. By harnessing the power of collective intelligence, the framework paves the way for a future where enterprises can leverage the full potential of AI to drive innovation, optimize operations, and gain a competitive edge in their respective industries.

--------------------------------------------------

# File: swarms/concept/purpose/why_swarms.md

# Why Swarms?

The need for multiple agents to work together in artificial intelligence (AI) and particularly in the context of Large Language Models (LLMs) stems from several inherent limitations and challenges in handling complex, dynamic, and multifaceted tasks with single-agent systems. Collaborating with multiple agents offers a pathway to enhance reliability, computational efficiency, cognitive diversity, and problem-solving capabilities. This section delves into the rationale behind employing multi-agent systems and strategizes on overcoming the associated expenses, such as API bills and hosting costs.

### Why Multiple Agents Are Necessary

#### 1. **Cognitive Diversity**

Different agents can bring varied perspectives, knowledge bases, and problem-solving approaches to a task. This diversity is crucial in complex problem-solving scenarios where a single approach might not be sufficient. Cognitive diversity enhances creativity, leading to innovative solutions and the ability to tackle a broader range of problems.

#### 2. **Specialization and Expertise**

In many cases, tasks are too complex for a single agent to handle efficiently. By dividing the task among multiple specialized agents, each can focus on a segment where it excels, thereby increasing the overall efficiency and effectiveness of the solution. This approach leverages the expertise of individual agents to achieve superior performance in tasks that require multifaceted knowledge and skills.

#### 3. **Scalability and Flexibility**

Multi-agent systems can more easily scale to handle large-scale or evolving tasks. Adding more agents to the system can increase its capacity or capabilities, allowing it to adapt to larger workloads or new types of tasks. This scalability is essential in dynamic environments where the demand and nature of tasks can change rapidly.

#### 4. **Robustness and Redundancy**

Collaboration among multiple agents enhances the system's robustness by introducing redundancy. If one agent fails or encounters an error, others can compensate, ensuring the system remains operational. This redundancy is critical in mission-critical applications where failure is not an option.

### Overcoming Expenses with API Bills and Hosting

Deploying multiple agents, especially when relying on cloud-based services or APIs, can incur significant costs. Here are strategies to manage and reduce these expenses:

#### 1. **Optimize Agent Efficiency**

Before scaling up the number of agents, ensure each agent operates as efficiently as possible. This can involve refining algorithms, reducing unnecessary API calls, and optimizing data processing to minimize computational requirements and, consequently, the associated costs.

#### 2. **Use Open Source and Self-Hosted Solutions**

Where possible, leverage open-source models and technologies that can be self-hosted. While there is an initial investment in setting up the infrastructure, over time, self-hosting can significantly reduce costs related to API calls and reliance on third-party services.

#### 3. **Implement Intelligent Caching**

Caching results for frequently asked questions or common tasks can drastically reduce the need for repeated computations or API calls. Intelligent caching systems can determine what information to store and for how long, optimizing the balance between fresh data and computational savings.

#### 4. **Dynamic Scaling and Load Balancing**

Use cloud services that offer dynamic scaling and load balancing to adjust the resources allocated based on the current demand. This ensures you're not paying for idle resources during low-usage periods while still being able to handle high demand when necessary.

#### 5. **Collaborative Cost-Sharing Models**

In scenarios where multiple stakeholders benefit from the multi-agent system, consider implementing a cost-sharing model. This approach distributes the financial burden among the users or beneficiaries, making it more sustainable.

#### 6. **Monitor and Analyze Costs**

Regularly monitor and analyze your usage and associated costs to identify potential savings. Many cloud providers offer tools to track and forecast expenses, helping you to adjust your usage patterns and configurations to minimize costs without sacrificing performance.

### Conclusion

The collaboration of multiple agents in AI systems presents a robust solution to the complexity, specialization, scalability, and robustness challenges inherent in single-agent approaches. While the associated costs can be significant, strategic optimization, leveraging open-source technologies, intelligent caching, dynamic resource management, collaborative cost-sharing, and diligent monitoring can mitigate these expenses. By adopting these strategies, organizations can harness the power of multi-agent systems to tackle complex problems more effectively and efficiently, ensuring the sustainable deployment of these advanced technologies.

--------------------------------------------------

# File: swarms/concept/swarm_architectures.md

# Multi-Agent Architectures

### What is a Multi-Agent Architecture?

A multi-agent architecture refers to a group of more than two agents working collaboratively to achieve a common goal. These agents can be software entities, such as LLMs that interact with each other to perform complex tasks. The concept of multi-agent architectures is inspired by how humans communicate and work together in teams, organizations, and communities, where individual contributions combine to create sophisticated collaborative problem-solving capabilities.

### How Multi-Agent Architectures Facilitate Communication

Multi-agent architectures are designed to establish and manage communication between agents within a system. These architectures define how agents interact, share information, and coordinate their actions to achieve the desired outcomes. Here are some key aspects of multi-agent architectures:

1. **Hierarchical Communication**: In hierarchical architectures, communication flows from higher-level agents to lower-level agents. Higher-level agents act as coordinators, distributing tasks and aggregating results. This structure is efficient for tasks that require top-down control and decision-making.

2. **Concurrent Communication**: In concurrent architectures, agents operate independently and simultaneously on different tasks. This architecture is suitable for tasks that can be processed concurrently without dependencies, allowing for faster execution and scalability.

3. **Sequential Communication**: Sequential architectures process tasks in a linear order, where each agent's output becomes the input for the next agent. This ensures that tasks with dependencies are handled in the correct sequence, maintaining the integrity of the workflow.

4. **Mesh Communication**: In mesh architectures, agents are fully connected, allowing any agent to communicate with any other agent. This setup provides high flexibility and redundancy, making it ideal for complex systems requiring dynamic interactions.

5. **Federated Communication**: Federated architectures involve multiple independent systems that collaborate by sharing information and results. Each system operates autonomously but can contribute to a larger task, enabling distributed problem-solving across different nodes.

Multi-agent architectures leverage these communication patterns to ensure that agents work together efficiently, adapting to the specific requirements of the task at hand. By defining clear communication protocols and interaction models, multi-agent architectures enable the seamless orchestration of multiple agents, leading to enhanced performance and problem-solving capabilities.

## Core Multi-Agent Architectures

| **Name**                          | **Description**                                                                                                                                                         | **Documentation**                                                                                      | **Use Cases**                                                                                     |
|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| Hierarchical Architecture         | A system where agents are organized in a hierarchy, with higher-level agents coordinating lower-level agents to achieve complex tasks.                                   | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)                | Manufacturing process optimization, multi-level sales management, healthcare resource coordination |
| Agent Rearrange                   | A setup where agents rearrange themselves dynamically based on the task requirements and environmental conditions.                                                       | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)                   | Adaptive manufacturing lines, dynamic sales territory realignment, flexible healthcare staffing  |
| Concurrent Workflows              | Agents perform different tasks simultaneously, coordinating to complete a larger goal.                                                                                  | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/)               | Concurrent production lines, parallel sales operations, simultaneous patient care processes       |
| Sequential Coordination           | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next.                                                           | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)               | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows     |
| Mixture of Agents                 | A heterogeneous architecture where agents with different capabilities are combined to solve complex problems.                                                           | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/moa/)                               | Financial forecasting, complex problem-solving requiring diverse skills                           |
| Graph Workflow                    | Agents collaborate in a directed acyclic graph (DAG) format to manage dependencies and parallel tasks.                                                                  | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)                    | AI-driven software development pipelines, complex project management                              |
| Group Chat                        | Agents engage in a chat-like interaction to reach decisions collaboratively.                                                                                           | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)                        | Real-time collaborative decision-making, contract negotiations                                    |
| Interactive Group Chat           | Enhanced group chat with dynamic speaker selection and interaction patterns.                                                                                           | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)             | Advanced collaborative decision-making, dynamic team coordination                                 |
| Agent Registry                    | A centralized registry where agents are stored, retrieved, and invoked dynamically.                                                                                     | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/)                    | Dynamic agent management, evolving recommendation engines                                         |
| SpreadSheet                       | Manages tasks at scale, tracking agent outputs in a structured format like CSV files.                                                                                   | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)                 | Large-scale marketing analytics, financial audits                                                 |
| Router                            | Routes and chooses the architecture based on the task requirements and available agents.                                                                               | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)                       | Dynamic task routing, adaptive architecture selection, optimized agent allocation                 |
| Heavy                             | High-performance architecture for handling intensive computational tasks with multiple agents.                                                                         | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/heavy_swarm/)                       | Large-scale data processing, intensive computational workflows                                    |
| Deep Research                     | Specialized architecture for conducting in-depth research tasks across multiple domains.                                                                               | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/deep_research_swarm/)               | Academic research, market analysis, comprehensive data investigation                              |
| De-Hallucination                  | Architecture designed to reduce and eliminate hallucinations in AI outputs through consensus.                                                                          | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/de_hallucination_swarm/)            | Fact-checking, content verification, reliable information generation                              |
| Council as Judge                  | Multiple agents act as a council to evaluate and judge outputs or decisions.                                                                                           | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/council_of_judges/)                     | Quality assessment, decision validation, peer review processes                                    |
| MALT                              | Specialized architecture for complex language processing tasks across multiple agents.                                                                                | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/malt/)                              | Natural language processing, translation, content generation                                      |
| Majority Voting                   | Agents vote on decisions with the majority determining the final outcome.                                                                                              | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/)                   | Democratic decision-making, consensus building, error reduction                                   |
| Round Robin                       | Tasks are distributed cyclically among agents in a rotating order.                                                                                                     | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/round_robin_swarm/)                       | Load balancing, fair task distribution, resource optimization                                     |
| Auto-Builder                      | Automatically constructs and configures multi-agent systems based on requirements.                                                                                    | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/auto_swarm_builder/)                | Dynamic system creation, adaptive architectures, rapid prototyping                               |
| Hybrid Hierarchical Cluster      | Combines hierarchical and peer-to-peer communication patterns for complex workflows.                                                                                   | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)     | Complex enterprise workflows, multi-department coordination                                       |
| Election                          | Agents participate in democratic voting processes to select leaders or make collective decisions.                                                                      | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/election_swarm/)                    | Democratic governance, consensus building, leadership selection                                   |
| Dynamic Conversational           | Adaptive conversation management with dynamic agent selection and interaction patterns.                                                                              | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/dynamic_conversational_swarm/)      | Adaptive chatbots, dynamic customer service, contextual conversations                            |
| Tree                              | Hierarchical tree structure for organizing agents in parent-child relationships.                                                                                      | [Learn More](https://docs.swarms.world/en/latest/swarms/structs/tree_swarm/)                        | Organizational hierarchies, decision trees, taxonomic classification                             |

---

## Architectural Patterns

### Hierarchical Architecture

**Overview:**
Organizes agents in a tree-like structure. Higher-level agents delegate tasks to lower-level agents, which can further divide tasks among themselves. This structure allows for efficient task distribution and scalability.

**Use Cases:**

- Complex decision-making processes where tasks can be broken down into subtasks

- Multi-stage workflows such as data processing pipelines or hierarchical reinforcement learning


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)**

```mermaid
graph TD
    A[Root Agent] --> B1[Sub-Agent 1]
    A --> B2[Sub-Agent 2]
    B1 --> C1[Sub-Agent 1.1]
    B1 --> C2[Sub-Agent 1.2]
    B2 --> C3[Sub-Agent 2.1]
    B2 --> C4[Sub-Agent 2.2]
```

---

### Agent Rearrange

**Overview:**
A dynamic architecture where agents rearrange themselves based on task requirements and environmental conditions. Agents can adapt their roles, positions, and relationships to optimize performance for different scenarios.

**Use Cases:**
- Adaptive manufacturing lines that reconfigure based on product requirements

- Dynamic sales territory realignment based on market conditions

- Flexible healthcare staffing that adjusts to patient needs


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)**

```mermaid
graph TD
    A[Task Requirements] --> B[Configuration Analyzer]
    B --> C[Optimization Engine]
    
    C --> D[Agent Pool]
    D --> E[Agent 1]
    D --> F[Agent 2]
    D --> G[Agent 3]
    D --> H[Agent N]
    
    C --> I[Rearrangement Logic]
    I --> J[New Configuration]
    J --> K[Role Assignment]
    K --> L[Execution Phase]
    
    L --> M[Performance Monitor]
    M --> N{Optimization Needed?}
    N -->|Yes| C
    N -->|No| O[Continue Execution]
```

---

### Concurrent Architecture

**Overview:**
Multiple agents operate independently and simultaneously on different tasks. Each agent works on its own task without dependencies on the others.

**Use Cases:**
- Tasks that can be processed independently, such as parallel data analysis

- Large-scale simulations where multiple scenarios are run simultaneously


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/concurrentworkflow/)**

```mermaid
graph LR
    A[Task Input] --> B1[Agent 1]
    A --> B2[Agent 2]
    A --> B3[Agent 3]
    A --> B4[Agent 4]
    B1 --> C1[Output 1]
    B2 --> C2[Output 2]
    B3 --> C3[Output 3]
    B4 --> C4[Output 4]
```

---

### Sequential Architecture

**Overview:**
Processes tasks in a linear sequence. Each agent completes its task before passing the result to the next agent in the chain. Ensures orderly processing and is useful when tasks have dependencies.

**Use Cases:**

- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing

- Scenarios requiring strict order of operations


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)**

```mermaid
graph TD
    A[Input] --> B[Agent 1]
    B --> C[Agent 2]
    C --> D[Agent 3]
    D --> E[Agent 4]
    E --> F[Final Output]
```

---

### Round Robin Architecture

**Overview:**
Tasks are distributed cyclically among a set of agents. Each agent takes turns handling tasks in a rotating order, ensuring even distribution of workload.

**Use Cases:**

- Load balancing in distributed systems

- Scenarios requiring fair distribution of tasks to avoid overloading any single agent


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/round_robin_swarm/)**

```mermaid
graph TD
    A[Task Distributor] --> B1[Agent 1]
    A --> B2[Agent 2]
    A --> B3[Agent 3]
    A --> B4[Agent 4]
    B1 --> C[Task Queue]
    B2 --> C
    B3 --> C
    B4 --> C
    C --> A
```

---

### SpreadSheet Architecture

**Overview:**
Makes it easy to manage thousands of agents in one place: a CSV file. Initialize any number of agents and run loops of agents on tasks.

**Use Cases:**
- Multi-threaded execution: Execute agents on multiple threads

- Save agent outputs into CSV file

- One place to analyze agent outputs


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)**

```mermaid
graph TD
    A[Initialize SpreadSheet System] --> B[Initialize Agents]
    B --> C[Load Task Queue]
    C --> D[Distribute Tasks]

    subgraph Agent_Pool[Agent Pool]
        D --> E1[Agent 1]
        D --> E2[Agent 2]
        D --> E3[Agent 3]
        D --> E4[Agent N]
    end

    E1 --> F1[Process Task]
    E2 --> F2[Process Task]
    E3 --> F3[Process Task]
    E4 --> F4[Process Task]

    F1 --> G[Collect Results]
    F2 --> G
    F3 --> G
    F4 --> G

    G --> H[Save to CSV]
    H --> I[Generate Analytics]
```

---

### Mixture of Agents

**Overview:**
Combines multiple agents with different capabilities and expertise to solve complex problems that require diverse skill sets.

**Use Cases:**
- Financial forecasting requiring different analytical approaches

- Complex problem-solving needing diverse expertise

- Multi-domain analysis tasks


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/moa/)**

```mermaid
graph TD
    A[Task Input] --> B[Layer 1: Reference Agents]
    B --> C[Specialist Agent 1]
    B --> D[Specialist Agent 2]
    B --> E[Specialist Agent N]

    C --> F[Response 1]
    D --> G[Response 2]
    E --> H[Response N]

    F --> I[Layer 2: Aggregator Agent]
    G --> I
    H --> I
    I --> J[Synthesized Output]
```

---

### Graph Workflow

**Overview:**
Organizes agents in a directed acyclic graph (DAG) format, enabling complex dependencies and parallel execution paths.

**Use Cases:**
- AI-driven software development pipelines

- Complex project management with dependencies

- Multi-step data processing workflows


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)**

```mermaid
graph TD
    A[Start Node] --> B[Agent 1]
    A --> C[Agent 2]
    B --> D[Agent 3]
    C --> D
    B --> E[Agent 4]
    D --> F[Agent 5]
    E --> F
    F --> G[End Node]
```

---

### Group Chat

**Overview:**
Enables agents to engage in chat-like interactions to reach decisions collaboratively through discussion and consensus building.

**Use Cases:**
- Real-time collaborative decision-making

- Contract negotiations

- Brainstorming sessions


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)**

```mermaid
graph TD
    A[Discussion Topic] --> B[Chat Environment]
    B --> C[Agent 1]
    B --> D[Agent 2]
    B --> E[Agent 3]
    B --> F[Agent N]
    
    C --> G[Message Exchange]
    D --> G
    E --> G
    F --> G
    
    G --> H[Consensus Building]
    H --> I[Final Decision]
```

---

### Interactive Group Chat

**Overview:**
Enhanced version of Group Chat with dynamic speaker selection, priority-based communication, and advanced interaction patterns.

**Use Cases:**
- Advanced collaborative decision-making

- Dynamic team coordination

- Adaptive conversation management


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)**

```mermaid
graph TD
    A[Conversation Manager] --> B[Speaker Selection Logic]
    B --> C[Priority Speaker]
    B --> D[Random Speaker]
    B --> E[Round Robin Speaker]
    
    C --> F[Active Discussion]
    D --> F
    E --> F
    
    F --> G[Agent Pool]
    G --> H[Agent 1]
    G --> I[Agent 2]
    G --> J[Agent N]
    
    H --> K[Dynamic Response]
    I --> K
    J --> K
    K --> A
```

---

### Agent Registry

**Overview:**
A centralized registry system where agents are stored, retrieved, and invoked dynamically. The registry maintains metadata about agent capabilities, availability, and performance metrics, enabling intelligent agent selection and management.

**Use Cases:**
- Dynamic agent management in large-scale systems

- Evolving recommendation engines that adapt agent selection

- Service discovery in distributed agent systems


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/agent_registry/)**

```mermaid
graph TD
    A[Agent Registration] --> B[Registry Database]
    B --> C[Agent Metadata]
    C --> D[Capabilities]
    C --> E[Performance Metrics]
    C --> F[Availability Status]
    
    G[Task Request] --> H[Registry Query Engine]
    H --> I[Agent Discovery]
    I --> J[Capability Matching]
    J --> K[Agent Selection]
    
    K --> L[Agent Invocation]
    L --> M[Task Execution]
    M --> N[Performance Tracking]
    N --> O[Registry Update]
    O --> B
```

---

### Router Architecture

**Overview:**
Intelligently routes tasks to the most appropriate agents or architectures based on task requirements and agent capabilities.

**Use Cases:**
- Dynamic task routing

- Adaptive architecture selection

- Optimized agent allocation


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)**

```mermaid
graph TD
    A[Incoming Task] --> B[Router Analysis]
    B --> C[Task Classification]
    C --> D[Agent Capability Matching]
    
    D --> E[Route to Sequential]
    D --> F[Route to Concurrent]
    D --> G[Route to Hierarchical]
    D --> H[Route to Specialist Agent]
    
    E --> I[Execute Architecture]
    F --> I
    G --> I
    H --> I
    
    I --> J[Collect Results]
    J --> K[Return Output]
```

---

### Heavy Architecture

**Overview:**
High-performance architecture designed for handling intensive computational tasks with multiple agents working on resource-heavy operations.

**Use Cases:**
- Large-scale data processing

- Intensive computational workflows

- High-throughput task execution


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/heavy_swarm/)**

```mermaid
graph TD
    A[Resource Manager] --> B[Load Balancer]
    B --> C[Heavy Agent Pool]
    
    C --> D[Compute Agent 1]
    C --> E[Compute Agent 2]
    C --> F[Compute Agent N]
    
    D --> G[Resource Monitor]
    E --> G
    F --> G
    
    G --> H[Performance Optimizer]
    H --> I[Result Aggregator]
    I --> J[Final Output]
```

---

### Deep Research Architecture

**Overview:**
Specialized architecture for conducting comprehensive research tasks across multiple domains with iterative refinement and cross-validation.

**Use Cases:**
- Academic research projects

- Market analysis and intelligence

- Comprehensive data investigation


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/deep_research_swarm/)**

```mermaid
graph TD
    A[Research Query] --> B[Research Planner]
    B --> C[Domain Analysis]
    C --> D[Research Agent 1]
    C --> E[Research Agent 2]
    C --> F[Research Agent N]
    
    D --> G[Initial Findings]
    E --> G
    F --> G
    
    G --> H[Cross-Validation]
    H --> I[Refinement Loop]
    I --> J[Synthesis Agent]
    J --> K[Comprehensive Report]
```

---

### De-Hallucination Architecture

**Overview:**
Architecture specifically designed to reduce and eliminate hallucinations in AI outputs through consensus mechanisms and fact-checking protocols.

**Use Cases:**
- Fact-checking and verification

- Content validation

- Reliable information generation


```mermaid
graph TD
    A[Input Query] --> B[Primary Agent]
    B --> C[Initial Response]
    C --> D[Validation Layer]
    
    D --> E[Fact-Check Agent 1]
    D --> F[Fact-Check Agent 2]
    D --> G[Fact-Check Agent 3]
    
    E --> H[Consensus Engine]
    F --> H
    G --> H
    
    H --> I[Confidence Score]
    I --> J{Score > Threshold?}
    J -->|Yes| K[Validated Output]
    J -->|No| L[Request Refinement]
    L --> B
```

---

### Council as Judge

**Overview:**
Multiple agents act as a council to evaluate, judge, and validate outputs or decisions through collaborative assessment.

**Use Cases:**
- Quality assessment and validation

- Decision validation processes

- Peer review systems


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/council_of_judges/)**

```mermaid
graph TD
    A[Submission] --> B[Council Formation]
    B --> C[Judge Agent 1]
    B --> D[Judge Agent 2]
    B --> E[Judge Agent 3]
    B --> F[Judge Agent N]
    
    C --> G[Individual Assessment]
    D --> G
    E --> G
    F --> G
    
    G --> H[Scoring System]
    H --> I[Weighted Voting]
    I --> J[Final Judgment]
    J --> K[Feedback & Recommendations]
```

---

### MALT Architecture

**Overview:**
Specialized architecture for complex language processing tasks that require coordination between multiple language-focused agents.

**Use Cases:**
- Natural language processing pipelines

- Translation and localization

- Content generation and editing


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/malt/)**

```mermaid
graph TD
    A[Language Task] --> B[Task Analyzer]
    B --> C[Language Router]
    
    C --> D[Grammar Agent]
    C --> E[Semantics Agent]
    C --> F[Style Agent]
    C --> G[Context Agent]
    
    D --> H[Language Processor]
    E --> H
    F --> H
    G --> H
    
    H --> I[Quality Controller]
    I --> J[Output Formatter]
    J --> K[Final Language Output]
```

---

### Majority Voting

**Overview:**
Agents vote on decisions with the majority determining the final outcome, providing democratic decision-making and error reduction through consensus.

**Use Cases:**
- Democratic decision-making processes

- Consensus building

- Error reduction through voting


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/majorityvoting/)**

```mermaid
graph TD
    A[Decision Request] --> B[Voting Coordinator]
    B --> C[Voting Pool]
    
    C --> D[Voter Agent 1]
    C --> E[Voter Agent 2]
    C --> F[Voter Agent 3]
    C --> G[Voter Agent N]
    
    D --> H[Vote Collection]
    E --> H
    F --> H
    G --> H
    
    H --> I[Vote Counter]
    I --> J[Majority Calculator]
    J --> K[Final Decision]
    K --> L[Decision Rationale]
```

---

### Auto-Builder

**Overview:**
Automatically constructs and configures multi-agent systems based on requirements, enabling dynamic system creation and adaptation.

**Use Cases:**
- Dynamic system creation

- Adaptive architectures

- Rapid prototyping of multi-agent systems


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/auto_swarm_builder/)**

```mermaid
graph TD
    A[Requirements Input] --> B[System Analyzer]
    B --> C[Architecture Selector]
    C --> D[Agent Configuration]
    
    D --> E[Agent Builder 1]
    D --> F[Agent Builder 2]
    D --> G[Agent Builder N]
    
    E --> H[System Assembler]
    F --> H
    G --> H
    
    H --> I[Configuration Validator]
    I --> J[System Deployment]
    J --> K[Performance Monitor]
    K --> L[Adaptive Optimizer]
```

---

### Hybrid Hierarchical Cluster

**Overview:**
Combines hierarchical and peer-to-peer communication patterns for complex workflows that require both centralized coordination and distributed collaboration.

**Use Cases:**
- Complex enterprise workflows

- Multi-department coordination

- Hybrid organizational structures


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)**

```mermaid
graph TD
    A[Central Coordinator] --> B[Cluster 1 Leader]
    A --> C[Cluster 2 Leader]
    A --> D[Cluster 3 Leader]
    
    B --> E[Peer Agent 1.1]
    B --> F[Peer Agent 1.2]
    E <--> F
    
    C --> G[Peer Agent 2.1]
    C --> H[Peer Agent 2.2]
    G <--> H
    
    D --> I[Peer Agent 3.1]
    D --> J[Peer Agent 3.2]
    I <--> J
    
    E --> K[Inter-Cluster Communication]
    G --> K
    I --> K
    K --> A
```

---

### Election Architecture

**Overview:**
Agents participate in democratic voting processes to select leaders or make collective decisions.

**Use Cases:**
- Democratic governance

- Consensus building

- Leadership selection


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/election_swarm/)**

```mermaid
graph TD
    A[Voting Process] --> B[Candidate Agents]
    B --> C[Voting Mechanism]
    
    C --> D[Voter Agent 1]
    C --> E[Voter Agent 2]
    C --> F[Voter Agent N]
    
    D --> G[Vote Collection]
    E --> G
    F --> G
    
    G --> H[Vote Counting]
    H --> I[Majority Check]
    I --> J{Majority?}
    J -->|Yes| K[Leader Selected]
    J -->|No| L[Continue Voting]
    L --> B
```

---


---

### Dynamic Conversational Architecture

**Overview:**
Adaptive conversation management with dynamic agent selection and interaction patterns.

**Use Cases:**
- Adaptive chatbots

- Dynamic customer service

- Contextual conversations


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/dynamic_conversational_swarm/)**

```mermaid
graph TD
    A[Conversation Manager] --> B[Speaker Selection Logic]
    B --> C[Priority Speaker]
    B --> D[Random Speaker]
    B --> E[Round Robin Speaker]
    
    C --> F[Active Discussion]
    D --> F
    E --> F
    
    F --> G[Agent Pool]
    G --> H[Agent 1]
    G --> I[Agent 2]
    G --> J[Agent N]
    
    H --> K[Dynamic Response]
    I --> K
    J --> K
    K --> A
```

---

### Tree Architecture

**Overview:**
Hierarchical tree structure for organizing agents in parent-child relationships.

**Use Cases:**
- Organizational hierarchies

- Decision trees

- Taxonomic classification


**[Learn More](https://docs.swarms.world/en/latest/swarms/structs/tree_swarm/)**

```mermaid
graph TD
    A[Root] --> B[Child 1]
    A --> C[Child 2]
    B --> D[Grandchild 1]
    B --> E[Grandchild 2]
    C --> F[Grandchild 3]
    C --> G[Grandchild 4]
```


--------------------------------------------------

# File: swarms/concept/swarm_ecosystem.md

# Understanding the Swarms Ecosystem

The [Swarms Ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a powerful suite of tools and frameworks designed to help developers build, deploy, and manage swarms of autonomous agents. This ecosystem covers various domains, from Large Language Models (LLMs) to IoT data integration, providing a comprehensive platform for automation and scalability. Below, we’ll explore the key components and how they contribute to this groundbreaking ecosystem.

#### 1. **Swarms Framework**

The [Swarms Framework](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a Python-based toolkit that simplifies the creation, orchestration, and scaling of swarms of agents. Whether you are dealing with marketing, accounting, or data analysis, the Swarms Framework allows developers to automate complex workflows efficiently.

```mermaid
graph TD;
    SF[Swarms Framework] --> Core[Swarms Core]
    SF --> JS[Swarms JS]
    SF --> Memory[Swarms Memory]
    SF --> Evals[Swarms Evals]
    SF --> Zero[Swarms Zero]
```

#### 2. **Swarms-Cloud**

[Swarms-Cloud](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a cloud-based solution that enables you to deploy your agents with enterprise-level guarantees. It provides 99% uptime, infinite scalability, and self-healing capabilities, making it ideal for mission-critical operations.

```mermaid
graph TD;
    SC[Swarms-Cloud] --> Uptime[99% Uptime]
    SC --> Scale[Infinite Scalability]
    SC --> Healing[Self-Healing]
```

#### 3. **Swarms-Models**

[Swarms-Models](https://github.com/The-Swarm-Corporation/swarm-ecosystem) offer a seamless interface to leading LLM providers like OpenAI, Anthropic, and Ollama. It allows developers to tap into cutting-edge natural language understanding for their agents.

```mermaid
graph TD;
    SM[Swarms-Models] --> OpenAI[OpenAI API]
    SM --> Anthropic[Anthropic API]
    SM --> Ollama[Ollama API]
```

#### 4. **AgentParse**

[AgentParse](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a high-performance library for mapping structured data like JSON, YAML, CSV, and Pydantic models into formats understandable by agents. This ensures fast, seamless data ingestion.

```mermaid
graph TD;
    AP[AgentParse] --> JSON[JSON Parsing]
    AP --> YAML[YAML Parsing]
    AP --> CSV[CSV Parsing]
    AP --> Pydantic[Pydantic Model Parsing]
```

#### 5. **Swarms-Platform**

The [Swarms-Platform](https://github.com/The-Swarm-Corporation/swarm-ecosystem) is a marketplace where developers can find, buy, and sell autonomous agents. It enables the rapid scaling of agent ecosystems by leveraging ready-made solutions.

```mermaid
graph TD;
    SP[Swarms-Platform] --> Discover[Discover Agents]
    SP --> Buy[Buy Agents]
    SP --> Sell[Sell Agents]
```

#### Extending the Ecosystem: **Swarms Core**, **JS**, and More

In addition to the core components, the Swarms Ecosystem offers several other powerful packages:

- **[Swarms Core](https://github.com/kyegomez/swarms)**: Built in Rust, Swarms Core handles concurrency, multi-threading, and execution strategies.
- **[Swarms JS](https://github.com/The-Swarm-Corporation/swarm-js)**: Allows JavaScript-based orchestration of multi-agent systems.
- **[Swarms Memory](https://github.com/The-Swarm-Corporation/swarm-memory)**: Provides Retrieval Augmented Generation (RAG) systems for long-term memory in agents.
- **[Swarms Evals](https://github.com/The-Swarm-Corporation/swarm-evals)**: Used for evaluating the performance of swarms of agents.
- **[Swarms Zero](https://github.com/The-Swarm-Corporation/zero)**: An RPC-based enterprise-grade automation framework.

```mermaid
graph TD;
    SC[Swarms Core] --> Rust[Rust for Performance]
    JS[Swarms JS] --> MultiAgent[Multi-Agent Orchestration]
    Memory[Swarms Memory] --> RAG[Retrieval Augmented Generation]
    Evals[Swarms Evals] --> Evaluation[Agent Evaluations]
    Zero[Swarms Zero] --> Automation[Enterprise Automation]
```

### Conclusion

The Swarms Ecosystem is a comprehensive, flexible, and scalable platform for managing and deploying autonomous agents. Whether you’re working with LLMs, IoT data, or building new models, the ecosystem provides the tools necessary to simplify automation at scale.

Start exploring the possibilities by checking out the [Swarms Ecosystem GitHub repository](https://github.com/The-Swarm-Corporation/swarm-ecosystem) and join our growing community of developers and innovators.



--------------------------------------------------

# File: swarms/concept/vision.md

# Swarms – The Ultimate Multi-Agent LLM Framework for Developers

Swarms aims to be the definitive and most reliable multi-agent LLM framework, offering developers the tools to automate business operations effortlessly. It provides a vast array of swarm architectures, seamless third-party integration, and unparalleled ease of use. With Swarms, developers can orchestrate intelligent, scalable agent ecosystems that can automate complex business processes.

### Key Features for Developers:
1. **Architectural Flexibility** – Choose from a wide variety of pre-built swarm architectures or build custom agent frameworks. Swarms allows developers to define flexible workflows for specific use cases, providing both sequential and concurrent task execution.
2. **Third-Party Integration** – Swarms makes it simple to integrate with external APIs, databases, and other platforms. By supporting extreme integration capabilities, it ensures your agents work effortlessly within any workflow.
3. **Developer-Centric APIs** – The Swarms API is built with developers in mind, offering an intuitive, simple-to-use interface. Developers can orchestrate agent swarms with minimal code and maximum control.

---

### Code Examples

#### 1. Basic Financial Analysis Agent:
This example demonstrates a simple financial agent setup that responds to financial questions, such as establishing a ROTH IRA, using OpenAI's GPT-based model.

```python
from swarms.structs.agent import Agent
from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT

# Initialize the Financial Analysis Agent with GPT-4o-mini model
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    model_name="gpt-4o-mini",
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=True,
    dynamic_temperature_enabled=True,
    saved_state_path="finance_agent.json",
    user_name="swarms_corp",
    retry_attempts=1,
    context_length=200000,
    return_step_meta=False,
)

# Example task for the agent
out = agent.run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?"
)

# Output the result
print(out)
```

#### 2. Agent Orchestration with AgentRearrange:
The following example showcases how to use the `AgentRearrange` class to manage a multi-agent system. It sets up a director agent to orchestrate two workers—one to generate a transcript and another to summarize it.

```python
from swarms.structs.agent import Agent
from swarms.structs.agent_rearrange import AgentRearrange  

# Initialize the Director agent using Anthropic model via model_name
director = Agent(
    agent_name="Director",
    system_prompt="You are a Director agent. Your role is to coordinate and direct tasks for worker agents. Break down complex tasks into clear, actionable steps.",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    dashboard=False,
    streaming_on=False, 
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="director.json",
)

# Worker 1: transcript generation
worker1 = Agent(
    agent_name="Worker1",
    system_prompt="You are a content creator agent. Your role is to generate detailed, engaging transcripts for YouTube videos about technical topics. Focus on clarity and educational value.",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    dashboard=False,
    streaming_on=False,  
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="worker1.json",
)

# Worker 2: summarization
worker2 = Agent(
    agent_name="Worker2",
    system_prompt="You are a summarization agent. Your role is to create concise, clear summaries of technical content while maintaining key information and insights.",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    dashboard=False,
    streaming_on=False,  
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="worker2.json",
)

# Orchestrate the agents in sequence
agents = [director, worker1, worker2]
flow = "Director -> Worker1 -> Worker2"
agent_system = AgentRearrange(agents=agents, flow=flow)

# Run the workflow
output = agent_system.run(
    "Create a format to express and communicate swarms of LLMs in a structured manner for YouTube"
)
print(output)
```

#### 1. Basic Agent Flow:
Here’s a visual representation of the basic workflow using Mermaid to display the sequential flow between agents.

```mermaid
flowchart TD
    A[Director] --> B[Worker 1: Generate Transcript]
    B --> C[Worker 2: Summarize Transcript]
```

In this diagram:
- The **Director** agent assigns tasks.
- **Worker 1** generates a transcript for a YouTube video.
- **Worker 2** summarizes the transcript.

#### 2. Sequential Agent Flow:
This diagram showcases a sequential agent setup where one agent completes its task before the next agent starts its task.

```mermaid
flowchart TD
    A[Director] --> B[Worker 1: Generate Transcript]
    B --> C[Worker 2: Summarize Transcript]
    C --> D[Worker 3: Finalize]
```

In this setup:

- The **Director** agent assigns tasks to **Worker 1**, which generates a transcript for a YouTube video.

- **Worker 1** completes its task before **Worker 2** starts summarizing the transcript.

- **Worker 2** completes its task before **Worker 3** finalizes the process.

### Why Developers Should Choose Swarms:

Swarms is designed with flexibility at its core. Developers can create custom architectures and workflows, enabling extreme control over how agents interact with each other. Whether it’s a linear process or a complex mesh of agent communications, Swarms handles it efficiently.

With support for extreme third-party integration, Swarms makes it easy for developers to plug into external systems, such as APIs or internal databases. This allows agents to act on live data, process external inputs, and execute actions in real time, making it a powerful tool for real-world applications.

Swarms abstracts the complexity of managing multiple agents with orchestration tools like `AgentRearrange`. Developers can define workflows that execute tasks concurrently or sequentially, depending on the problem at hand. This makes it easy to build and maintain large-scale automation systems.

### Conclusion:
Swarms is not just another multi-agent framework; it's built specifically for developers who need powerful tools to automate complex, large-scale business operations. With flexible architecture, deep integration capabilities, and developer-friendly APIs, Swarms is the ultimate solution for businesses looking to streamline operations and future-proof their workflows.

--------------------------------------------------

# File: swarms/concept/why.md

**Maximizing Enterprise Automation: Overcoming the Limitations of Individual AI Agents Through Multi-Agent Collaboration**


In today's rapidly evolving business landscape, enterprises are constantly seeking innovative solutions to enhance efficiency, reduce operational costs, and maintain a competitive edge. Automation has emerged as a critical strategy for achieving these objectives, with artificial intelligence (AI) playing a pivotal role. AI agents, particularly those powered by advanced machine learning models, have shown immense potential in automating a variety of tasks. However, individual AI agents come with inherent limitations that hinder their ability to fully automate complex enterprise operations at scale.

This essay dives into the specific limitations of individual AI agents—context window limits, hallucination, single-task execution, lack of collaboration, lack of accuracy, and slow processing speed—and explores how multi-agent collaboration can overcome these challenges. By tailoring our discussion to the needs of enterprises aiming to automate operations at scale, we highlight practical strategies and frameworks that can be adopted to unlock the full potential of AI-driven automation.

---

### Part 1: The Limitations of Individual AI Agents

Despite significant advancements, individual AI agents face several obstacles that limit their effectiveness in enterprise automation. Understanding these limitations is crucial for organizations aiming to implement AI solutions that are both efficient and scalable.

#### 1. Context Window Limits

**Explanation**

AI agents, especially those based on language models like GPT-3 or GPT-4, operate within a fixed context window. This means they can only process and consider a limited amount of information (tokens) at a time. In practical terms, this restricts the agent's ability to handle large documents, long conversations, or complex datasets that exceed their context window.

**Impact on Enterprises**

For enterprises, this limitation poses significant challenges. Business operations often involve processing extensive documents such as legal contracts, technical manuals, or large datasets. An AI agent with a limited context window may miss crucial information located outside its immediate context, leading to incomplete analyses or erroneous conclusions.


```mermaid
graph LR
    subgraph "Context Window Limit"
        Input[Large Document]
        Agent[AI Agent]
        Output[Partial Understanding]
        Input -- Truncated Data --> Agent
        Agent -- Generates --> Output
    end
```

*An AI agent processes only a portion of a large document due to context window limits, resulting in partial understanding.*

#### 2. Hallucination

**Explanation**

Hallucination refers to the tendency of AI agents to produce outputs that are not grounded in the input data or reality. They may generate plausible-sounding but incorrect or nonsensical information, especially when uncertain or when the input data is ambiguous.

**Impact on Enterprises**

In enterprise settings, hallucinations can lead to misinformation, poor decision-making, and a lack of trust in AI systems. For instance, if an AI agent generates incorrect financial forecasts or misinterprets regulatory requirements, the consequences could be financially damaging and legally problematic.


```mermaid
graph TD
    Input[Ambiguous Data]
    Agent[AI Agent]
    Output[Incorrect Information]
    Input --> Agent
    Agent --> Output
```

*An AI agent generates incorrect information (hallucination) when processing ambiguous data.*

#### 3. Single Task Execution

**Explanation**

Many AI agents are designed to excel at a specific task or a narrow set of functions. They lack the flexibility to perform multiple tasks simultaneously or adapt to new tasks without significant reconfiguration or retraining.

**Impact on Enterprises**

Enterprises require systems that can handle a variety of tasks, often concurrently. Relying on single-task agents necessitates deploying multiple separate agents, which can lead to integration challenges, increased complexity, and higher maintenance costs.


```mermaid
graph LR
    TaskA[Task A] --> AgentA[Agent A]
    TaskB[Task B] --> AgentB[Agent B]
    AgentA --> OutputA[Result A]
    AgentB --> OutputB[Result B]
```

*Separate agents handle different tasks independently, lacking integration.*

#### 4. Lack of Collaboration

**Explanation**

Individual AI agents typically operate in isolation, without the ability to communicate or collaborate with other agents. This siloed operation prevents them from sharing insights, learning from each other, or coordinating actions to achieve a common goal.

**Impact on Enterprises**

Complex enterprise operations often require coordinated efforts across different functions and departments. The inability of AI agents to collaborate limits their effectiveness in such environments, leading to disjointed processes and suboptimal outcomes.


```mermaid
graph LR
    Agent1[Agent 1]
    Agent2[Agent 2]
    Agent3[Agent 3]
    Agent1 -->|No Communication| Agent2
    Agent2 -->|No Communication| Agent3
```

*Agents operate without collaboration, resulting in isolated efforts.*

#### 5. Lack of Accuracy

**Explanation**

AI agents may produce inaccurate results due to limitations in their training data, algorithms, or inability to fully understand complex inputs. Factors such as data bias, overfitting, or lack of domain-specific knowledge contribute to this inaccuracy.

**Impact on Enterprises**

Inaccurate outputs can have serious ramifications for businesses, including flawed strategic decisions, customer dissatisfaction, and compliance risks. High accuracy is essential for tasks like financial analysis, customer service, and regulatory compliance.


```mermaid
graph TD
    Input[Complex Data]
    Agent[AI Agent]
    Output[Inaccurate Result]
    Input --> Agent
    Agent --> Output
```

*An AI agent produces an inaccurate result when handling complex data.*

#### 6. Slow Processing Speed

**Explanation**

Some AI agents require significant computational resources and time to process data and generate outputs. Factors like model complexity, inefficient algorithms, or hardware limitations can contribute to slow processing speeds.

**Impact on Enterprises**

Slow processing impedes real-time decision-making and responsiveness. In fast-paced business environments, delays can lead to missed opportunities, reduced productivity, and competitive disadvantages.


```mermaid
graph TD
    Input[Data]
    Agent[AI Agent]
    Delay[Processing Delay]
    Output[Delayed Response]
    Input --> Agent
    Agent --> Delay
    Delay --> Output
```

*An AI agent's slow processing leads to delayed responses.*

---

### Part 2: Overcoming Limitations Through Multi-Agent Collaboration

To address the challenges posed by individual AI agents, enterprises can adopt a multi-agent collaboration approach. By orchestrating multiple agents with complementary skills and functionalities, organizations can enhance performance, accuracy, and scalability in their automation efforts.

#### 1. Extending Context Window Through Distributed Processing

**Solution**

By dividing large inputs into smaller segments, multiple agents can process different parts simultaneously. A coordinating agent can then aggregate the results to form a comprehensive understanding.

**Implementation in Enterprises**

- **Document Analysis:** For lengthy legal contracts, agents can each analyze specific sections, and a master agent can compile insights and ensure consistency.
- **Customer Interaction History:** In customer service, agents can handle different segments of a customer's history to provide personalized support.


```mermaid
graph LR
    Input[Large Document]
    Splitter[Splitter Agent]
    A1[Agent 1]
    A2[Agent 2]
    A3[Agent 3]
    Aggregator[Aggregator Agent]
    Output[Comprehensive Analysis]
    Input --> Splitter
    Splitter --> A1
    Splitter --> A2
    Splitter --> A3
    A1 --> Aggregator
    A2 --> Aggregator
    A3 --> Aggregator
    Aggregator --> Output
```

*Multiple agents process segments of a large document, and results are aggregated.*

#### 2. Reducing Hallucination Through Cross-Verification

**Solution**

Agents can verify each other's outputs by cross-referencing information and flagging inconsistencies. Implementing consensus mechanisms ensures that only accurate information is accepted.

**Implementation in Enterprises**

- **Data Validation:** In data entry automation, one agent inputs data while another validates it against source documents.
- **Decision Support Systems:** Multiple agents evaluate options and agree on recommendations, reducing the risk of incorrect advice.


```mermaid
graph TD
    A[Agent's Output]
    V1[Verifier Agent 1]
    V2[Verifier Agent 2]
    Consensus[Consensus Mechanism]
    Output[Validated Output]
    A --> V1
    A --> V2
    V1 & V2 --> Consensus
    Consensus --> Output
```

*Agents verify outputs through cross-verification and consensus.*

#### 3. Enhancing Multi-Tasking Through Specialized Agents

**Solution**

Deploy specialized agents for different tasks and enable them to work concurrently. An orchestrator agent manages task allocation and workflow integration.

**Implementation in Enterprises**

- **Automated Workflows:** In supply chain management, one agent handles inventory analysis, another manages logistics, and a third forecasts demand.
- **IT Operations:** In IT automation, separate agents manage network monitoring, security scanning, and system updates.


```mermaid
graph LR
    Task[Complex Task]
    Orchestrator[Orchestrator Agent]
    AgentA[Specialist Agent A]
    AgentB[Specialist Agent B]
    AgentC[Specialist Agent C]
    Output[Integrated Solution]
    Task --> Orchestrator
    Orchestrator --> AgentA
    Orchestrator --> AgentB
    Orchestrator --> AgentC
    AgentA & AgentB & AgentC --> Orchestrator
    Orchestrator --> Output
```

*Specialized agents handle different tasks under the management of an orchestrator agent.*

#### 4. Facilitating Collaboration Through Communication Protocols

**Solution**

Implement communication protocols that allow agents to share information, request assistance, and coordinate actions. This fosters a collaborative environment where agents complement each other's capabilities.

**Implementation in Enterprises**

- **Customer Service:** Chatbots and virtual assistants share customer data to provide seamless support across channels.
- **Project Management:** Agents managing different aspects of a project (scheduling, resource allocation, risk assessment) coordinate to keep the project on track.


```mermaid
graph LR
    Agent1[Agent 1]
    Agent2[Agent 2]
    Agent3[Agent 3]
    Agent1 <--> Agent2
    Agent2 <--> Agent3
    Agent3 <--> Agent1
    Output[Collaborative Outcome]
```

*Agents communicate and collaborate to achieve a common goal.*

#### 5. Improving Accuracy Through Ensemble Learning

**Solution**

Use ensemble methods where multiple agents provide predictions or analyses, and a meta-agent combines these to produce a more accurate result.

**Implementation in Enterprises**

- **Risk Assessment:** Different agents assess risks from various perspectives (financial, operational, compliance), and their insights are combined.
- **Market Analysis:** Agents analyze market trends, customer behavior, and competitor actions, leading to a comprehensive market strategy.


```mermaid
graph TD
    AgentA[Agent A Output]
    AgentB[Agent B Output]
    AgentC[Agent C Output]
    MetaAgent[Meta-Agent]
    Output[Enhanced Accuracy]
    AgentA --> MetaAgent
    AgentB --> MetaAgent
    AgentC --> MetaAgent
    MetaAgent --> Output
```

*Meta-agent combines outputs from multiple agents to improve accuracy.*

#### 6. Increasing Processing Speed Through Parallelization

**Solution**

By distributing workloads among multiple agents operating in parallel, processing times are significantly reduced, enabling real-time responses.

**Implementation in Enterprises**

- **Data Processing:** Large datasets are partitioned and processed simultaneously by different agents.
- **Customer Requests:** Multiple customer inquiries are handled at once by separate agents, improving response times.


```mermaid
graph LR
    Data[Large Dataset]
    Agent1[Agent 1]
    Agent2[Agent 2]
    Agent3[Agent 3]
    Output[Processed Data]
    Data --> Agent1
    Data --> Agent2
    Data --> Agent3
    Agent1 & Agent2 & Agent3 --> Output
```

*Parallel processing by agents leads to faster completion times.*

---

### Part 3: Tailoring Multi-Agent Systems for Enterprise Automation at Scale

Implementing multi-agent systems in an enterprise context requires careful planning and consideration of organizational needs, technical infrastructure, and strategic goals. Below are key considerations and steps for enterprises aiming to adopt multi-agent collaboration for automation at scale.

#### 1. Identifying Automation Opportunities

Enterprises should start by identifying processes and tasks that are suitable for automation through multi-agent systems. Prioritize areas where:

- **Complexity Requires Specialization:** Tasks that involve multiple steps or require diverse expertise.
- **Scalability Is Essential:** Operations that need to handle increasing workloads efficiently.
- **Speed and Accuracy Are Critical:** Processes where delays or errors have significant impacts.

#### 2. Designing the Multi-Agent Architecture

Develop a robust architecture that defines how agents will interact, communicate, and collaborate. Key components include:

- **Agent Specialization:** Define the roles and responsibilities of each agent.
- **Communication Protocols:** Establish standards for information exchange.
- **Coordination Mechanisms:** Implement orchestrator agents or decentralized coordination strategies.
- **Integration with Existing Systems:** Ensure compatibility with current IT infrastructure.

#### 3. Ensuring Data Security and Compliance

Data security is paramount when agents handle sensitive enterprise information. Implement measures such as:

- **Encryption:** Secure communication channels between agents.
- **Access Control:** Define permissions for data access and agent capabilities.
- **Compliance Checks:** Ensure the system adheres to relevant regulations (e.g., GDPR, HIPAA).

#### 4. Monitoring and Performance Management

Establish monitoring tools to track agent performance, system health, and outcomes. Key metrics may include:

- **Processing Speed:** Measure how quickly tasks are completed.
- **Accuracy Rates:** Track the correctness of outputs.
- **Resource Utilization:** Monitor computational resources used by agents.
- **Error Logs:** Identify and address failures or exceptions.

#### 5. Scaling Strategies

Develop strategies for scaling the system as enterprise needs grow, including:

- **Dynamic Resource Allocation:** Adjust computational resources based on workload.
- **Agent Addition or Removal:** Add new agents or deactivate others to meet changing demands.
- **Load Balancing:** Distribute tasks evenly to prevent bottlenecks.

#### 6. Continuous Improvement

Implement feedback loops for ongoing enhancement of the multi-agent system:

- **User Feedback:** Gather input from users interacting with the system.
- **Performance Analytics:** Analyze data to identify areas for optimization.
- **Updating Agents:** Regularly update agent algorithms and knowledge bases.

---

### Part 4: Case Studies and Real-World Applications

To illustrate the practical benefits of multi-agent collaboration in enterprise automation, let's explore several real-world examples.

#### Case Study 1: Financial Services Automation

**Challenge**

A financial institution needs to process large volumes of loan applications, requiring data verification, risk assessment, compliance checks, and decision-making.

**Solution**

- **Specialized Agents:**
  - **Data Extraction Agent:** Extracts data from application forms.
  - **Verification Agent:** Confirms the accuracy of applicant information.
  - **Risk Assessment Agent:** Evaluates credit risk using predictive models.
  - **Compliance Agent:** Ensures all regulatory requirements are met.
  - **Decision Agent:** Aggregates inputs and makes approval decisions.

- **Collaboration:**
  - Agents communicate to share data and findings.
  - The Decision Agent coordinates the workflow.

**Outcome**

- **Increased Processing Speed:** Applications are processed in minutes instead of days.
- **Improved Accuracy:** Cross-verification reduces errors.
- **Scalability:** System handles fluctuating application volumes efficiently.

#### Case Study 2: Manufacturing Supply Chain Optimization

**Challenge**

A manufacturing company wants to optimize its supply chain to reduce costs and improve delivery times.

**Solution**

- **Specialized Agents:**
  - **Demand Forecasting Agent:** Predicts product demand.
  - **Inventory Management Agent:** Monitors stock levels and orders materials.
  - **Logistics Agent:** Plans shipping routes and schedules.
  - **Supplier Evaluation Agent:** Assesses supplier performance and reliability.

- **Collaboration:**
  - Agents share data on demand forecasts and inventory levels.
  - Logistics Agent adjusts plans based on input from other agents.

**Outcome**

- **Cost Reduction:** Optimized inventory levels reduce holding costs.
- **Efficiency Gains:** Improved logistics planning enhances delivery times.
- **Adaptability:** System responds quickly to changes in demand or supply disruptions.

#### Case Study 3: Healthcare Patient Management

**Challenge**

A hospital aims to improve patient care coordination, managing appointments, medical records, billing, and treatment plans.

**Solution**

- **Specialized Agents:**
  - **Appointment Scheduling Agent:** Manages patient appointments.
  - **Medical Records Agent:** Updates and retrieves patient records.
  - **Billing Agent:** Handles invoicing and insurance claims.
  - **Treatment Planning Agent:** Assists in developing patient care plans.

- **Collaboration:**
  - Agents coordinate to ensure seamless patient experiences.
  - Data is securely shared while maintaining patient confidentiality.

**Outcome**

- **Enhanced Patient Care:** Improved coordination leads to better treatment outcomes.
- **Operational Efficiency:** Administrative tasks are streamlined.
- **Compliance:** System adheres to healthcare regulations (e.g., HIPAA).

---

### Part 5: Implementing Multi-Agent Systems – Best Practices for Enterprises

For enterprises embarking on the journey of multi-agent automation, adhering to best practices ensures successful implementation.

#### 1. Start Small and Scale Gradually

- **Pilot Projects:** Begin with a specific process or department to test the multi-agent system.
- **Learn and Adapt:** Use insights from initial deployments to refine the system.

#### 2. Invest in Training and Change Management

- **Employee Education:** Train staff on interacting with and managing multi-agent systems.
- **Change Management:** Prepare the organization for changes in workflows and roles.

#### 3. Leverage Cloud and Edge Computing

- **Scalable Infrastructure:** Utilize cloud services for flexible resource allocation.
- **Edge Computing:** Deploy agents closer to data sources for faster processing.

#### 4. Foster Interoperability

- **Standards Compliance:** Use industry standards for data formats and communication protocols.
- **API Integration:** Ensure agents can integrate with existing enterprise applications.

#### 5. Prioritize Ethical Considerations

- **Transparency:** Maintain clear documentation of how agents make decisions.
- **Bias Mitigation:** Implement strategies to prevent and correct algorithmic biases.
- **Accountability:** Establish protocols for human oversight and intervention.

---

### Conclusion

Enterprises seeking to automate operations at scale face the limitations inherent in individual AI agents. Context window limits, hallucinations, single-task execution, lack of collaboration, lack of accuracy, and slow processing speed hinder the full potential of automation efforts. Multi-agent collaboration emerges as a robust solution to these challenges, offering a pathway to enhanced efficiency, accuracy, scalability, and adaptability.

By adopting multi-agent systems, enterprises can:

- **Extend Capabilities:** Overcome individual agent limitations through collective intelligence.
- **Improve Outcomes:** Achieve higher accuracy and faster processing by leveraging specialized agents.
- **Enhance Flexibility:** Adapt to changing business needs with scalable and versatile agent architectures.
- **Drive Innovation:** Foster a culture of continuous improvement and technological advancement.

Implementing multi-agent systems requires thoughtful planning, adherence to best practices, and a commitment to ongoing management and optimization. Enterprises that successfully navigate this journey will position themselves at the forefront of automation, unlocking new levels of productivity and competitive advantage in an increasingly digital world.


--------------------------------------------------

# File: swarms/contributing.md

# Contribution Guidelines

---

## Table of Contents

- [Project Overview](#project-overview)
- [Getting Started](#getting-started)
  - [Installation](#installation)
  - [Project Structure](#project-structure)
- [How to Contribute](#how-to-contribute)
  - [Reporting Issues](#reporting-issues)
  - [Submitting Pull Requests](#submitting-pull-requests)
- [Coding Standards](#coding-standards)
  - [Type Annotations](#type-annotations)
  - [Docstrings and Documentation](#docstrings-and-documentation)
  - [Testing](#testing)
  - [Code Style](#code-style)
- [Areas Needing Contributions](#areas-needing-contributions)
  - [Writing Tests](#writing-tests)
  - [Improving Documentation](#improving-documentation)
  - [Creating Training Scripts](#creating-training-scripts)
- [Community and Support](#community-and-support)
- [License](#license)

---

## Project Overview

**swarms** is a library focused on making it simple to orchestrate agents to automate real-world activities. The goal is to automate the world economy with these swarms of agents.

We need your help to:

- **Write Tests**: Ensure the reliability and correctness of the codebase.
- **Improve Documentation**: Maintain clear and comprehensive documentation.
- **Add New Orchestration Methods**: Add multi-agent orchestration methods
- **Removing Defunct Code**: Removing bad code



Your contributions will help us push the boundaries of AI and make this library a valuable resource for the community.

---

## Getting Started

### Installation

You can install swarms using `pip`:

```bash
pip3 install swarms
```

Alternatively, you can clone the repository:

```bash
git clone https://github.com/kyegomez/swarms
```

### Project Structure

- **`swarms/`**: Contains all the source code for the library.
- **`examples/`**: Includes example scripts and notebooks demonstrating how to use the library.
- **`tests/`**: (To be created) Will contain unit tests for the library.
- **`docs/`**: (To be maintained) Contains documentation files.

---

## How to Contribute

### Reporting Issues

If you find any bugs, inconsistencies, or have suggestions for enhancements, please open an issue on GitHub:

1. **Search Existing Issues**: Before opening a new issue, check if it has already been reported.
2. **Open a New Issue**: If it hasn't been reported, create a new issue and provide detailed information.
   - **Title**: A concise summary of the issue.
   - **Description**: Detailed description, steps to reproduce, expected behavior, and any relevant logs or screenshots.
3. **Label Appropriately**: Use labels to categorize the issue (e.g., bug, enhancement, documentation).

### Submitting Pull Requests

We welcome pull requests (PRs) for bug fixes, improvements, and new features. Please follow these guidelines:

1. **Fork the Repository**: Create a personal fork of the repository on GitHub.
2. **Clone Your Fork**: Clone your forked repository to your local machine.

   ```bash
   git clone https://github.com/kyegomez/swarms.git
   ```

3. **Create a New Branch**: Use a descriptive branch name.

   ```bash
   git checkout -b feature/your-feature-name
   ```

4. **Make Your Changes**: Implement your code, ensuring it adheres to the coding standards.
5. **Add Tests**: Write tests to cover your changes.
6. **Commit Your Changes**: Write clear and concise commit messages.

   ```bash
   git commit -am "Add feature X"
   ```

7. **Push to Your Fork**:

   ```bash
   git push origin feature/your-feature-name
   ```

8. **Create a Pull Request**:

   - Go to the original repository on GitHub.
   - Click on "New Pull Request".
   - Select your branch and create the PR.
   - Provide a clear description of your changes and reference any related issues.

9. **Respond to Feedback**: Be prepared to make changes based on code reviews.

**Note**: It's recommended to create small and focused PRs for easier review and faster integration.

---

## Coding Standards

To maintain code quality and consistency, please adhere to the following standards.

### Type Annotations

- **Mandatory**: All functions and methods must have type annotations.
- **Example**:

  ```python
  def add_numbers(a: int, b: int) -> int:
      return a + b
  ```

- **Benefits**:
  - Improves code readability.
  - Helps with static type checking tools.

### Docstrings and Documentation

- **Docstrings**: Every public class, function, and method must have a docstring following the [Google Python Style Guide](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) or [NumPy Docstring Standard](https://numpydoc.readthedocs.io/en/latest/format.html).
- **Content**:
  - **Description**: Briefly describe what the function or class does.
  - **Args**: List and describe each parameter.
  - **Returns**: Describe the return value(s).
  - **Raises**: List any exceptions that are raised.

- **Example**:

  ```python
  def calculate_mean(values: List[float]) -> float:
      """
      Calculates the mean of a list of numbers.

      Args:
          values (List[float]): A list of numerical values.

      Returns:
          float: The mean of the input values.

      Raises:
          ValueError: If the input list is empty.
      """
      if not values:
          raise ValueError("The input list is empty.")
      return sum(values) / len(values)
  ```

- **Documentation**: Update or create documentation pages if your changes affect the public API.

### Testing

- **Required**: All new features and bug fixes must include appropriate unit tests.
- **Framework**: Use `unittest`, `pytest`, or a similar testing framework.
- **Test Location**: Place tests in the `tests/` directory, mirroring the structure of `swarms/`.
- **Test Coverage**: Aim for high test coverage to ensure code reliability.
- **Running Tests**: Provide instructions for running tests.

  ```bash
  pytest tests/
  ```

### Code Style

- **PEP 8 Compliance**: Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guidelines.
- **Linting Tools**: Use `flake8`, `black`, or `pylint` to check code style.
- **Consistency**: Maintain consistency with the existing codebase.

---

## Areas Needing Contributions

We have several areas where contributions are particularly welcome.

### Writing Tests

- **Goal**: Increase test coverage to ensure the library's robustness.
- **Tasks**:
  - Write unit tests for existing code in `swarms/`.
  - Identify edge cases and potential failure points.
  - Ensure tests are repeatable and independent.

### Improving Documentation

- **Goal**: Maintain clear and comprehensive documentation for users and developers.
- **Tasks**:
  - Update docstrings to reflect any changes.
  - Add examples and tutorials in the `examples/` directory.
  - Improve or expand the content in the `docs/` directory.

### Creating Multi-Agent Orchestration Methods

- **Goal**: Provide new multi-agent orchestration methods

---

## Community and Support

- **Communication**: Engage with the community by participating in discussions on issues and pull requests.
- **Respect**: Maintain a respectful and inclusive environment.
- **Feedback**: Be open to receiving and providing constructive feedback.

---

## License

By contributing to swarms, you agree that your contributions will be licensed under the [MIT License](LICENSE).

---

Thank you for contributing to swarms! Your efforts help make this project better for everyone.

If you have any questions or need assistance, please feel free to open an issue or reach out to the maintainers.

--------------------------------------------------

# File: swarms/ecosystem.md


# Swarms Infrastructure Stack

**We're Building the Operating System for the Agent Economy** 

The Swarms ecosystem represents the most comprehensive, production-ready multi-agent AI platform available today. From our flagship Python framework to high-performance Rust implementations and client libraries spanning every major programming language, we provide enterprise-grade tools that power the next generation of agentic applications.

---

## **Product Portfolio by Language & API**

### 🐍 **Python**

| **Product**                  | **Description**                                                                                                                                                                                                 | **Status**      | **Repository**                                                                 | **Documentation**                                                                                  |
|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| **Swarms Python Framework**  | The core multi-agent orchestration framework for Python. Enables building, managing, and scaling complex agentic systems with robust abstractions, workflows, and integrations.                                 | **Production**  | [swarms](https://github.com/kyegomez/swarms)                                  | [Docs](https://docs.swarms.world/en/latest/swarms/install/install/)                                |
| **Python API Client**        | Official Python SDK for interacting with Swarms Cloud and remote agent infrastructure. Simplifies API calls, authentication, and integration into Python applications.                                          | **Production**  | [swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk)             | [Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/)                            |
| **Swarms Tools**             | A comprehensive library of prebuilt tools for various domains, including finance, social media, data processing, and more. Accelerates agent development by providing ready-to-use capabilities and integrations. | **Production**  | [swarms-tools](https://github.com/The-Swarm-Corporation/swarms-tools)          | *Coming Soon*                                                                                      |
| **Swarms Memory**            | A robust library of memory structures and data loaders for Retrieval-Augmented Generation (RAG) processing. Provides advanced memory management, vector stores, and integration with agentic workflows.         | **Production**  | [swarms-memory](https://github.com/The-Swarm-Corporation/swarms-memory)        | *Coming Soon*                                                                                      |

---

### 🦀 **Rust**

| **Product**                | **Description**                                                                                                                                                                                                 | **Status**      | **Repository**                                                                 | **Documentation**                                                                                  |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| **Swarms Rust Framework**  | High-performance, memory-safe multi-agent orchestration framework written in Rust. Designed for demanding production environments and seamless integration with Rust-based systems.                              | **Production**  | [swarms-rs](https://github.com/The-Swarm-Corporation/swarms-rs)               | [Docs](https://docs.swarms.world/en/latest/swarms_rs/overview/)                                   |
| **Rust Client**            | Official Rust client library for connecting to Swarms Cloud and orchestrating agents from Rust applications. Provides idiomatic Rust APIs for agent management and communication.                              | **Q2 2025**     | *In Development*                                                              | *Coming Soon*                                                                                      |

---

### 🌐 **API Clients (Multi-Language)**

| **Language/Platform**      | **Description**                                                                                                                                                                                                 | **Status**      | **Repository**                                                                 | **Documentation**                                                                                  |
|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| **TypeScript/Node.js**     | Official TypeScript/Node.js SDK for Swarms Cloud. Enables seamless integration of agentic workflows into JavaScript and TypeScript applications, both server-side and in the browser.                           | **Production**  | [swarms-ts](https://github.com/The-Swarm-Corporation/swarms-ts)               | *Coming Soon*                                                                                      |
| **Go**                     | Go client library for Swarms Cloud, providing Go developers with native APIs to manage, orchestrate, and interact with agents in distributed systems and microservices.                                         | **Production**  | [swarms-client-go](https://github.com/The-Swarm-Corporation/swarms-client-go) | *Coming Soon*                                                                                      |
| **Java**                   | Java SDK for Swarms Cloud, allowing enterprise Java applications to leverage multi-agent orchestration and integrate agentic capabilities into JVM-based systems.                                               | **Production**  | [swarms-java](https://github.com/The-Swarm-Corporation/swarms-java)           | *Coming Soon*                                                                                      |
| **Kotlin**                 | Native Kotlin client for Swarms Cloud, designed for modern JVM and Android applications seeking to embed agentic intelligence and orchestration.                                                               | **Q2 2025**     | *In Development*                                                              | *Coming Soon*                                                                                      |
| **Ruby**                   | Ruby SDK for Swarms Cloud, enabling Ruby and Rails developers to easily connect, manage, and orchestrate agents within their applications.                                                                     | **Q2 2025**     | *In Development*                                                              | *Coming Soon*                                                                                      |
| **C#/.NET**                | Official C#/.NET client library for Swarms Cloud, providing .NET developers with tools to integrate agentic workflows into desktop, web, and cloud applications.                                               | **Q3 2025**     | *In Development*                                                              | *Coming Soon*                                                                                      |

---

## **Why Choose the Swarms Ecosystem?**

| **Feature**                | **Description**                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------------|
| **Production Ready**         | Battle-tested in enterprise environments with 99.9%+ uptime                                           |
| **Scalable Infrastructure** | Handle millions of agent interactions with automatic scaling                                         |
| **Security First**          | End-to-end encryption, API key management, and enterprise compliance                                 |
| **Observability**           | Comprehensive logging, monitoring, and debugging capabilities                                        |
| **Multiple Language Support** | Native clients for every major programming language                                                  |
| **Unified API**             | Consistent interface across all platforms and languages                                              |
| **Rich Documentation**      | Comprehensive guides, tutorials, and API references                                                  |
| **Active Community**        | 24/7 support through Discord, GitHub, and direct channels                                            |
| **High Throughput**         | Process thousands of concurrent agent requests                                                       |
| **Low Latency**             | Optimized for real-time applications and user experiences                                            |
| **Fault Tolerance**         | Automatic retries, circuit breakers, and graceful degradation                                        |
| **Multi-Cloud**             | Deploy on AWS, GCP, Azure, or on-premises infrastructure                                             |

---


--------------------------------------------------

# File: swarms/examples/agent_output_types.md

# Agent Output Types Examples with Vision Capabilities

This example demonstrates how to use different output types when working with Swarms agents, including vision-enabled agents that can analyze images. Each output type formats the agent's response in a specific way, making it easier to integrate with different parts of your application.

## Prerequisites

- Python 3.7+
- OpenAI API key
- Anthropic API key (optional, for Claude models)
- Swarms library

## Installation

```bash
pip3 install -U swarms
```

## Environment Variables

```plaintext
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""  # Required for GPT-4V vision capabilities
ANTHROPIC_API_KEY=""  # Optional, for Claude models
```

## Examples

### Vision-Enabled Quality Control Agent

```python
from swarms.structs import Agent
from swarms.prompts.logistics import (
    Quality_Control_Agent_Prompt,
)

# Image for analysis
factory_image = "image.jpg"


# Quality control agent
quality_control_agent = Agent(
    agent_name="Quality Control Agent",
    agent_description="A quality control agent that analyzes images and provides a detailed report on the quality of the product in the image.",
    model_name="gpt-4.1-mini",
    system_prompt=Quality_Control_Agent_Prompt,
    multi_modal=True,
    max_loops=2,
    output_type="str-all-except-first",
)


response = quality_control_agent.run(
    task="what is in the image?",
    img=factory_image,
)

print(response)

```

### Supported Image Formats

The vision-enabled agents support various image formats including:

| Format | Description |
|--------|-------------|
| JPEG/JPG | Standard image format with lossy compression |
| PNG | Lossless format supporting transparency |
| GIF | Animated format (only first frame used) |
| WebP | Modern format with both lossy and lossless compression |

### Best Practices for Vision Tasks

| Best Practice | Description |
|--------------|-------------|
| Image Quality | Ensure images are clear and well-lit for optimal analysis |
| Image Size | Keep images under 20MB and in supported formats |
| Task Specificity | Provide clear, specific instructions for image analysis |
| Model Selection | Use vision-capable models (e.g., GPT-4V) for image tasks |

--------------------------------------------------

# File: swarms/examples/agent_structured_outputs.md

# Agent Structured Outputs

This example demonstrates how to use structured outputs with Swarms agents following OpenAI's function calling schema. By defining function schemas, you can specify exactly how agents should structure their responses, making it easier to parse and use the outputs in your applications.

## Prerequisites

- Python 3.7+
- OpenAI API key
- Swarms library

## Installation

```bash
pip3 install -U swarms
```

## Environment Variables

```plaintext
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
```

## Understanding Function Schemas

Function schemas in Swarms follow OpenAI's function calling format. Each function schema is defined as a dictionary with the following structure:

```python
{
    "type": "function",
    "function": {
        "name": "function_name",
        "description": "A clear description of what the function does",
        "parameters": {
            "type": "object",
            "properties": {
                # Define the parameters your function accepts
            },
            "required": ["list", "of", "required", "parameters"]
        }
    }
}
```

## Code Example

Here's an example showing how to use multiple function schemas with a Swarms agent:

```python
from swarms import Agent
from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT

# Define multiple function schemas
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "Retrieve the current stock price and related information for a specified company.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "The stock ticker symbol of the company, e.g. AAPL for Apple Inc.",
                    },
                    "include_history": {
                        "type": "boolean",
                        "description": "Whether to include historical price data.",
                    },
                    "time": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Optional time for stock data, in ISO 8601 format.",
                    },
                },
                "required": ["ticker", "include_history"]
            },
        },
    },
    # Can pass in multiple function schemas as well
    {
        "type": "function",
        "function": {
            "name": "analyze_company_financials",
            "description": "Analyze key financial metrics and ratios for a company.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "The stock ticker symbol of the company",
                    },
                    "metrics": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "enum": ["PE_ratio", "market_cap", "revenue", "profit_margin"]
                        },
                        "description": "List of financial metrics to analyze"
                    },
                    "timeframe": {
                        "type": "string",
                        "enum": ["quarterly", "annual", "ttm"],
                        "description": "Timeframe for the analysis"
                    }
                },
                "required": ["ticker", "metrics"]
            }
        }
    }
]

# Initialize the agent with multiple function schemas
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Personal finance advisor agent that can fetch stock prices and analyze financials",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    max_loops=1,
    tools_list_dictionary=tools,  # Pass in the list of function schemas
    output_type="final"
)

# Example usage with stock price query
stock_response = agent.run(
    "What is the current stock price for Apple Inc. (AAPL)? Include historical data."
)
print("Stock Price Response:", stock_response)

# Example usage with financial analysis query
analysis_response = agent.run(
    "Analyze Apple's PE ratio and market cap using quarterly data."
)
print("Financial Analysis Response:", analysis_response)
```

## Schema Types and Properties

The function schema supports various parameter types and properties:

| Schema Type | Description |
|------------|-------------|
| Basic Types | `string`, `number`, `integer`, `boolean`, `array`, `object` |
| Format Specifications | `date-time`, `date`, `email`, etc. |
| Enums | Restrict values to a predefined set |
| Required vs Optional Parameters | Specify which parameters must be provided |
| Nested Objects and Arrays | Support for complex data structures |

Example of a more complex schema:

```python
{
    "type": "function",
    "function": {
        "name": "generate_investment_report",
        "description": "Generate a comprehensive investment report",
        "parameters": {
            "type": "object",
            "properties": {
                "portfolio": {
                    "type": "object",
                    "properties": {
                        "stocks": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "ticker": {"type": "string"},
                                    "shares": {"type": "number"},
                                    "entry_price": {"type": "number"}
                                }
                            }
                        },
                        "risk_tolerance": {
                            "type": "string",
                            "enum": ["low", "medium", "high"]
                        },
                        "time_horizon": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 30,
                            "description": "Investment time horizon in years"
                        }
                    },
                    "required": ["stocks", "risk_tolerance"]
                },
                "report_type": {
                    "type": "string",
                    "enum": ["summary", "detailed", "risk_analysis"]
                }
            },
            "required": ["portfolio"]
        }
    }
}
```

This example shows how to structure complex nested objects, arrays, and various parameter types while following OpenAI's function calling schema.


--------------------------------------------------

# File: swarms/examples/agent_with_tools.md

# Basic Agent Example

This tutorial demonstrates how to create and use tools (callables) with the Swarms framework. Tools are Python functions that your agent can call to perform specific tasks, interact with external services, or process data. We'll show you how to build well-structured tools and integrate them with your agent.

## Prerequisites

- Python 3.7+

- OpenAI API key

- Swarms library

## Building Tools for Your Agent

Tools are functions that your agent can use to interact with external services, process data, or perform specific tasks. Here's a guide on how to build effective tools for your agent:

### Tool Structure Best Practices

1. **Type Hints**: Always use type hints to specify input and output types

2. **Docstrings**: Include comprehensive docstrings with description, args, returns, and examples

3. **Error Handling**: Implement proper error handling and return consistent JSON responses

4. **Rate Limiting**: Include rate limiting when dealing with APIs

5. **Input Validation**: Validate input parameters before processing

### Example Tool Template

Here's a template for creating a well-structured tool:

```python
from typing import Optional, Dict, Any
import json

def example_tool(param1: str, param2: Optional[int] = None) -> str:
    """
    Brief description of what the tool does.

    Args:
        param1 (str): Description of first parameter
        param2 (Optional[int]): Description of optional parameter

    Returns:
        str: JSON formatted string containing the result

    Raises:
        ValueError: Description of when this error occurs
        RequestException: Description of when this error occurs

    Example:
        >>> result = example_tool("test", 123)
        >>> print(result)
        {"status": "success", "data": {"key": "value"}}
    """
    try:
        # Input validation
        if not isinstance(param1, str):
            raise ValueError("param1 must be a string")

        # Main logic
        result: Dict[str, Any] = {
            "status": "success",
            "data": {
                "param1": param1,
                "param2": param2
            }
        }

        # Return JSON string
        return json.dumps(result, indent=2)

    except ValueError as e:
        return json.dumps({"error": f"Validation error: {str(e)}"})
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})
```

### Building API Integration Tools

When building tools that interact with external APIs:

1. **API Client Setup**:

```python
def get_api_data(endpoint: str, params: Dict[str, Any]) -> str:
    """
    Generic API data fetcher with proper error handling.

    Args:
        endpoint (str): API endpoint to call
        params (Dict[str, Any]): Query parameters

    Returns:
        str: JSON formatted response
    """
    try:
        response = requests.get(
            endpoint,
            params=params,
            timeout=10
        )
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)
    except requests.RequestException as e:
        return json.dumps({"error": f"API error: {str(e)}"})
```



### Data Processing Tools

Example of a tool that processes data:

```python
from typing import List, Dict
import pandas as pd

def process_market_data(prices: List[float], window: int = 14) -> str:
    """
    Calculate technical indicators from price data.

    Args:
        prices (List[float]): List of historical prices
        window (int): Rolling window size for calculations

    Returns:
        str: JSON formatted string with calculated indicators

    Example:
        >>> prices = [100, 101, 99, 102, 98, 103]
        >>> result = process_market_data(prices, window=3)
        >>> print(result)
        {"sma": 101.0, "volatility": 2.1}
    """
    try:
        df = pd.DataFrame({"price": prices})
        
        results: Dict[str, float] = {
            "sma": df["price"].rolling(window).mean().iloc[-1],
            "volatility": df["price"].rolling(window).std().iloc[-1]
        }
        
        return json.dumps(results, indent=2)
        
    except Exception as e:
        return json.dumps({"error": f"Processing error: {str(e)}"})
```

### Adding Tools to Your Agent

Once you've created your tools, add them to your agent like this:

```python
agent = Agent(
    agent_name="Your-Agent",
    agent_description="Description of your agent",
    system_prompt="System prompt for your agent",
    tools=[
        example_tool,
        get_api_data,
        rate_limited_api_call,
        process_market_data
    ]
)
```

## Tutorial Steps

1. First, install the latest version of Swarms:

```bash
pip3 install -U swarms
```

2. Set up your environment variables in a `.env` file:

```plaintext
OPENAI_API_KEY="your-api-key-here"
WORKSPACE_DIR="agent_workspace"
```

3. Create a new Python file and customize your agent with the following parameters:
   - `agent_name`: A unique identifier for your agent
   
   - `agent_description`: A detailed description of your agent's capabilities
   
   - `system_prompt`: The core instructions that define your agent's behavior
   
   - `model_name`: The GPT model to use
   
   - Additional configuration options for temperature and output format

4. Run the example code below:



```python
import json
import requests
from swarms import Agent
from typing import List
import time


def get_coin_price(coin_id: str, vs_currency: str) -> str:
    """
    Get the current price of a specific cryptocurrency.

    Args:
        coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum')
        vs_currency (str, optional): The target currency. Defaults to "usd".

    Returns:
        str: JSON formatted string containing the coin's current price and market data

    Raises:
        requests.RequestException: If the API request fails

    Example:
        >>> result = get_coin_price("bitcoin")
        >>> print(result)
        {"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}}
    """
    try:
        url = "https://api.coingecko.com/api/v3/simple/price"
        params = {
            "ids": coin_id,
            "vs_currencies": vs_currency,
            "include_market_cap": True,
            "include_24hr_vol": True,
            "include_24hr_change": True,
            "include_last_updated_at": True,
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()
        return json.dumps(data, indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {
                "error": f"Failed to fetch price for {coin_id}: {str(e)}"
            }
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_top_cryptocurrencies(limit: int, vs_currency: str) -> str:
    """
    Fetch the top cryptocurrencies by market capitalization.

    Args:
        limit (int, optional): Number of coins to retrieve (1-250). Defaults to 10.
        vs_currency (str, optional): The target currency. Defaults to "usd".

    Returns:
        str: JSON formatted string containing top cryptocurrencies with detailed market data

    Raises:
        requests.RequestException: If the API request fails
        ValueError: If limit is not between 1 and 250

    Example:
        >>> result = get_top_cryptocurrencies(5)
        >>> print(result)
        [{"id": "bitcoin", "name": "Bitcoin", "current_price": 45000, ...}]
    """
    try:
        if not 1 <= limit <= 250:
            raise ValueError("Limit must be between 1 and 250")

        url = "https://api.coingecko.com/api/v3/coins/markets"
        params = {
            "vs_currency": vs_currency,
            "order": "market_cap_desc",
            "per_page": limit,
            "page": 1,
            "sparkline": False,
            "price_change_percentage": "24h,7d",
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()

        # Simplify the data structure for better readability
        simplified_data = []
        for coin in data:
            simplified_data.append(
                {
                    "id": coin.get("id"),
                    "symbol": coin.get("symbol"),
                    "name": coin.get("name"),
                    "current_price": coin.get("current_price"),
                    "market_cap": coin.get("market_cap"),
                    "market_cap_rank": coin.get("market_cap_rank"),
                    "total_volume": coin.get("total_volume"),
                    "price_change_24h": coin.get(
                        "price_change_percentage_24h"
                    ),
                    "price_change_7d": coin.get(
                        "price_change_percentage_7d_in_currency"
                    ),
                    "last_updated": coin.get("last_updated"),
                }
            )

        return json.dumps(simplified_data, indent=2)

    except (requests.RequestException, ValueError) as e:
        return json.dumps(
            {
                "error": f"Failed to fetch top cryptocurrencies: {str(e)}"
            }
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def search_cryptocurrencies(query: str) -> str:
    """
    Search for cryptocurrencies by name or symbol.

    Args:
        query (str): The search term (coin name or symbol)

    Returns:
        str: JSON formatted string containing search results with coin details

    Raises:
        requests.RequestException: If the API request fails

    Example:
        >>> result = search_cryptocurrencies("ethereum")
        >>> print(result)
        {"coins": [{"id": "ethereum", "name": "Ethereum", "symbol": "eth", ...}]}
    """
    try:
        url = "https://api.coingecko.com/api/v3/search"
        params = {"query": query}

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()

        # Extract and format the results
        result = {
            "coins": data.get("coins", [])[
                :10
            ],  # Limit to top 10 results
            "query": query,
            "total_results": len(data.get("coins", [])),
        }

        return json.dumps(result, indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f'Failed to search for "{query}": {str(e)}'}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_jupiter_quote(
    input_mint: str,
    output_mint: str,
    amount: float,
    slippage: float = 0.5,
) -> str:
    """
    Get a quote for token swaps using Jupiter Protocol on Solana.

    Args:
        input_mint (str): Input token mint address
        output_mint (str): Output token mint address
        amount (float): Amount of input tokens to swap
        slippage (float, optional): Slippage tolerance percentage. Defaults to 0.5.

    Returns:
        str: JSON formatted string containing the swap quote details

    Example:
        >>> result = get_jupiter_quote("SOL_MINT_ADDRESS", "USDC_MINT_ADDRESS", 1.0)
        >>> print(result)
        {"inputAmount": "1000000000", "outputAmount": "22.5", "route": [...]}
    """
    try:
        url = "https://lite-api.jup.ag/swap/v1/quote"
        params = {
            "inputMint": input_mint,
            "outputMint": output_mint,
            "amount": str(int(amount * 1e9)),  # Convert to lamports
            "slippageBps": int(slippage * 100),
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to get Jupiter quote: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_htx_market_data(symbol: str) -> str:
    """
    Get market data for a trading pair from HTX exchange.

    Args:
        symbol (str): Trading pair symbol (e.g., 'btcusdt', 'ethusdt')

    Returns:
        str: JSON formatted string containing market data

    Example:
        >>> result = get_htx_market_data("btcusdt")
        >>> print(result)
        {"symbol": "btcusdt", "price": "45000", "volume": "1000000", ...}
    """
    try:
        url = "https://api.htx.com/market/detail/merged"
        params = {"symbol": symbol.lower()}

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to fetch HTX market data: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_token_historical_data(
    token_id: str, days: int = 30, vs_currency: str = "usd"
) -> str:
    """
    Get historical price and market data for a cryptocurrency.

    Args:
        token_id (str): The CoinGecko ID of the cryptocurrency
        days (int, optional): Number of days of historical data. Defaults to 30.
        vs_currency (str, optional): The target currency. Defaults to "usd".

    Returns:
        str: JSON formatted string containing historical price and market data

    Example:
        >>> result = get_token_historical_data("bitcoin", 7)
        >>> print(result)
        {"prices": [[timestamp, price], ...], "market_caps": [...], "volumes": [...]}
    """
    try:
        url = f"https://api.coingecko.com/api/v3/coins/{token_id}/market_chart"
        params = {
            "vs_currency": vs_currency,
            "days": days,
            "interval": "daily",
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to fetch historical data: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_defi_stats() -> str:
    """
    Get global DeFi statistics including TVL, trading volumes, and dominance.

    Returns:
        str: JSON formatted string containing global DeFi statistics

    Example:
        >>> result = get_defi_stats()
        >>> print(result)
        {"total_value_locked": 50000000000, "defi_dominance": 15.5, ...}
    """
    try:
        url = "https://api.coingecko.com/api/v3/global/decentralized_finance_defi"
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to fetch DeFi stats: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_jupiter_tokens() -> str:
    """
    Get list of tokens supported by Jupiter Protocol on Solana.

    Returns:
        str: JSON formatted string containing supported tokens

    Example:
        >>> result = get_jupiter_tokens()
        >>> print(result)
        {"tokens": [{"symbol": "SOL", "mint": "...", "decimals": 9}, ...]}
    """
    try:
        url = "https://lite-api.jup.ag/tokens/v1/mints/tradable"
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to fetch Jupiter tokens: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_htx_trading_pairs() -> str:
    """
    Get list of all trading pairs available on HTX exchange.

    Returns:
        str: JSON formatted string containing trading pairs information

    Example:
        >>> result = get_htx_trading_pairs()
        >>> print(result)
        {"symbols": [{"symbol": "btcusdt", "state": "online", "type": "spot"}, ...]}
    """
    try:
        url = "https://api.htx.com/v1/common/symbols"
        response = requests.get(url, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to fetch HTX trading pairs: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_market_sentiment(coin_ids: List[str]) -> str:
    """
    Get market sentiment data including social metrics and developer activity.

    Args:
        coin_ids (List[str]): List of CoinGecko coin IDs

    Returns:
        str: JSON formatted string containing market sentiment data

    Example:
        >>> result = get_market_sentiment(["bitcoin", "ethereum"])
        >>> print(result)
        {"bitcoin": {"sentiment_score": 75, "social_volume": 15000, ...}, ...}
    """
    try:
        sentiment_data = {}
        for coin_id in coin_ids:
            url = f"https://api.coingecko.com/api/v3/coins/{coin_id}"
            params = {
                "localization": False,
                "tickers": False,
                "market_data": False,
                "community_data": True,
                "developer_data": True,
            }

            response = requests.get(url, params=params, timeout=10)
            response.raise_for_status()
            data = response.json()

            sentiment_data[coin_id] = {
                "community_score": data.get("community_score"),
                "developer_score": data.get("developer_score"),
                "public_interest_score": data.get(
                    "public_interest_score"
                ),
                "community_data": data.get("community_data"),
                "developer_data": data.get("developer_data"),
            }

            # Rate limiting to avoid API restrictions
            time.sleep(0.6)

        return json.dumps(sentiment_data, indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {"error": f"Failed to fetch market sentiment: {str(e)}"}
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


# Initialize the agent with expanded tools
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Advanced financial advisor agent with comprehensive cryptocurrency market analysis capabilities across multiple platforms including Jupiter Protocol and HTX",
    system_prompt="You are an advanced financial advisor agent with access to real-time cryptocurrency data from multiple sources including CoinGecko, Jupiter Protocol, and HTX. You can help users analyze market trends, check prices, find trading opportunities, perform swaps, and get detailed market insights. Always provide accurate, up-to-date information and explain market data in an easy-to-understand way.",
    max_loops=1,
    max_tokens=4096,
    model_name="gpt-4o-mini",
    dynamic_temperature_enabled=True,
    output_type="all",
    tools=[
        get_coin_price,
        get_top_cryptocurrencies,
        search_cryptocurrencies,
        get_jupiter_quote,
        get_htx_market_data,
        get_token_historical_data,
        get_defi_stats,
        get_jupiter_tokens,
        get_htx_trading_pairs,
        get_market_sentiment,
    ],
    # Upload your tools to the tools parameter here!
)

# agent.run("Use defi stats to find the best defi project to invest in")
agent.run("Get the market sentiment for bitcoin")
# Automatically executes any number and combination of tools you have uploaded to the tools parameter!
```


--------------------------------------------------

# File: swarms/examples/agents_as_tools.md

# Agents as Tools Tutorial

This tutorial demonstrates how to create a powerful multi-agent system where agents can delegate tasks to specialized sub-agents. This pattern is particularly useful for complex tasks that require different types of expertise or capabilities.

## Overview

The Agents as Tools pattern allows you to:

- Create specialized agents with specific capabilities

- Have agents delegate tasks to other agents

- Chain multiple agents together for complex workflows

- Maintain separation of concerns between different agent roles

## Prerequisites

- Python 3.8 or higher

- Basic understanding of Python programming

- Familiarity with async/await concepts (optional)


## Installation

Install the swarms package using pip:

```bash
pip install -U swarms
```

## Basic Setup

1. First, set up your environment variables:

```python
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY=""
```

## Step-by-Step Guide

1. **Define Your Tools**
   
   - Create functions that will serve as tools for your agents
   
   - Add proper type hints and detailed docstrings
   
   - Include error handling and logging
   
   - Example:
   
   ```python
   def my_tool(param: str) -> str:
       """Detailed description of what the tool does.
       
       Args:
           param: Description of the parameter
           
       Returns:
           Description of the return value
       """
       # Tool implementation
       return result
   ```

2. **Create Specialized Agents**
   
   - Define agents with specific roles and capabilities
   
   - Configure each agent with appropriate settings
   
   - Assign relevant tools to each agent
   
   ```python
   specialized_agent = Agent(
       agent_name="Specialist",
       agent_description="Expert in specific domain",
       system_prompt="Detailed instructions for the agent",
       tools=[tool1, tool2]
   )
   ```

3. **Set Up the Director Agent**
   
   - Create a high-level agent that coordinates other agents
   
   - Give it access to specialized agents as tools
   
   - Define clear delegation rules
   
   ```python
   director = Agent(
       agent_name="Director",
       agent_description="Coordinates other agents",
       tools=[specialized_agent.run]
   )
   ```

4. **Execute Multi-Agent Workflows**
   
   - Start with the director agent
   
   - Let it delegate tasks as needed
   
   - Handle responses and chain results
   
   ```python
   result = director.run("Your high-level task description")
   ```



## Code

```python
import json
import requests
from swarms import Agent

def create_python_file(code: str, filename: str) -> str:
    """Create a Python file with the given code and execute it using Python 3.12.
    
    This function takes a string containing Python code, writes it to a file, and executes it
    using Python 3.12 via subprocess. The file will be created in the current working directory.
    If a file with the same name already exists, it will be overwritten.
    
    Args:
        code (str): The Python code to write to the file. This should be valid Python 3.12 code.
        filename (str): The name of the file to create and execute.
        
    Returns:
        str: A detailed message indicating the file was created and the execution result.
        
    Raises:
        IOError: If there are any issues writing to the file.
        subprocess.SubprocessError: If there are any issues executing the file.
        
    Example:
        >>> code = "print('Hello, World!')"
        >>> result = create_python_file(code, "test.py")
        >>> print(result)
        'Python file created successfully. Execution result: Hello, World!'
    """
    import subprocess
    import os
    import datetime
    
    # Get current timestamp for logging
    timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    
    # Write the code to file
    with open(filename, "w") as f:
        f.write(code)
    
    # Get file size and permissions
    file_stats = os.stat(filename)
    file_size = file_stats.st_size
    file_permissions = oct(file_stats.st_mode)[-3:]
    
    # Execute the file using Python 3.12 and capture output
    try:
        result = subprocess.run(
            ["python3.12", filename],
            capture_output=True,
            text=True,
            check=True
        )
        
        # Create detailed response
        response = f"""
File Creation Details:
----------------------
Timestamp: {timestamp}
Filename: {filename}
File Size: {file_size} bytes
File Permissions: {file_permissions}
Location: {os.path.abspath(filename)}

Execution Details:
-----------------
Exit Code: {result.returncode}
Execution Time: {result.returncode} seconds

Output:
-------
{result.stdout}

Error Output (if any):
--------------------
{result.stderr}
"""
        return response
    except subprocess.CalledProcessError as e:
        error_response = f"""
File Creation Details:
----------------------
Timestamp: {timestamp}
Filename: {filename}
File Size: {file_size} bytes
File Permissions: {file_permissions}
Location: {os.path.abspath(filename)}

Execution Error:
---------------
Exit Code: {e.returncode}
Error Message: {e.stderr}

Command Output:
-------------
{e.stdout}
"""
        return error_response
    
    
    



def update_python_file(code: str, filename: str) -> str:
    """Update an existing Python file with new code and execute it using Python 3.12.
    
    This function takes a string containing Python code and updates an existing Python file.
    If the file doesn't exist, it will be created. The file will be executed using Python 3.12.
    
    Args:
        code (str): The Python code to write to the file. This should be valid Python 3.12 code.
        filename (str): The name of the file to update and execute.
        
    Returns:
        str: A detailed message indicating the file was updated and the execution result.
        
    Raises:
        IOError: If there are any issues writing to the file.
        subprocess.SubprocessError: If there are any issues executing the file.
        
    Example:
        >>> code = "print('Updated code!')"
        >>> result = update_python_file(code, "my_script.py")
        >>> print(result)
        'Python file updated successfully. Execution result: Updated code!'
    """
    import subprocess
    import os
    import datetime
    
    # Get current timestamp for logging
    timestamp = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    
    # Check if file exists and get its stats
    file_exists = os.path.exists(filename)
    if file_exists:
        old_stats = os.stat(filename)
        old_size = old_stats.st_size
        old_permissions = oct(old_stats.st_mode)[-3:]
    
    # Write the code to file
    with open(filename, "w") as f:
        f.write(code)
    
    # Get new file stats
    new_stats = os.stat(filename)
    new_size = new_stats.st_size
    new_permissions = oct(new_stats.st_mode)[-3:]
    
    # Execute the file using Python 3.12 and capture output
    try:
        result = subprocess.run(
            ["python3.12", filename],
            capture_output=True,
            text=True,
            check=True
        )
        
        # Create detailed response
        response = f"""
File Update Details:
-------------------
Timestamp: {timestamp}
Filename: {filename}
Previous Status: {'Existed' if file_exists else 'Did not exist'}
Previous Size: {old_size if file_exists else 'N/A'} bytes
Previous Permissions: {old_permissions if file_exists else 'N/A'}
New Size: {new_size} bytes
New Permissions: {new_permissions}
Location: {os.path.abspath(filename)}

Execution Details:
-----------------
Exit Code: {result.returncode}
Execution Time: {result.returncode} seconds

Output:
-------
{result.stdout}

Error Output (if any):
--------------------
{result.stderr}
"""
        return response
    except subprocess.CalledProcessError as e:
        error_response = f"""
        File Update Details:
        -------------------
        Timestamp: {timestamp}
        Filename: {filename}
        Previous Status: {'Existed' if file_exists else 'Did not exist'}
        Previous Size: {old_size if file_exists else 'N/A'} bytes
        Previous Permissions: {old_permissions if file_exists else 'N/A'}
        New Size: {new_size} bytes
        New Permissions: {new_permissions}
        Location: {os.path.abspath(filename)}

        Execution Error:
        ---------------
        Exit Code: {e.returncode}
        Error Message: {e.stderr}

        Command Output:
        -------------
        {e.stdout}
        """
        return error_response
    
    
def run_quant_trading_agent(task: str) -> str:
    """Run a quantitative trading agent to analyze and execute trading strategies.

    This function initializes and runs a specialized quantitative trading agent that can:
    - Develop and backtest trading strategies
    - Analyze market data for alpha opportunities
    - Implement risk management frameworks
    - Optimize portfolio allocations
    - Conduct quantitative research
    - Monitor market microstructure
    - Evaluate trading system performance

    Args:
        task (str): The specific trading task or analysis to perform

    Returns:
        str: The agent's response or analysis results

    Example:
        >>> result = run_quant_trading_agent("Analyze SPY ETF for mean reversion opportunities")
        >>> print(result)
    """
    # Initialize the agent
    agent = Agent(
        agent_name="Quantitative-Trading-Agent",
        agent_description="Advanced quantitative trading and algorithmic analysis agent",
        system_prompt="""You are an expert quantitative trading agent with deep expertise in:
        - Algorithmic trading strategies and implementation
        - Statistical arbitrage and market making
        - Risk management and portfolio optimization
        - High-frequency trading systems
        - Market microstructure analysis
        - Quantitative research methodologies
        - Financial mathematics and stochastic processes
        - Machine learning applications in trading
        
        Your core responsibilities include:
        1. Developing and backtesting trading strategies
        2. Analyzing market data and identifying alpha opportunities
        3. Implementing risk management frameworks
        4. Optimizing portfolio allocations
        5. Conducting quantitative research
        6. Monitoring market microstructure
        7. Evaluating trading system performance
        
        You maintain strict adherence to:
        - Mathematical rigor in all analyses
        - Statistical significance in strategy development
        - Risk-adjusted return optimization
        - Market impact minimization
        - Regulatory compliance
        - Transaction cost analysis
        - Performance attribution
        
        You communicate in precise, technical terms while maintaining clarity for stakeholders.""",
        max_loops=2,
        model_name="claude-3-5-sonnet-20240620",
        tools=[create_python_file, update_python_file, backtest_summary],
    )

    out = agent.run(task)
    return out



def backtest_summary(report: str) -> str:
    """Generate a summary of a backtest report, but only if the backtest was profitable.
    
    This function should only be used when the backtest results show a positive return.
    Using this function for unprofitable backtests may lead to misleading conclusions.
    
    Args:
        report (str): The backtest report containing performance metrics
        
    Returns:
        str: A formatted summary of the backtest report
        
    Example:
        >>> result = backtest_summary("Total Return: +15.2%, Sharpe: 1.8")
        >>> print(result)
        'The backtest report is: Total Return: +15.2%, Sharpe: 1.8'
    """
    return f"The backtest report is: {report}"

def get_coin_price(coin_id: str, vs_currency: str) -> str:
    """
    Get the current price of a specific cryptocurrency.

    Args:
        coin_id (str): The CoinGecko ID of the cryptocurrency (e.g., 'bitcoin', 'ethereum')
        vs_currency (str, optional): The target currency. Defaults to "usd".

    Returns:
        str: JSON formatted string containing the coin's current price and market data

    Raises:
        requests.RequestException: If the API request fails

    Example:
        >>> result = get_coin_price("bitcoin")
        >>> print(result)
        {"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}}
    """
    try:
        url = "https://api.coingecko.com/api/v3/simple/price"
        params = {
            "ids": coin_id,
            "vs_currencies": vs_currency,
            "include_market_cap": True,
            "include_24hr_vol": True,
            "include_24hr_change": True,
            "include_last_updated_at": True,
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()
        return json.dumps(data, indent=2)

    except requests.RequestException as e:
        return json.dumps(
            {
                "error": f"Failed to fetch price for {coin_id}: {str(e)}"
            }
        )
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})



def run_crypto_quant_agent(task: str) -> str:
    """
    Run a crypto quantitative trading agent with specialized tools for cryptocurrency market analysis.

    This function initializes and runs a quantitative trading agent specifically designed for
    cryptocurrency markets. The agent is equipped with tools for price fetching and can perform
    various quantitative analyses including algorithmic trading strategy development, risk management,
    and market microstructure analysis.

    Args:
        task (str): The task or query to be processed by the crypto quant agent.

    Returns:
        str: The agent's response to the given task.

    Example:
        >>> response = run_crypto_quant_agent("Analyze the current market conditions for Bitcoin")
        >>> print(response)
        "Based on current market analysis..."
    """
    # Initialize the agent with expanded tools
    quant_agent = Agent(
        agent_name="Crypto-Quant-Agent",
        agent_description="Advanced quantitative trading agent specializing in cryptocurrency markets with algorithmic analysis capabilities",
        system_prompt="""You are an expert quantitative trading agent specializing in cryptocurrency markets. Your capabilities include:
        - Algorithmic trading strategy development and backtesting
        - Statistical arbitrage and market making for crypto assets
        - Risk management and portfolio optimization for digital assets
        - High-frequency trading system design for crypto markets
        - Market microstructure analysis of crypto exchanges
        - Quantitative research methodologies for crypto assets
        - Financial mathematics and stochastic processes
        - Machine learning applications in crypto trading
        
        You maintain strict adherence to:
        - Mathematical rigor in all analyses
        - Statistical significance in strategy development
        - Risk-adjusted return optimization
        - Market impact minimization
        - Regulatory compliance
        - Transaction cost analysis
        - Performance attribution
        
        You communicate in precise, technical terms while maintaining clarity for stakeholders.""",
        max_loops=1,
        max_tokens=4096,
        model_name="gpt-4.1-mini",
        dynamic_temperature_enabled=True,
        output_type="final",
        tools=[
            get_coin_price,
        ],
    )

    return quant_agent.run(task)

# Initialize the agent
agent = Agent(
    agent_name="Director-Agent",
    agent_description="Strategic director and project management agent",
    system_prompt="""You are an expert Director Agent with comprehensive capabilities in:
    - Strategic planning and decision making
    - Project management and coordination
    - Resource allocation and optimization
    - Team leadership and delegation
    - Risk assessment and mitigation
    - Stakeholder management
    - Process optimization
    - Quality assurance
    
    Your core responsibilities include:
    1. Developing and executing strategic initiatives
    2. Coordinating cross-functional projects
    3. Managing resource allocation
    4. Setting and tracking KPIs
    5. Ensuring project deliverables
    6. Risk management and mitigation
    7. Stakeholder communication
    
    You maintain strict adherence to:
    - Best practices in project management
    - Data-driven decision making
    - Clear communication protocols
    - Quality standards
    - Timeline management
    - Budget constraints
    - Regulatory compliance
    
    You communicate with clarity and authority while maintaining professionalism and ensuring all stakeholders are aligned.""",
    max_loops=1,
    model_name="gpt-4o-mini",
    output_type="final",
    interactive=False,
    tools=[run_quant_trading_agent],
)

out = agent.run("""
    Please call the quantitative trading agent to generate Python code for an Bitcoin backtest using the CoinGecko API.
    Provide a comprehensive description of the backtest methodology and trading strategy.
    Consider the API limitations of CoinGecko and utilize only free, open-source libraries that don't require API keys. Use the requests library to fetch the data. Create a specialized strategy for the backtest focused on the orderbook and other data for price action.
    The goal is to create a backtest that can predict the price action of the coin based on the orderbook and other data.
    Maximize the profit of the backtest. Please use the OKX price API for the orderbook and other data. Be very explicit in your implementation.
    Be very precise with the instructions you give to the agent and tell it to a 400 lines of good code.
""")
print(out)
```

## Best Practices

| Category | Best Practice | Description |
|----------|---------------|-------------|
| **Tool Design** | Single Purpose | Keep tools focused and single-purpose |
| | Clear Naming | Use clear, descriptive names |
| | Error Handling | Include comprehensive error handling |
| | Documentation | Add detailed documentation |
| **Agent Configuration** | Clear Role | Give each agent a clear, specific role |
| | System Prompts | Provide detailed system prompts |
| | Model Parameters | Configure appropriate model and parameters |
| | Resource Limits | Set reasonable limits on iterations and tokens |
| **Error Handling** | Multi-level | Implement proper error handling at each level |
| | Logging | Include logging for debugging |
| | API Management | Handle API rate limits and timeouts |
| | Fallbacks | Provide fallback options when possible |
| **Performance Optimization** | Async Operations | Use async operations where appropriate |
| | Caching | Implement caching when possible |
| | Token Usage | Monitor and optimize token usage |
| | Batch Processing | Consider batch operations for efficiency |


--------------------------------------------------

# File: swarms/examples/aggregate.md

# Aggregate Multi-Agent Responses

The `aggregate` function allows you to run multiple agents concurrently on the same task and then synthesize their responses using an intelligent aggregator agent. This is useful for getting diverse perspectives on a problem and then combining them into a comprehensive analysis.

## Installation

You can get started by first installing swarms with the following command, or [click here for more detailed installation instructions](https://docs.swarms.world/en/latest/swarms/install/install/):

```bash
pip3 install -U swarms
``` 

## Environment Variables

```txt
WORKSPACE_DIR=""
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
```

## How It Works

1. **Concurrent Execution**: All agents in the `workers` list run the same task simultaneously
2. **Response Collection**: Individual agent responses are collected into a conversation
3. **Intelligent Aggregation**: A specialized aggregator agent analyzes all responses and creates a comprehensive synthesis
4. **Formatted Output**: The final result is returned in the specified format

## Code Example

```python
from swarms.structs.agent import Agent
from swarms.structs.ma_blocks import aggregate


# Create specialized agents for different perspectives
agents = [
    Agent(
        agent_name="Sector-Financial-Analyst",
        agent_description="Senior financial analyst at BlackRock.",
        system_prompt="You are a financial analyst tasked with optimizing asset allocations for a $50B portfolio. Provide clear, quantitative recommendations for each sector.",
        max_loops=1,
        model_name="gpt-4o-mini",
        max_tokens=3000,
    ),
    Agent(
        agent_name="Sector-Risk-Analyst",
        agent_description="Expert risk management analyst.",
        system_prompt="You are a risk analyst responsible for advising on risk allocation within a $50B portfolio. Provide detailed insights on risk exposures for each sector.",
        max_loops=1,
        model_name="gpt-4o-mini",
        max_tokens=3000,
    ),
    Agent(
        agent_name="Tech-Sector-Analyst",
        agent_description="Technology sector analyst.",
        system_prompt="You are a tech sector analyst focused on capital and risk allocations. Provide data-backed insights for the tech sector.",
        max_loops=1,
        model_name="gpt-4o-mini",
        max_tokens=3000,
    ),
]

# Run the aggregate function
result = aggregate(
    workers=agents,
    task="What is the best sector to invest in?",
    type="all",  # Get complete conversation history
    aggregator_model_name="anthropic/claude-3-sonnet-20240229"
)

print(result)
```


--------------------------------------------------

# File: swarms/examples/azure.md

# Azure OpenAI Integration

This guide demonstrates how to integrate Azure OpenAI models with Swarms for enterprise-grade AI applications. Azure OpenAI provides access to OpenAI models through Microsoft's cloud infrastructure with enhanced security, compliance, and enterprise features.

## Prerequisites

- Azure subscription with OpenAI service enabled
- Azure OpenAI resource deployed
- Python 3.7+
- Swarms library
- LiteLLM library

## Installation

First, install the required dependencies:

```bash
pip install -U swarms
```

## Environment Setup

### 1. Azure OpenAI Configuration

Set up your Azure OpenAI environment variables in a `.env` file:

```bash
# Azure OpenAI Configuration
AZURE_API_KEY=your_azure_openai_api_key
AZURE_API_BASE=https://your-resource-name.openai.azure.com/
AZURE_API_VERSION=2024-02-15-preview

# Optional: Model deployment names (if different from model names)
AZURE_GPT4_DEPLOYMENT_NAME=gpt-4
AZURE_GPT35_DEPLOYMENT_NAME=gpt-35-turbo
```

### 2. Verify Available Models

Check what Azure models are available using LiteLLM:

```python
from litellm import model_list

# List all available Azure models
print("Available Azure models:")
for model in model_list:
    if "azure" in model:
        print(f"  - {model}")
```

Common Azure model names include:

- `azure/gpt-4.1`

- `azure/gpt-4o`

- `azure/gpt-4o-mini`



## Models Supported

```txt
azure_ai/grok-3
azure_ai/global/grok-3
azure_ai/global/grok-3-mini
azure_ai/grok-3-mini
azure_ai/deepseek-r1
azure_ai/deepseek-v3
azure_ai/deepseek-v3-0324
azure_ai/jamba-instruct
azure_ai/jais-30b-chat
azure_ai/mistral-nemo
azure_ai/mistral-medium-2505
azure_ai/mistral-large
azure_ai/mistral-small
azure_ai/mistral-small-2503
azure_ai/mistral-large-2407
azure_ai/mistral-large-latest
azure_ai/ministral-3b
azure_ai/Llama-3.2-11B-Vision-Instruct
azure_ai/Llama-3.3-70B-Instruct
azure_ai/Llama-4-Scout-17B-16E-Instruct
azure_ai/Llama-4-Maverick-17B-128E-Instruct-FP8
azure_ai/Llama-3.2-90B-Vision-Instruct
azure_ai/Meta-Llama-3-70B-Instruct
azure_ai/Meta-Llama-3.1-8B-Instruct
azure_ai/Meta-Llama-3.1-70B-Instruct
azure_ai/Meta-Llama-3.1-405B-Instruct
azure_ai/Phi-4-mini-instruct
azure_ai/Phi-4-multimodal-instruct
azure_ai/Phi-4
azure_ai/Phi-3.5-mini-instruct
azure_ai/Phi-3.5-vision-instruct
azure_ai/Phi-3.5-MoE-instruct
azure_ai/Phi-3-mini-4k-instruct
azure_ai/Phi-3-mini-128k-instruct
azure_ai/Phi-3-small-8k-instruct
azure_ai/Phi-3-small-128k-instruct
azure_ai/Phi-3-medium-4k-instruct
azure_ai/Phi-3-medium-128k-instruct
azure_ai/cohere-rerank-v3.5
azure_ai/cohere-rerank-v3-multilingual
azure_ai/cohere-rerank-v3-english
azure_ai/Cohere-embed-v3-english
azure_ai/Cohere-embed-v3-multilingual
azure_ai/embed-v-4-0
azure/gpt-4o-mini-tts
azure/computer-use-preview
azure/gpt-4o-audio-preview-2024-12-17
azure/gpt-4o-mini-audio-preview-2024-12-17
azure/gpt-4.1
azure/gpt-4.1-2025-04-14
azure/gpt-4.1-mini
azure/gpt-4.1-mini-2025-04-14
azure/gpt-4.1-nano
azure/gpt-4.1-nano-2025-04-14
azure/o3-pro
azure/o3-pro-2025-06-10
azure/o3
azure/o3-2025-04-16
azure/o3-deep-research
azure/o4-mini
azure/gpt-4o-mini-realtime-preview-2024-12-17
azure/eu/gpt-4o-mini-realtime-preview-2024-12-17
azure/us/gpt-4o-mini-realtime-preview-2024-12-17
azure/gpt-4o-realtime-preview-2024-12-17
azure/us/gpt-4o-realtime-preview-2024-12-17
azure/eu/gpt-4o-realtime-preview-2024-12-17
azure/gpt-4o-realtime-preview-2024-10-01
azure/us/gpt-4o-realtime-preview-2024-10-01
azure/eu/gpt-4o-realtime-preview-2024-10-01
azure/o4-mini-2025-04-16
azure/o3-mini-2025-01-31
azure/us/o3-mini-2025-01-31
azure/eu/o3-mini-2025-01-31
azure/tts-1
azure/tts-1-hd
azure/whisper-1
azure/gpt-4o-transcribe
azure/gpt-4o-mini-transcribe
azure/o3-mini
azure/o1-mini
azure/o1-mini-2024-09-12
azure/us/o1-mini-2024-09-12
azure/eu/o1-mini-2024-09-12
azure/o1
azure/o1-2024-12-17
azure/us/o1-2024-12-17
azure/eu/o1-2024-12-17
azure/codex-mini
azure/o1-preview
azure/o1-preview-2024-09-12
azure/us/o1-preview-2024-09-12
azure/eu/o1-preview-2024-09-12
azure/gpt-4.5-preview
azure/gpt-4o
azure/global/gpt-4o-2024-11-20
azure/gpt-4o-2024-08-06
azure/global/gpt-4o-2024-08-06
azure/gpt-4o-2024-11-20
azure/us/gpt-4o-2024-11-20
azure/eu/gpt-4o-2024-11-20
azure/gpt-4o-2024-05-13
azure/global-standard/gpt-4o-2024-08-06
azure/us/gpt-4o-2024-08-06
azure/eu/gpt-4o-2024-08-06
azure/global-standard/gpt-4o-2024-11-20
azure/global-standard/gpt-4o-mini
azure/gpt-4o-mini
azure/gpt-4o-mini-2024-07-18
azure/us/gpt-4o-mini-2024-07-18
azure/eu/gpt-4o-mini-2024-07-18
azure/gpt-4-turbo-2024-04-09
azure/gpt-4-0125-preview
azure/gpt-4-1106-preview
azure/gpt-4-0613
azure/gpt-4-32k-0613
azure/gpt-4-32k
azure/gpt-4
azure/gpt-4-turbo
azure/gpt-4-turbo-vision-preview
azure/gpt-35-turbo-16k-0613
azure/gpt-35-turbo-1106
azure/gpt-35-turbo-0613
azure/gpt-35-turbo-0301
azure/gpt-35-turbo-0125
azure/gpt-3.5-turbo-0125
azure/gpt-35-turbo-16k
azure/gpt-35-turbo
azure/gpt-3.5-turbo
azure/mistral-large-latest
azure/mistral-large-2402
azure/command-r-plus
azure/ada
azure/text-embedding-ada-002
azure/text-embedding-3-large
azure/text-embedding-3-small
azure/gpt-image-1
azure/low/1024-x-1024/gpt-image-1
azure/medium/1024-x-1024/gpt-image-1
azure/high/1024-x-1024/gpt-image-1
azure/low/1024-x-1536/gpt-image-1
azure/medium/1024-x-1536/gpt-image-1
azure/high/1024-x-1536/gpt-image-1
azure/low/1536-x-1024/gpt-image-1
azure/medium/1536-x-1024/gpt-image-1
azure/high/1536-x-1024/gpt-image-1
azure/standard/1024-x-1024/dall-e-3
azure/hd/1024-x-1024/dall-e-3
azure/standard/1024-x-1792/dall-e-3
azure/standard/1792-x-1024/dall-e-3
azure/hd/1024-x-1792/dall-e-3
azure/hd/1792-x-1024/dall-e-3
azure/standard/1024-x-1024/dall-e-2
azure/gpt-3.5-turbo-instruct-0914
azure/gpt-35-turbo-instruct
azure/gpt-35-turbo-instruct-0914
```


## Basic Usage

### Simple Agent with Azure Model

```python
import os
from dotenv import load_dotenv
from swarms import Agent

# Load environment variables
load_dotenv()

# Initialize agent with Azure model
agent = Agent(
    agent_name="Azure-Agent",
    agent_description="An agent powered by Azure OpenAI",
    system_prompt="You are a helpful assistant powered by Azure OpenAI.",
    model_name="azure/gpt-4o-mini",
    max_loops=1,
    max_tokens=1000,
    dynamic_temperature_enabled=True,
    output_type="str",
)

# Run the agent
response = agent.run("Explain quantum computing in simple terms.")
print(response)
```

## Advanced Configuration

### Quantitative Trading Agent Example

Here's a comprehensive example of a quantitative trading agent using Azure models:

```python
import os
from dotenv import load_dotenv
from swarms import Agent

# Load environment variables
load_dotenv()

# Initialize the quantitative trading agent
agent = Agent(
    agent_name="Quantitative-Trading-Agent",
    agent_description="Advanced quantitative trading and algorithmic analysis agent powered by Azure OpenAI",
    system_prompt="""You are an expert quantitative trading agent with deep expertise in:
    - Algorithmic trading strategies and implementation
    - Statistical arbitrage and market making
    - Risk management and portfolio optimization
    - High-frequency trading systems
    - Market microstructure analysis
    - Quantitative research methodologies
    - Financial mathematics and stochastic processes
    - Machine learning applications in trading
    
    Your core responsibilities include:
    1. Developing and backtesting trading strategies
    2. Analyzing market data and identifying alpha opportunities
    3. Implementing risk management frameworks
    4. Optimizing portfolio allocations
    5. Conducting quantitative research
    6. Monitoring market microstructure
    7. Evaluating trading system performance
    
    You maintain strict adherence to:
    - Mathematical rigor in all analyses
    - Statistical significance in strategy development
    - Risk-adjusted return optimization
    - Market impact minimization
    - Regulatory compliance
    - Transaction cost analysis
    - Performance attribution
    
    You communicate in precise, technical terms while maintaining clarity for stakeholders.""",
    model_name="azure/gpt-4o",
    dynamic_temperature_enabled=True,
    output_type="str-all-except-first",
    max_loops="auto",
    interactive=True,
    no_reasoning_prompt=True,
    streaming_on=True,
    max_tokens=4096,
)

# Example usage
response = agent.run(
    task="What are the best top 3 ETFs for gold coverage? Provide detailed analysis including expense ratios, liquidity, and tracking error."
)
print(response)
```


## Next Steps

- Check out [LiteLLM Azure integration](https://docs.litellm.ai/docs/providers/azure)

- Learn about [Swarms multi-agent architectures](../structs/index.md)

- Discover [advanced tool integrations](agent_with_tools.md)


--------------------------------------------------

# File: swarms/examples/basic_agent.md

# Basic Agent Example

This example demonstrates how to create and configure a sophisticated AI agent using the Swarms framework. In this tutorial, we'll build a Quantitative Trading Agent that can analyze financial markets and provide investment insights. The agent is powered by GPT models and can be customized for various financial analysis tasks.

## Prerequisites

- Python 3.7+

- OpenAI API key

- Swarms library

## Tutorial Steps

1. First, install the latest version of Swarms:

```bash
pip3 install -U swarms
```

2. Set up your environment variables in a `.env` file:

```plaintext
OPENAI_API_KEY="your-api-key-here"
WORKSPACE_DIR="agent_workspace"
```

3. Create a new Python file and customize your agent with the following parameters:
   - `agent_name`: A unique identifier for your agent
   
   - `agent_description`: A detailed description of your agent's capabilities
   
   - `system_prompt`: The core instructions that define your agent's behavior
   
   - `model_name`: The GPT model to use
   
   - Additional configuration options for temperature and output format

4. Run the example code below:


## Code

```python
import time
from swarms import Agent

# Initialize the agent
agent = Agent(
    agent_name="Quantitative-Trading-Agent",
    agent_description="Advanced quantitative trading and algorithmic analysis agent",
    system_prompt="""You are an expert quantitative trading agent with deep expertise in:
    - Algorithmic trading strategies and implementation
    - Statistical arbitrage and market making
    - Risk management and portfolio optimization
    - High-frequency trading systems
    - Market microstructure analysis
    - Quantitative research methodologies
    - Financial mathematics and stochastic processes
    - Machine learning applications in trading
    
    Your core responsibilities include:
    1. Developing and backtesting trading strategies
    2. Analyzing market data and identifying alpha opportunities
    3. Implementing risk management frameworks
    4. Optimizing portfolio allocations
    5. Conducting quantitative research
    6. Monitoring market microstructure
    7. Evaluating trading system performance
    
    You maintain strict adherence to:
    - Mathematical rigor in all analyses
    - Statistical significance in strategy development
    - Risk-adjusted return optimization
    - Market impact minimization
    - Regulatory compliance
    - Transaction cost analysis
    - Performance attribution
    
    You communicate in precise, technical terms while maintaining clarity for stakeholders.""",
    max_loops=1,
    model_name="gpt-4o-mini",
    dynamic_temperature_enabled=True,
    output_type="json",
    safety_prompt_on=True,
)

out = agent.run("What are the best top 3 etfs for gold coverage?")

time.sleep(10)
print(out)
```

## Example Output

The agent will return a JSON response containing recommendations for gold ETFs based on the query.

## Customization

You can modify the system prompt and agent parameters to create specialized agents for different use cases:

| Use Case | Description |
|----------|-------------|
| Market Analysis | Analyze market trends, patterns, and indicators to identify trading opportunities |
| Portfolio Management | Optimize asset allocation and rebalancing strategies |
| Risk Assessment | Evaluate and mitigate potential risks in trading strategies |
| Trading Strategy Development | Design and implement algorithmic trading strategies |

--------------------------------------------------

# File: swarms/examples/claude.md

# Agent with Anthropic/Claude

- Get their api keys and put it in the `.env`

- Select your model_name like `claude-3-sonnet-20240229` follows LiteLLM conventions


```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="claude-3-sonnet-20240229",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

--------------------------------------------------

# File: swarms/examples/cohere.md

# Agent with Cohere

- Add your `COHERE_API_KEY` in the `.env` file

- Select your model_name like `command-r` follows LiteLLM conventions


```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="command-r",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

--------------------------------------------------

# File: swarms/examples/concurrent_workflow.md

# ConcurrentWorkflow Examples

The ConcurrentWorkflow architecture enables parallel execution of multiple agents, allowing them to work simultaneously on different aspects of a task. This is particularly useful for complex tasks that can be broken down into independent subtasks.

## Prerequisites

- Python 3.7+
- OpenAI API key or other supported LLM provider keys
- Swarms library

## Installation

```bash
pip3 install -U swarms
```

## Environment Variables

```plaintext
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
```

## Basic Usage

### 1. Initialize Specialized Agents

```python
from swarms import Agent
from swarms.structs.concurrent_workflow import ConcurrentWorkflow

# Initialize market research agent
market_researcher = Agent(
    agent_name="Market-Researcher",
    system_prompt="""You are a market research specialist. Your tasks include:
    1. Analyzing market trends and patterns
    2. Identifying market opportunities and threats
    3. Evaluating competitor strategies
    4. Assessing customer needs and preferences
    5. Providing actionable market insights""",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    temperature=0.7,
)

# Initialize financial analyst agent
financial_analyst = Agent(
    agent_name="Financial-Analyst",
    system_prompt="""You are a financial analysis expert. Your responsibilities include:
    1. Analyzing financial statements
    2. Evaluating investment opportunities
    3. Assessing risk factors
    4. Providing financial forecasts
    5. Recommending financial strategies""",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    temperature=0.7,
)

# Initialize technical analyst agent
technical_analyst = Agent(
    agent_name="Technical-Analyst",
    system_prompt="""You are a technical analysis specialist. Your focus areas include:
    1. Analyzing price patterns and trends
    2. Evaluating technical indicators
    3. Identifying support and resistance levels
    4. Assessing market momentum
    5. Providing trading recommendations""",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    temperature=0.7,
)

# Create list of agents
agents = [market_researcher, financial_analyst, technical_analyst]

# Initialize the concurrent workflow with dashboard
router = ConcurrentWorkflow(
    name="market-analysis-router",
    agents=agents,
    max_loops=1,
    show_dashboard=True,  # Enable the real-time dashboard
)

# Run the workflow
result = router.run(
    "Analyze Tesla (TSLA) stock from market, financial, and technical perspectives"
)
```

## Features

### Real-time Dashboard

The ConcurrentWorkflow includes a powerful real-time dashboard feature that provides comprehensive monitoring and visualization of agent execution. Enable it by setting `show_dashboard=True` during workflow initialization.

#### Dashboard Features

- **Live Status Tracking**: Real-time updates showing each agent's execution status
- **Progress Visualization**: Visual indicators of agent progress and completion
- **Output Streaming**: Live display of agent outputs as they're generated
- **Error Monitoring**: Immediate visibility into any agent failures or errors
- **Performance Metrics**: Execution time and completion statistics
- **Clean Display**: Automatic cleanup and formatting for optimal viewing

#### Dashboard Status Values

- **"pending"**: Agent is queued but not yet started
- **"running"**: Agent is currently executing the task
- **"completed"**: Agent finished successfully with output
- **"error"**: Agent execution failed with error details

#### Dashboard Configuration

```python
# Enable dashboard with custom configuration
workflow = ConcurrentWorkflow(
    name="my-workflow",
    agents=agents,
    show_dashboard=True,  # Enable real-time monitoring
    output_type="dict",   # Configure output format
    auto_save=True,       # Auto-save conversation history
)
```

#### Dashboard Behavior

When `show_dashboard=True`:
- Individual agent print outputs are automatically disabled to prevent conflicts
- Dashboard updates every 100ms for smooth real-time streaming
- Initial dashboard shows all agents as "pending"
- Real-time updates show status changes and output previews
- Final dashboard displays complete results summary
- Automatic cleanup of dashboard resources after completion

### Concurrent Execution

- **ThreadPoolExecutor**: Uses 95% of available CPU cores for optimal performance
- **True Parallelism**: Agents execute simultaneously, not sequentially
- **Thread Safety**: Safe concurrent access to shared resources
- **Error Isolation**: Individual agent failures don't affect others
- **Resource Management**: Automatic thread lifecycle management

### Output Formatting Options

The workflow supports multiple output aggregation formats:

- **"dict-all-except-first"**: Dictionary with all agent outputs except the first (default)
- **"dict"**: Complete dictionary with all agent outputs keyed by agent name
- **"str"**: Concatenated string of all agent outputs
- **"list"**: List of individual agent outputs in completion order

```python
# Configure output format
workflow = ConcurrentWorkflow(
    agents=agents,
    output_type="dict",  # Get complete dictionary of results
    show_dashboard=True
)
```

### Advanced Features

#### Auto Prompt Engineering

Enable automatic prompt optimization for all agents:

```python
workflow = ConcurrentWorkflow(
    agents=agents,
    auto_generate_prompts=True,  # Enable automatic prompt engineering
    show_dashboard=True
)
```

#### Conversation History Management

Automatic conversation tracking and persistence:

```python
workflow = ConcurrentWorkflow(
    agents=agents,
    auto_save=True,                    # Auto-save conversation history
    metadata_output_path="results.json"  # Custom output file path
)
```

#### Multimodal Support

Support for image inputs across all agents:

```python
# Single image input
result = workflow.run(
    task="Analyze this chart",
    img="financial_chart.png"
)

# Multiple image inputs
result = workflow.run(
    task="Compare these charts",
    imgs=["chart1.png", "chart2.png", "chart3.png"]
)
```

## Best Practices

### 1. Dashboard Usage

- **Development & Debugging**: Use dashboard for real-time monitoring during development
- **Production**: Consider disabling dashboard for headless execution in production
- **Performance**: Dashboard adds minimal overhead but provides valuable insights
- **Error Handling**: Dashboard immediately shows which agents fail and why

### 2. Agent Configuration

- **Specialization**: Use specialized agents for specific tasks
- **Model Selection**: Choose appropriate models for each agent's role
- **Temperature**: Configure temperature based on task requirements
- **System Prompts**: Write clear, specific system prompts for each agent

### 3. Resource Management

- **CPU Utilization**: Workflow automatically uses 95% of available cores
- **Memory**: Monitor conversation history growth in long-running workflows
- **Rate Limits**: Handle API rate limits appropriately for your LLM provider
- **Error Recovery**: Implement fallback mechanisms for failed agents

### 4. Task Design

- **Independence**: Ensure tasks can be processed concurrently without dependencies
- **Granularity**: Break complex tasks into independent subtasks
- **Balance**: Distribute work evenly across agents for optimal performance

## Example Implementations

### Comprehensive Market Analysis

```python
from swarms import Agent
from swarms.structs.concurrent_workflow import ConcurrentWorkflow

# Initialize specialized agents
market_analyst = Agent(
    agent_name="Market-Analyst",
    system_prompt="""You are a market analysis specialist focusing on:
    1. Market trends and patterns
    2. Competitive analysis
    3. Market opportunities
    4. Industry dynamics
    5. Growth potential""",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    temperature=0.7,
)

financial_analyst = Agent(
    agent_name="Financial-Analyst",
    system_prompt="""You are a financial analysis expert specializing in:
    1. Financial statements analysis
    2. Ratio analysis
    3. Cash flow analysis
    4. Valuation metrics
    5. Risk assessment""",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    temperature=0.7,
)

risk_analyst = Agent(
    agent_name="Risk-Analyst",
    system_prompt="""You are a risk assessment specialist focusing on:
    1. Market risks
    2. Operational risks
    3. Financial risks
    4. Regulatory risks
    5. Strategic risks""",
    model_name="claude-3-sonnet-20240229",
    max_loops=1,
    temperature=0.7,
)

# Create the concurrent workflow with dashboard
workflow = ConcurrentWorkflow(
    name="comprehensive-analysis-workflow",
    agents=[market_analyst, financial_analyst, risk_analyst],
    max_loops=1,
    show_dashboard=True,  # Enable real-time monitoring
    output_type="dict",   # Get structured results
    auto_save=True,       # Save conversation history
)

try:
    result = workflow.run(
        """Provide a comprehensive analysis of Apple Inc. (AAPL) including:
        1. Market position and competitive analysis
        2. Financial performance and health
        3. Risk assessment and mitigation strategies"""
    )
    
    # Process and display results
    print("\nAnalysis Results:")
    print("=" * 50)
    for agent_name, output in result.items():
        print(f"\nAnalysis from {agent_name}:")
        print("-" * 40)
        print(output)
        
except Exception as e:
    print(f"Error during analysis: {str(e)}")
```

### Batch Processing with Dashboard

```python
# Process multiple tasks sequentially with concurrent agent execution
tasks = [
    "Analyze Q1 financial performance and market position",
    "Analyze Q2 financial performance and market position", 
    "Analyze Q3 financial performance and market position",
    "Analyze Q4 financial performance and market position"
]

# Optional: corresponding images for each task
charts = ["q1_chart.png", "q2_chart.png", "q3_chart.png", "q4_chart.png"]

# Batch processing with dashboard monitoring
results = workflow.batch_run(tasks, imgs=charts)

print(f"Completed {len(results)} quarterly analyses")
for i, result in enumerate(results):
    print(f"\nQ{i+1} Analysis Results:")
    print(result)
```

### Multimodal Analysis

```python
# Analyze financial charts with multiple specialized agents
workflow = ConcurrentWorkflow(
    agents=[technical_analyst, fundamental_analyst, sentiment_analyst],
    show_dashboard=True,
    output_type="dict"
)

# Analyze a single chart
result = workflow.run(
    task="Analyze this stock chart and provide trading insights",
    img="stock_chart.png"
)

# Analyze multiple charts
result = workflow.run(
    task="Compare these three charts and identify patterns",
    imgs=["chart1.png", "chart2.png", "chart3.png"]
)
```

### Error Handling and Monitoring

```python
# Workflow with comprehensive error handling
workflow = ConcurrentWorkflow(
    agents=agents,
    show_dashboard=True,  # Monitor execution in real-time
    auto_save=True,       # Preserve results even if errors occur
    output_type="dict"    # Get structured results for easier processing
)

try:
    result = workflow.run("Complex analysis task")
    
    # Check for errors in results
    for agent_name, output in result.items():
        if output.startswith("Error:"):
            print(f"Agent {agent_name} failed: {output}")
        else:
            print(f"Agent {agent_name} completed successfully")
            
except Exception as e:
    print(f"Workflow execution failed: {str(e)}")
    # Results may still be available for successful agents
```

## Performance Tips

1. **Agent Count**: Use 2+ agents to benefit from concurrent execution
2. **CPU Utilization**: Workflow automatically optimizes for available cores
3. **Dashboard Overhead**: Minimal performance impact for valuable monitoring
4. **Memory Management**: Clear conversation history for very large batch jobs
5. **Error Recovery**: Failed agents don't stop successful ones

## Use Cases

- **Multi-perspective Analysis**: Financial, legal, technical reviews
- **Consensus Building**: Voting systems and decision making
- **Parallel Processing**: Data analysis and batch operations
- **A/B Testing**: Different agent configurations and strategies
- **Redundancy**: Reliability improvements through multiple agents
- **Real-time Monitoring**: Development and debugging workflows

This guide demonstrates how to effectively use the ConcurrentWorkflow architecture with its advanced dashboard feature for parallel processing of complex tasks using multiple specialized agents. 

--------------------------------------------------

# File: swarms/examples/deepseek.md

# Agent with DeepSeek

- Add your `DEEPSEEK_API_KEY` in the `.env` file

- Select your model_name like `deepseek/deepseek-chat` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/deepseek)

- Execute your agent!


```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="deepseek/deepseek-chat",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

## R1 

This is a simple example of how to use the DeepSeek Reasoner model otherwise known as R1.

```python

import os
from swarms import Agent
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="deepseek/deepseek-reasoner",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

--------------------------------------------------

# File: swarms/examples/groq.md

# Agent with Groq

- Add your `GROQ_API_KEY`

- Initiate your agent

- Run your agent

```python
import os

from swarms import Agent

company = "NVDA"


# Initialize the Managing Director agent
managing_director = Agent(
    agent_name="Managing-Director",
    system_prompt=f"""
    As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions. 
    Your responsibilities include:
    1. Setting the overall strategy and direction for the analysis
    2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation
    3. Reviewing the findings and recommendations from each team member
    4. Making the final decision on whether to proceed with the acquisition
    
    For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment.
    """,
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="managing-director.json",
)
```

--------------------------------------------------

# File: swarms/examples/groupchat_example.md

# GroupChat Example

!!! abstract "Overview"
    Learn how to create and configure a group chat with multiple AI agents using the Swarms framework. This example demonstrates how to set up agents for expense analysis and budget advising.

## Prerequisites

!!! info "Before You Begin"
    Make sure you have:
    - Python 3.7+ installed
    - A valid API key for your model provider
    - The Swarms package installed

## Installation

```bash
pip install swarms
```

## Environment Setup

!!! tip "API Key Configuration"
    Set your API key in the `.env` file:
    ```bash
    OPENAI_API_KEY="your-api-key-here"
    ```

## Code Implementation

### Import Required Modules

```python
from dotenv import load_dotenv
import os
from swarms import Agent, GroupChat
```

### Configure Agents

!!! example "Agent Configuration"
    Here's how to set up your agents with specific roles:

    ```python
    # Expense Analysis Agent
    agent1 = Agent(
        agent_name="Expense-Analysis-Agent",
        description="You are an accounting agent specializing in analyzing potential expenses.",
        model_name="gpt-4o-mini",
        max_loops=1,
        autosave=False,
        dashboard=False,
        verbose=True,
        dynamic_temperature_enabled=True,
        user_name="swarms_corp",
        retry_attempts=1,
        context_length=200000,
        output_type="string",
        streaming_on=False,
        max_tokens=15000,
    )

    # Budget Adviser Agent
    agent2 = Agent(
        agent_name="Budget-Adviser-Agent",
        description="You are a budget adviser who provides insights on managing and optimizing expenses.",
        model_name="gpt-4o-mini",
        max_loops=1,
        autosave=False,
        dashboard=False,
        verbose=True,
        dynamic_temperature_enabled=True,
        user_name="swarms_corp",
        retry_attempts=1,
        context_length=200000,
        output_type="string",
        streaming_on=False,
        max_tokens=15000,
    )
    ```

### Initialize GroupChat

!!! example "GroupChat Setup"
    Configure the GroupChat with your agents:

    ```python
    agents = [agent1, agent2]

    chat = GroupChat(
        name="Expense Advisory",
        description="Accounting group focused on discussing potential expenses",
        agents=agents,
        max_loops=1,
        output_type="all",
    )
    ```

### Run the Chat

!!! example "Execute the Chat"
    Start the conversation between agents:

    ```python
    history = chat.run(
        "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list."
    )
    ```

## Complete Example

!!! success "Full Implementation"
    Here's the complete code combined:

    ```python
    from dotenv import load_dotenv
    import os
    from swarms import Agent, GroupChat

    if __name__ == "__main__":
        # Load environment variables
        load_dotenv()
        api_key = os.getenv("OPENAI_API_KEY")

        # Configure agents
        agent1 = Agent(
            agent_name="Expense-Analysis-Agent",
            description="You are an accounting agent specializing in analyzing potential expenses.",
            model_name="gpt-4o-mini",
            max_loops=1,
            autosave=False,
            dashboard=False,
            verbose=True,
            dynamic_temperature_enabled=True,
            user_name="swarms_corp",
            retry_attempts=1,
            context_length=200000,
            output_type="string",
            streaming_on=False,
            max_tokens=15000,
        )

        agent2 = Agent(
            agent_name="Budget-Adviser-Agent",
            description="You are a budget adviser who provides insights on managing and optimizing expenses.",
            model_name="gpt-4o-mini",
            max_loops=1,
            autosave=False,
            dashboard=False,
            verbose=True,
            dynamic_temperature_enabled=True,
            user_name="swarms_corp",
            retry_attempts=1,
            context_length=200000,
            output_type="string",
            streaming_on=False,
            max_tokens=15000,
        )

        # Initialize GroupChat
        agents = [agent1, agent2]
        chat = GroupChat(
            name="Expense Advisory",
            description="Accounting group focused on discussing potential expenses",
            agents=agents,
            max_loops=1,
            output_type="all",
        )

        # Run the chat
        history = chat.run(
            "What potential expenses should we consider for the upcoming quarter? Please collaborate to outline a comprehensive list."
        )
    ```

## Configuration Options

!!! info "Key Parameters"
    | Parameter | Description | Default |
    |-----------|-------------|---------|
    | `max_loops` | Maximum number of conversation loops | 1 |
    | `autosave` | Enable automatic saving of chat history | False |
    | `dashboard` | Enable dashboard visualization | False |
    | `verbose` | Enable detailed logging | True |
    | `dynamic_temperature_enabled` | Enable dynamic temperature adjustment | True |
    | `retry_attempts` | Number of retry attempts for failed operations | 1 |
    | `context_length` | Maximum context length for the model | 200000 |
    | `max_tokens` | Maximum tokens for model output | 15000 |

## Next Steps

!!! tip "What to Try Next"
    1. Experiment with different agent roles and descriptions
    2. Adjust the `max_loops` parameter to allow for longer conversations
    3. Enable the dashboard to visualize agent interactions
    4. Try different model configurations and parameters

## Troubleshooting

!!! warning "Common Issues"
    - Ensure your API key is correctly set in the `.env` file
    - Check that all required dependencies are installed
    - Verify that your model provider's API is accessible
    - Monitor the `verbose` output for detailed error messages

## Additional Resources

- [Swarms Documentation](https://docs.swarms.world)
- [API Reference](https://docs.swarms.world/api)
- [Examples Gallery](https://docs.swarms.world/examples)

--------------------------------------------------

# File: swarms/examples/hhcs_examples.md


#  Hybrid Hierarchical-Cluster Swarm (HHCS) Example

1. Get your GROQ api key
2. Create a `.env` file in the root directory and add your API key: `GROQ_API_KEY`
3. Write the following code:
4. Run the file

```python

from swarms import Agent, SwarmRouter, HybridHierarchicalClusterSwarm


# Core Legal Agent Definitions with short, simple prompts
litigation_agent = Agent(
    agent_name="Litigator",
    system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

corporate_agent = Agent(
    agent_name="Corporate-Attorney",
    system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

ip_agent = Agent(
    agent_name="IP-Attorney",
    system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

employment_agent = Agent(
    agent_name="Employment-Attorney",
    system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

paralegal_agent = Agent(
    agent_name="Paralegal",
    system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

doc_review_agent = Agent(
    agent_name="Document-Reviewer",
    system_prompt="You examine documents. Extract key information and identify relevant content.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

# Practice Area Swarm Routers
litigation_swarm = SwarmRouter(
    name="litigation-practice",
    description="Handle all aspects of litigation",
    agents=[litigation_agent, paralegal_agent, doc_review_agent],
    swarm_type="SequentialWorkflow",
)

corporate_swarm = SwarmRouter(
    name="corporate-practice",
    description="Handle business and corporate legal matters",
    agents=[corporate_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

ip_swarm = SwarmRouter(
    name="ip-practice",
    description="Handle intellectual property matters",
    agents=[ip_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

employment_swarm = SwarmRouter(
    name="employment-practice",
    description="Handle employment and labor law matters",
    agents=[employment_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

# Cross-functional Swarm Router
m_and_a_swarm = SwarmRouter(
    name="mergers-acquisitions",
    description="Handle mergers and acquisitions",
    agents=[
        corporate_agent,
        ip_agent,
        employment_agent,
        doc_review_agent,
    ],
    swarm_type="ConcurrentWorkflow",
)

dispute_swarm = SwarmRouter(
    name="dispute-resolution",
    description="Handle complex disputes requiring multiple specialties",
    agents=[litigation_agent, corporate_agent, doc_review_agent],
    swarm_type="ConcurrentWorkflow",
)


hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm(
    name="hybrid-hiearchical-swarm",
    description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.",
    swarms=[
        litigation_swarm,
        corporate_swarm,
        ip_swarm,
        employment_swarm,
        m_and_a_swarm,
        dispute_swarm,
    ],
    max_loops=1,
    router_agent_model_name="gpt-4o-mini",
)


if __name__ == "__main__":
    hybrid_hiearchical_swarm.run(
        "What is the best way to file for a patent? for ai technology "
    )

```

--------------------------------------------------

# File: swarms/examples/hierarchical_swarm_example.md

# Hierarchical Swarm Examples

This page provides simple, practical examples of how to use the `HierarchicalSwarm` for various real-world scenarios.

## Basic Example: Financial Analysis

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized financial analysis agents
market_research_agent = Agent(
    agent_name="Market-Research-Specialist",
    agent_description="Expert in market research, trend analysis, and competitive intelligence",
    system_prompt="""You are a senior market research specialist with expertise in:
    - Market trend analysis and forecasting
    - Competitive landscape assessment
    - Consumer behavior analysis
    - Industry report generation
    - Market opportunity identification
    - Risk assessment and mitigation strategies""",
    model_name="gpt-4o",
)

financial_analyst_agent = Agent(
    agent_name="Financial-Analysis-Expert",
    agent_description="Specialist in financial statement analysis, valuation, and investment research",
    system_prompt="""You are a senior financial analyst with deep expertise in:
    - Financial statement analysis (income statement, balance sheet, cash flow)
    - Valuation methodologies (DCF, comparable company analysis, precedent transactions)
    - Investment research and due diligence
    - Financial modeling and forecasting
    - Risk assessment and portfolio analysis
    - ESG (Environmental, Social, Governance) analysis""",
    model_name="gpt-4o",
)

# Initialize the hierarchical swarm
financial_analysis_swarm = HierarchicalSwarm(
    name="Financial-Analysis-Hierarchical-Swarm",
    description="A hierarchical swarm for comprehensive financial analysis with specialized agents",
    agents=[market_research_agent, financial_analyst_agent],
    max_loops=2,
    verbose=True,
)

# Execute financial analysis
task = "Conduct a comprehensive analysis of Tesla (TSLA) stock including market position, financial health, and investment potential"
result = financial_analysis_swarm.run(task=task)
print(result)
```

## Development Team Example

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized development agents
frontend_developer_agent = Agent(
    agent_name="Frontend-Developer",
    agent_description="Senior frontend developer expert in modern web technologies and user experience",
    system_prompt="""You are a senior frontend developer with expertise in:
    - Modern JavaScript frameworks (React, Vue, Angular)
    - TypeScript and modern ES6+ features
    - CSS frameworks and responsive design
    - State management (Redux, Zustand, Context API)
    - Web performance optimization
    - Accessibility (WCAG) and SEO best practices""",
    model_name="gpt-4o",
)

backend_developer_agent = Agent(
    agent_name="Backend-Developer",
    agent_description="Senior backend developer specializing in server-side development and API design",
    system_prompt="""You are a senior backend developer with expertise in:
    - Server-side programming languages (Python, Node.js, Java, Go)
    - Web frameworks (Django, Flask, Express, Spring Boot)
    - Database design and optimization (SQL, NoSQL)
    - API design and REST/GraphQL implementation
    - Authentication and authorization systems
    - Microservices architecture and containerization""",
    model_name="gpt-4o",
)

# Initialize the development swarm
development_department_swarm = HierarchicalSwarm(
    name="Autonomous-Development-Department",
    description="A fully autonomous development department with specialized agents",
    agents=[frontend_developer_agent, backend_developer_agent],
    max_loops=3,
    verbose=True,
)

# Execute development project
task = "Create a simple web app that allows users to upload a file and then download it. The app should be built with React and Node.js."
result = development_department_swarm.run(task=task)
print(result)
```

## Single Step Execution

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create analysis agents
market_agent = Agent(
    agent_name="Market-Analyst",
    agent_description="Expert in market analysis and trends",
    model_name="gpt-4o",
)

technical_agent = Agent(
    agent_name="Technical-Analyst",
    agent_description="Specialist in technical analysis and patterns",
    model_name="gpt-4o",
)

# Initialize the swarm
swarm = HierarchicalSwarm(
    name="Analysis-Swarm",
    description="A hierarchical swarm for comprehensive analysis",
    agents=[market_agent, technical_agent],
    max_loops=1,
    verbose=True,
)

# Execute a single step
task = "Analyze the current market trends for electric vehicles"
feedback = swarm.step(task=task)
print("Director Feedback:", feedback)
```

## Batch Processing

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create analysis agents
market_agent = Agent(
    agent_name="Market-Analyst",
    agent_description="Expert in market analysis and trends",
    model_name="gpt-4o",
)

technical_agent = Agent(
    agent_name="Technical-Analyst",
    agent_description="Specialist in technical analysis and patterns",
    model_name="gpt-4o",
)

# Initialize the swarm
swarm = HierarchicalSwarm(
    name="Analysis-Swarm",
    description="A hierarchical swarm for comprehensive analysis",
    agents=[market_agent, technical_agent],
    max_loops=2,
    verbose=True,
)

# Execute multiple tasks
tasks = [
    "Analyze Apple (AAPL) stock performance",
    "Evaluate Microsoft (MSFT) market position",
    "Assess Google (GOOGL) competitive landscape"
]

results = swarm.batched_run(tasks=tasks)
for i, result in enumerate(results):
    print(f"Task {i+1} Result:", result)
```

## Research Team Example

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized research agents
research_manager = Agent(
    agent_name="Research-Manager",
    agent_description="Manages research operations and coordinates research tasks",
    system_prompt="You are a research manager responsible for overseeing research projects and coordinating research efforts.",
    model_name="gpt-4o",
)

data_analyst = Agent(
    agent_name="Data-Analyst",
    agent_description="Analyzes data and generates insights",
    system_prompt="You are a data analyst specializing in processing and analyzing data to extract meaningful insights.",
    model_name="gpt-4o",
)

research_assistant = Agent(
    agent_name="Research-Assistant",
    agent_description="Assists with research tasks and data collection",
    system_prompt="You are a research assistant who helps gather information and support research activities.",
    model_name="gpt-4o",
)

# Initialize the research swarm
research_swarm = HierarchicalSwarm(
    name="Research-Team-Swarm",
    description="A hierarchical swarm for comprehensive research projects",
    agents=[research_manager, data_analyst, research_assistant],
    max_loops=2,
    verbose=True,
)

# Execute research project
task = "Conduct a comprehensive market analysis for a new AI-powered productivity tool"
result = research_swarm.run(task=task)
print(result)
```

## Key Takeaways

1. **Agent Specialization**: Create agents with specific, well-defined expertise areas
2. **Clear Task Descriptions**: Provide detailed, actionable task descriptions
3. **Appropriate Loop Count**: Set `max_loops` based on task complexity (1-3 for most tasks)
4. **Verbose Logging**: Enable verbose mode during development for debugging
5. **Context Preservation**: The swarm maintains full conversation history automatically

For more detailed information about the `HierarchicalSwarm` API and advanced usage patterns, see the [main documentation](hierarchical_swarm.md). 

--------------------------------------------------

# File: swarms/examples/igc_example.md

## Interactive Groupchat Examples

The Interactive GroupChat is a powerful multi-agent architecture that enables dynamic collaboration between multiple AI agents. This architecture allows agents to communicate with each other, respond to mentions using `@agent_name` syntax, and work together to solve complex tasks through structured conversation flows.

### Architecture Description

The Interactive GroupChat implements a **collaborative swarm architecture** where multiple specialized agents work together in a coordinated manner. Key features include:

- **Mention-based Communication**: Agents can be directed to specific tasks using `@agent_name` syntax
- **Flexible Speaker Functions**: Multiple speaking order strategies (round robin, random, priority-based)
- **Enhanced Collaboration**: Agents build upon each other's responses and avoid redundancy
- **Interactive Sessions**: Support for both automated and interactive conversation modes
- **Context Awareness**: Agents maintain conversation history and context

For comprehensive documentation on Interactive GroupChat, visit: [Interactive GroupChat Documentation](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)

### Step-by-Step Showcase

* **Agent Creation**: Define specialized agents with unique expertise and system prompts
* **GroupChat Initialization**: Create the InteractiveGroupChat structure with desired speaker function
* **Task Definition**: Formulate tasks using `@agent_name` mentions to direct specific agents
* **Execution**: Run the group chat to generate collaborative responses
* **Response Processing**: Handle the coordinated output from multiple agents
* **Iteration**: Chain multiple tasks for complex workflows

## Installation

Install the swarms package using pip:

```bash
pip install -U swarms
```

## Basic Setup

1. First, set up your environment variables:

```python
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
```

## Code

```python
"""
InteractiveGroupChat Speaker Function Examples

This example demonstrates how to use different speaker functions in the InteractiveGroupChat:
- Round Robin: Agents speak in a fixed order, cycling through the list
- Random: Agents speak in random order
- Priority: Agents speak based on priority weights
- Custom: User-defined speaker functions

The example also shows how agents can mention each other using @agent_name syntax.
"""

from swarms import Agent
from swarms.structs.interactive_groupchat import (
    InteractiveGroupChat,
    random_speaker,
)


def create_example_agents():
    """Create example agents for demonstration."""

    # Create agents with different expertise
    analyst = Agent(
        agent_name="analyst",
        system_prompt="You are a data analyst. You excel at analyzing data, creating charts, and providing insights.",
        model_name="gpt-4.1",
        streaming_on=True,
        print_on=True,
    )

    researcher = Agent(
        agent_name="researcher",
        system_prompt="You are a research specialist. You are great at gathering information, fact-checking, and providing detailed research.",
        model_name="gpt-4.1",
        streaming_on=True,
        print_on=True,
    )

    writer = Agent(
        agent_name="writer",
        system_prompt="You are a content writer. You excel at writing clear, engaging content and summarizing information.",
        model_name="gpt-4.1",
        streaming_on=True,
        print_on=True,
    )

    return [analyst, researcher, writer]


def example_random():
    agents = create_example_agents()

    # Create group chat with random speaker function
    group_chat = InteractiveGroupChat(
        name="Random Team",
        description="A team that speaks in random order",
        agents=agents,
        speaker_function=random_speaker,
        interactive=False,
    )

    # Test the random behavior
    task = "Let's create a marketing strategy. @analyst @researcher @writer please contribute."

    response = group_chat.run(task)
    print(f"Response:\n{response}\n")


if __name__ == "__main__":
    # example_round_robin()
    example_random()
```



## Connect With Us

Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights!

| Platform | Description | Link |
|----------|-------------|------|
| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) |
| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) |
| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/EamjgSaEQf) |
| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) |
| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) |
| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) |
| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |


--------------------------------------------------

# File: swarms/examples/interactive_groupchat_example.md

# Interactive GroupChat Example 

This is an example of the InteractiveGroupChat module in swarms. [Click here for full documentation](https://docs.swarms.world/en/latest/swarms/structs/interactive_groupchat/)

## Installation

You can get started by first installing swarms with the following command, or [click here for more detailed installation instructions](https://docs.swarms.world/en/latest/swarms/install/install/):

```bash
pip3 install -U swarms
``` 

## Environment Variables

```txt
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
```

# Code


## Interactive Session in Terminal

```python
from swarms import Agent
from swarms.structs.interactive_groupchat import InteractiveGroupChat


if __name__ == "__main__":
    # Initialize agents
    financial_advisor = Agent(
        agent_name="FinancialAdvisor",
        system_prompt="You are a financial advisor specializing in investment strategies and portfolio management.",
        random_models_on=True,
        output_type="final",
    )

    tax_expert = Agent(
        agent_name="TaxExpert",
        system_prompt="You are a tax expert who provides guidance on tax optimization and compliance.",
        random_models_on=True,
        output_type="final",
    )

    investment_analyst = Agent(
        agent_name="InvestmentAnalyst",
        system_prompt="You are an investment analyst focusing on market trends and investment opportunities.",
        random_models_on=True,
        output_type="final",
    )

    # Create a list of agents including both Agent instances and callables
    agents = [
        financial_advisor,
        tax_expert,
        investment_analyst,
    ]

    # Initialize another chat instance in interactive mode
    interactive_chat = InteractiveGroupChat(
        name="Interactive Financial Advisory Team",
        description="An interactive team of financial experts providing comprehensive financial advice",
        agents=agents,
        max_loops=1,
        output_type="all",
        interactive=True,
    )

    try:
        # Start the interactive session
        print("\nStarting interactive session...")
        # interactive_chat.run("What is the best methodology to accumulate gold and silver commodities, and what is the best long-term strategy to accumulate them?")
        interactive_chat.start_interactive_session()
    except Exception as e:
        print(f"An error occurred in interactive mode: {e}")
```


## Run Method // Manual Method


```python
from swarms import Agent
from swarms.structs.interactive_groupchat import InteractiveGroupChat


if __name__ == "__main__":
    # Initialize agents
    financial_advisor = Agent(
        agent_name="FinancialAdvisor",
        system_prompt="You are a financial advisor specializing in investment strategies and portfolio management.",
        random_models_on=True,
        output_type="final",
    )

    tax_expert = Agent(
        agent_name="TaxExpert",
        system_prompt="You are a tax expert who provides guidance on tax optimization and compliance.",
        random_models_on=True,
        output_type="final",
    )

    investment_analyst = Agent(
        agent_name="InvestmentAnalyst",
        system_prompt="You are an investment analyst focusing on market trends and investment opportunities.",
        random_models_on=True,
        output_type="final",
    )

    # Create a list of agents including both Agent instances and callables
    agents = [
        financial_advisor,
        tax_expert,
        investment_analyst,
    ]

    # Initialize another chat instance in interactive mode
    interactive_chat = InteractiveGroupChat(
        name="Interactive Financial Advisory Team",
        description="An interactive team of financial experts providing comprehensive financial advice",
        agents=agents,
        max_loops=1,
        output_type="all",
        interactive=False,
    )

    try:
        # Start the interactive session
        print("\nStarting interactive session...")
        # interactive_chat.run("What is the best methodology to accumulate gold and silver commodities, and what is the best long-term strategy to accumulate them?")
        interactive_chat.run('@TaxExpert how can I understand tax tactics for crypto payroll in solana?')
    except Exception as e:
        print(f"An error occurred in interactive mode: {e}")
```

--------------------------------------------------

# File: swarms/examples/llama4.md

# Llama4 Model Integration

!!! info "Prerequisites"
    - Python 3.8 or higher
    - `swarms` library installed
    - Access to Llama4 model
    - Valid environment variables configured

## Quick Start

Here's a simple example of integrating Llama4 model for crypto risk analysis:

```python
from dotenv import load_dotenv
from swarms import Agent
from swarms.utils.vllm_wrapper import VLLM

load_dotenv()
model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E")
```

## Available Models

| Model Name | Description | Type |
|------------|-------------|------|
| meta-llama/Llama-4-Maverick-17B-128E | Base model with 128 experts | Base |
| meta-llama/Llama-4-Maverick-17B-128E-Instruct | Instruction-tuned version with 128 experts | Instruct |
| meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8 | FP8 quantized instruction model | Instruct (Optimized) |
| meta-llama/Llama-4-Scout-17B-16E | Base model with 16 experts | Base |
| meta-llama/Llama-4-Scout-17B-16E-Instruct | Instruction-tuned version with 16 experts | Instruct |

!!! tip "Model Selection"
    - Choose Instruct models for better performance on instruction-following tasks
    - FP8 models offer better memory efficiency with minimal performance impact
    - Scout models (16E) are lighter but still powerful
    - Maverick models (128E) offer maximum performance but require more resources

## Detailed Implementation

### 1. Define Custom System Prompt

```python
CRYPTO_RISK_ANALYSIS_PROMPT = """
You are a cryptocurrency risk analysis expert. Your role is to:

1. Analyze market risks:
   - Volatility assessment
   - Market sentiment analysis
   - Trading volume patterns
   - Price trend evaluation

2. Evaluate technical risks:
   - Network security
   - Protocol vulnerabilities
   - Smart contract risks
   - Technical scalability

3. Consider regulatory risks:
   - Current regulations
   - Potential regulatory changes
   - Compliance requirements
   - Geographic restrictions

4. Assess fundamental risks:
   - Team background
   - Project development status
   - Competition analysis
   - Use case viability

Provide detailed, balanced analysis with both risks and potential mitigations.
Base your analysis on established crypto market principles and current market conditions.
"""
```

### 2. Initialize Agent

```python
agent = Agent(
    agent_name="Crypto-Risk-Analysis-Agent",
    agent_description="Agent for analyzing risks in cryptocurrency investments",
    system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT,
    max_loops=1,
    llm=model,
)
```

## Full Code

```python
from dotenv import load_dotenv

from swarms import Agent
from swarms.utils.vllm_wrapper import VLLM

load_dotenv()

# Define custom system prompt for crypto risk analysis
CRYPTO_RISK_ANALYSIS_PROMPT = """
You are a cryptocurrency risk analysis expert. Your role is to:

1. Analyze market risks:
   - Volatility assessment
   - Market sentiment analysis
   - Trading volume patterns
   - Price trend evaluation

2. Evaluate technical risks:
   - Network security
   - Protocol vulnerabilities
   - Smart contract risks
   - Technical scalability

3. Consider regulatory risks:
   - Current regulations
   - Potential regulatory changes
   - Compliance requirements
   - Geographic restrictions

4. Assess fundamental risks:
   - Team background
   - Project development status
   - Competition analysis
   - Use case viability

Provide detailed, balanced analysis with both risks and potential mitigations.
Base your analysis on established crypto market principles and current market conditions.
"""

model = VLLM(model_name="meta-llama/Llama-4-Maverick-17B-128E")

# Initialize the agent with custom prompt
agent = Agent(
    agent_name="Crypto-Risk-Analysis-Agent",
    agent_description="Agent for analyzing risks in cryptocurrency investments",
    system_prompt=CRYPTO_RISK_ANALYSIS_PROMPT,
    max_loops=1,
    llm=model,
)

print(
    agent.run(
        "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally"
    )
)
```

!!! warning "Resource Usage"
    The Llama4 model requires significant computational resources. Ensure your system meets the minimum requirements.

## FAQ

??? question "What is the purpose of max_loops parameter?"
    The `max_loops` parameter determines how many times the agent will iterate through its thinking process. In this example, it's set to 1 for a single pass analysis.

??? question "Can I use a different model?"
    Yes, you can replace the VLLM wrapper with other compatible models. Just ensure you update the model initialization accordingly.

??? question "How do I customize the system prompt?"
    You can modify the `CRYPTO_RISK_ANALYSIS_PROMPT` string to match your specific use case while maintaining the structured format.

!!! note "Best Practices"
    - Always handle API errors gracefully
    - Monitor model performance and resource usage
    - Keep your prompts clear and specific
    - Test thoroughly before production deployment

!!! example "Sample Usage"
    ```python
    response = agent.run(
        "Conduct a risk analysis of the top cryptocurrencies. Think for 2 loops internally"
    )
    print(response)
    ```

--------------------------------------------------

# File: swarms/examples/lumo.md

# Lumo Example
Introducing Lumo-70B-Instruct - the largest and most advanced AI model ever created for the Solana ecosystem. Built on Meta's groundbreaking LLaMa 3.3 70B Instruct foundation, this revolutionary model represents a quantum leap in blockchain-specific artificial intelligence. With an unprecedented 70 billion parameters and trained on the most comprehensive Solana documentation dataset ever assembled, Lumo-70B-Instruct sets a new standard for developer assistance in the blockchain space.


- [Docs](https://huggingface.co/lumolabs-ai/Lumo-70B-Instruct)

```python
from swarms import Agent
from transformers import LlamaForCausalLM, AutoTokenizer
import torch
from transformers import BitsAndBytesConfig

class Lumo:
    """
    A class for generating text using the Lumo model with 4-bit quantization.
    """
    def __init__(self):
        """
        Initializes the Lumo model with 4-bit quantization and a tokenizer.
        """
        # Configure 4-bit quantization
        bnb_config = BitsAndBytesConfig(
            load_in_4bit=True,
            bnb_4bit_quant_type="nf4",
            bnb_4bit_compute_dtype=torch.float16,
            llm_int8_enable_fp32_cpu_offload=True
        )

        self.model = LlamaForCausalLM.from_pretrained(
            "lumolabs-ai/Lumo-70B-Instruct",
            device_map="auto",
            quantization_config=bnb_config,
            use_cache=False,
            attn_implementation="sdpa"
        )
        self.tokenizer = AutoTokenizer.from_pretrained("lumolabs-ai/Lumo-70B-Instruct")

    def run(self, task: str) -> str:
        """
        Generates text based on the given prompt using the Lumo model.

        Args:
            prompt (str): The input prompt for the model.

        Returns:
            str: The generated text.
        """
        inputs = self.tokenizer(task, return_tensors="pt").to(self.model.device)
        outputs = self.model.generate(**inputs, max_new_tokens=100)
        return self.tokenizer.decode(outputs[0], skip_special_tokens=True)




Agent(
    agent_name="Solana-Analysis-Agent",
    llm=Lumo(),
    max_loops="auto",
    interactive=True,
    streaming_on=True,
).run("How do i create a smart contract in solana?")

```

--------------------------------------------------

# File: swarms/examples/mixture_of_agents.md

# MixtureOfAgents Examples

The MixtureOfAgents architecture combines multiple specialized agents with an aggregator agent to process complex tasks. This architecture is particularly effective for tasks requiring diverse expertise and consensus-building among different specialists.

## Prerequisites

- Python 3.7+
- OpenAI API key or other supported LLM provider keys
- Swarms library

## Installation

```bash
pip3 install -U swarms
```

## Environment Variables

```plaintext
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
```

## Basic Usage

### 1. Initialize Specialized Agents

```python
from swarms import Agent, MixtureOfAgents

# Initialize specialized agents
legal_expert = Agent(
    agent_name="Legal-Expert",
    system_prompt="""You are a legal expert specializing in contract law. Your responsibilities include:
    1. Analyzing legal documents and contracts
    2. Identifying potential legal risks
    3. Ensuring regulatory compliance
    4. Providing legal recommendations
    5. Drafting and reviewing legal documents""",
    model_name="gpt-4o",
    max_loops=1,
)

financial_expert = Agent(
    agent_name="Financial-Expert",
    system_prompt="""You are a financial expert specializing in business finance. Your tasks include:
    1. Analyzing financial implications
    2. Evaluating costs and benefits
    3. Assessing financial risks
    4. Providing financial projections
    5. Recommending financial strategies""",
    model_name="gpt-4o",
    max_loops=1,
)

business_expert = Agent(
    agent_name="Business-Expert",
    system_prompt="""You are a business strategy expert. Your focus areas include:
    1. Analyzing business models
    2. Evaluating market opportunities
    3. Assessing competitive advantages
    4. Providing strategic recommendations
    5. Planning business development""",
    model_name="gpt-4o",
    max_loops=1,
)

# Initialize aggregator agent
aggregator = Agent(
    agent_name="Decision-Aggregator",
    system_prompt="""You are a decision aggregator responsible for:
    1. Synthesizing input from multiple experts
    2. Resolving conflicting viewpoints
    3. Prioritizing recommendations
    4. Providing coherent final decisions
    5. Ensuring comprehensive coverage of all aspects""",
    model_name="gpt-4o",
    max_loops=1,
)
```

### 2. Create and Run MixtureOfAgents

```python
# Create list of specialist agents
specialists = [legal_expert, financial_expert, business_expert]

# Initialize the mixture of agents
moa = MixtureOfAgents(
    agents=specialists,
    aggregator_agent=aggregator,
    layers=3,
)

# Run the analysis
result = moa.run(
    "Analyze the proposed merger between Company A and Company B, considering legal, financial, and business aspects."
)
```

## Advanced Usage

### 1. Custom Configuration with System Prompts

```python
# Initialize MixtureOfAgents with custom aggregator prompt
moa = MixtureOfAgents(
    agents=specialists,
    aggregator_agent=aggregator,
    aggregator_system_prompt="""As the decision aggregator, synthesize the analyses from all specialists into a coherent recommendation:
    1. Summarize key points from each specialist
    2. Identify areas of agreement and disagreement
    3. Weigh different perspectives
    4. Provide a balanced final recommendation
    5. Highlight key risks and opportunities""",
    layers=3,
)

result = moa.run("Evaluate the potential acquisition of StartupX")
```

### 2. Error Handling and Validation

```python
try:
    moa = MixtureOfAgents(
        agents=specialists,
        aggregator_agent=aggregator,
        layers=3,
        verbose=True,
    )
    
    result = moa.run("Complex analysis task")
    
    # Validate and process results
    if result:
        print("Analysis complete:")
        print(result)
    else:
        print("Analysis failed to produce results")
        
except Exception as e:
    print(f"Error in analysis: {str(e)}")
```

## Best Practices

1. Agent Selection and Configuration:
   - Choose specialists with complementary expertise
   - Configure appropriate system prompts
   - Set suitable model parameters

2. Aggregator Configuration:
   - Define clear aggregation criteria
   - Set appropriate weights for different opinions
   - Configure conflict resolution strategies

3. Layer Management:
   - Set appropriate number of layers
   - Monitor layer effectiveness
   - Adjust based on task complexity

4. Quality Control:
   - Implement validation checks
   - Monitor agent performance
   - Ensure comprehensive coverage

## Example Implementation

Here's a complete example showing how to use MixtureOfAgents for a comprehensive business analysis:

```python
import os
from swarms import Agent, MixtureOfAgents

# Initialize specialist agents
market_analyst = Agent(
    agent_name="Market-Analyst",
    system_prompt="""You are a market analysis specialist focusing on:
    1. Market size and growth
    2. Competitive landscape
    3. Customer segments
    4. Market trends
    5. Entry barriers""",
    model_name="gpt-4o",
    max_loops=1,
)

financial_analyst = Agent(
    agent_name="Financial-Analyst",
    system_prompt="""You are a financial analysis expert specializing in:
    1. Financial performance
    2. Valuation metrics
    3. Cash flow analysis
    4. Investment requirements
    5. ROI projections""",
    model_name="gpt-4o",
    max_loops=1,
)

risk_analyst = Agent(
    agent_name="Risk-Analyst",
    system_prompt="""You are a risk assessment specialist focusing on:
    1. Market risks
    2. Operational risks
    3. Financial risks
    4. Regulatory risks
    5. Strategic risks""",
    model_name="gpt-4o",
    max_loops=1,
)

# Initialize aggregator
aggregator = Agent(
    agent_name="Strategic-Aggregator",
    system_prompt="""You are a strategic decision aggregator responsible for:
    1. Synthesizing specialist analyses
    2. Identifying key insights
    3. Evaluating trade-offs
    4. Making recommendations
    5. Providing action plans""",
    model_name="gpt-4o",
    max_loops=1,
)

# Create and configure MixtureOfAgents
try:
    moa = MixtureOfAgents(
        agents=[market_analyst, financial_analyst, risk_analyst],
        aggregator_agent=aggregator,
        aggregator_system_prompt="""Synthesize the analyses from all specialists to provide:
        1. Comprehensive situation analysis
        2. Key opportunities and risks
        3. Strategic recommendations
        4. Implementation considerations
        5. Success metrics""",
        layers=3,
        verbose=True,
    )
    
    # Run the analysis
    result = moa.run(
        """Evaluate the business opportunity for expanding into the electric vehicle market:
        1. Market potential and competition
        2. Financial requirements and projections
        3. Risk assessment and mitigation strategies"""
    )
    
    # Process and display results
    print("\nComprehensive Analysis Results:")
    print("=" * 50)
    print(result)
    print("=" * 50)
    
except Exception as e:
    print(f"Error during analysis: {str(e)}")
```

This comprehensive guide demonstrates how to effectively use the MixtureOfAgents architecture for complex analysis tasks requiring multiple expert perspectives and consensus-building. 

--------------------------------------------------

# File: swarms/examples/moa_example.md

# Mixture of Agents Example

The Mixture of Agents (MoA) is a sophisticated multi-agent architecture that implements parallel processing with iterative refinement. This approach processes multiple specialized agents simultaneously, concatenates their outputs, and then performs multiple parallel runs to achieve consensus or enhanced results.

## How It Works

1. **Parallel Processing**: Multiple agents work simultaneously on the same input
2. **Output Concatenation**: Results from all agents are combined into a unified response
3. **Iterative Refinement**: The process repeats for `n` layers/iterations to improve quality
4. **Consensus Building**: Multiple runs help achieve more reliable and comprehensive outputs

This architecture is particularly effective for complex tasks that benefit from diverse perspectives and iterative improvement, such as financial analysis, risk assessment, and multi-faceted problem solving.

![Mixture of Agents](https://files.readme.io/ddb138e-moa-3layer.png)


## Installation

Install the swarms package using pip:

```bash
pip install -U swarms
```

## Basic Setup

1. First, set up your environment variables:

```python
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY=""
```

## Code

```python
from swarms import Agent, MixtureOfAgents

# Agent 1: Risk Metrics Calculator
risk_metrics_agent = Agent(
    agent_name="Risk-Metrics-Calculator",
    agent_description="Calculates key risk metrics like VaR, Sharpe ratio, and volatility",
    system_prompt="""You are a risk metrics specialist. Calculate and explain:
    - Value at Risk (VaR)
    - Sharpe ratio
    - Volatility
    - Maximum drawdown
    - Beta coefficient
    
    Provide clear, numerical results with brief explanations.""",
    max_loops=1,
    # model_name="gpt-4o-mini",
    random_model_enabled=True,
    dynamic_temperature_enabled=True,
    output_type="str-all-except-first",
    max_tokens=4096,
)

# Agent 2: Portfolio Risk Analyzer
portfolio_risk_agent = Agent(
    agent_name="Portfolio-Risk-Analyzer",
    agent_description="Analyzes portfolio diversification and concentration risk",
    system_prompt="""You are a portfolio risk analyst. Focus on:
    - Portfolio diversification analysis
    - Concentration risk assessment
    - Correlation analysis
    - Sector/asset allocation risk
    - Liquidity risk evaluation
    
    Provide actionable insights for risk reduction.""",
    max_loops=1,
    # model_name="gpt-4o-mini",
    random_model_enabled=True,
    dynamic_temperature_enabled=True,
    output_type="str-all-except-first",
    max_tokens=4096,
)

# Agent 3: Market Risk Monitor
market_risk_agent = Agent(
    agent_name="Market-Risk-Monitor",
    agent_description="Monitors market conditions and identifies risk factors",
    system_prompt="""You are a market risk monitor. Identify and assess:
    - Market volatility trends
    - Economic risk factors
    - Geopolitical risks
    - Interest rate risks
    - Currency risks
    
    Provide current risk alerts and trends.""",
    max_loops=1,
    # model_name="gpt-4o-mini",
    random_model_enabled=True,
    dynamic_temperature_enabled=True,
    output_type="str-all-except-first",
    max_tokens=4096,
)


swarm = MixtureOfAgents(
    agents=[
        risk_metrics_agent,
        portfolio_risk_agent,
        market_risk_agent,
    ],
    layers=1,
    max_loops=1,
    output_type="final",
)


out = swarm.run(
    "Calculate VaR and Sharpe ratio for a portfolio with 15% annual return and 20% volatility"
)

print(out)
```

## Support and Community

If you're facing issues or want to learn more, check out the following resources to join our Discord, stay updated on Twitter, and watch tutorials on YouTube!

| Platform | Link | Description |
|----------|------|-------------|
| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides |
| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles |
| 💬 Discord | [Join Discord](https://discord.gg/EamjgSaEQf) | Live chat and community support |
| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements |
| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates |
| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos |
| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events |



--------------------------------------------------

# File: swarms/examples/model_providers.md

# Model Providers Overview

Swarms supports a vast array of model providers, giving you the flexibility to choose the best model for your specific use case. Whether you need high-performance inference, cost-effective solutions, or specialized capabilities, Swarms has you covered.

## Supported Model Providers

| Provider | Description | Documentation |
|----------|-------------|---------------|
| **OpenAI** | Industry-leading language models including GPT-4, GPT-4o, and GPT-4o-mini. Perfect for general-purpose tasks, creative writing, and complex reasoning. | [OpenAI Integration](openai_example.md) |
| **Anthropic/Claude** | Advanced AI models known for their safety, helpfulness, and reasoning capabilities. Claude models excel at analysis, coding, and creative tasks. | [Claude Integration](claude.md) |
| **Groq** | Ultra-fast inference platform offering real-time AI responses. Ideal for applications requiring low latency and high throughput. | [Groq Integration](groq.md) |
| **Cohere** | Enterprise-grade language models with strong performance on business applications, text generation, and semantic search. | [Cohere Integration](cohere.md) |
| **DeepSeek** | Advanced reasoning models including the DeepSeek Reasoner (R1). Excellent for complex problem-solving and analytical tasks. | [DeepSeek Integration](deepseek.md) |
| **Ollama** | Local model deployment platform allowing you to run open-source models on your own infrastructure. No API keys required. | [Ollama Integration](ollama.md) |
| **OpenRouter** | Unified API gateway providing access to hundreds of models from various providers through a single interface. | [OpenRouter Integration](openrouter.md) |
| **XAI** | xAI's Grok models offering unique capabilities for research, analysis, and creative tasks with advanced reasoning abilities. | [XAI Integration](xai.md) |
| **vLLM** | High-performance inference library for serving large language models with optimized memory usage and throughput. | [vLLM Integration](vllm_integration.md) |
| **Llama4** | Meta's latest open-source language models including Llama-4-Maverick and Llama-4-Scout variants with expert routing capabilities. | [Llama4 Integration](llama4.md) |
| **Azure OpenAI** | Enterprise-grade OpenAI models through Microsoft's cloud infrastructure with enhanced security, compliance, and enterprise features. | [Azure Integration](azure.md) |

## Quick Start

All model providers follow a consistent pattern in Swarms. Here's the basic template:

```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize agent with your chosen model
agent = Agent(
    agent_name="Your-Agent-Name",
    model_name="gpt-4o-mini",  # Varies by provider
    system_prompt="Your system prompt here",
    agent_description="Description of what your agent does.",
)

# Run your agent
response = agent.run("Your query here")
```

## Model Selection Guide

### For High-Performance Applications

- **OpenAI GPT-4o**: Best overall performance and reasoning

- **Anthropic Claude**: Excellent safety and analysis capabilities

- **DeepSeek R1**: Advanced reasoning and problem-solving

### For Cost-Effective Solutions

- **OpenAI GPT-4o-mini**: Great performance at lower cost

- **Ollama**: Free local deployment

- **OpenRouter**: Access to cost-effective models

### For Real-Time Applications

- **Groq**: Ultra-fast inference

- **vLLM**: Optimized for high throughput

### For Specialized Tasks

- **Llama4**: Expert routing for complex workflows

- **XAI Grok**: Advanced research capabilities

- **Cohere**: Strong business applications

## Environment Setup

Most providers require API keys. Add them to your `.env` file:

```bash
# OpenAI
OPENAI_API_KEY=your_openai_key

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key

# Groq
GROQ_API_KEY=your_groq_key

# Cohere
COHERE_API_KEY=your_cohere_key

# DeepSeek
DEEPSEEK_API_KEY=your_deepseek_key

# OpenRouter
OPENROUTER_API_KEY=your_openrouter_key

# XAI
XAI_API_KEY=your_xai_key

# Azure OpenAI
AZURE_API_KEY=your_azure_openai_api_key
AZURE_API_BASE=https://your-resource-name.openai.azure.com/
AZURE_API_VERSION=2024-02-15-preview
```

!!! note "No API Key Required"
    Ollama and vLLM can be run locally without API keys, making them perfect for development and testing.

## Advanced Features

### Multi-Model Workflows

Swarms allows you to create workflows that use different models for different tasks:

```python
from swarms import Agent, ConcurrentWorkflow

# Research agent using Claude for analysis
research_agent = Agent(
    agent_name="Research-Agent",
    model_name="claude-3-sonnet-20240229",
    system_prompt="You are a research expert."
)

# Creative agent using GPT-4o for content generation
creative_agent = Agent(
    agent_name="Creative-Agent", 
    model_name="gpt-4o",
    system_prompt="You are a creative content expert."
)

# Workflow combining both agents
workflow = ConcurrentWorkflow(
    name="Research-Creative-Workflow",
    agents=[research_agent, creative_agent]
)
```

### Model Routing

Automatically route tasks to the most appropriate model:

```python
from swarms import Agent, ModelRouter

# Define model preferences for different task types
model_router = ModelRouter(
    models={
        "analysis": "claude-3-sonnet-20240229",
        "creative": "gpt-4o", 
        "fast": "gpt-4o-mini",
        "local": "ollama/llama2"
    }
)

# Agent will automatically choose the best model
agent = Agent(
    agent_name="Smart-Agent",
    llm=model_router,
    system_prompt="You are a versatile assistant."
)
```

## Getting Help

- **Documentation**: Each provider has detailed documentation with examples

- **Community**: Join the Swarms community for support and best practices

- **Issues**: Report bugs and request features on GitHub

- **Discussions**: Share your use cases and learn from others

!!! success "Ready to Get Started?"
    Choose a model provider from the table above and follow the detailed integration guide. Each provider offers unique capabilities that can enhance your Swarms applications.


--------------------------------------------------

# File: swarms/examples/multi_agent_router_minimal.md

# MultiAgentRouter Minimal Example

This example shows how to route a task to the most suitable agent using `SwarmRouter` with `swarm_type="MultiAgentRouter"`.

```python
from swarms import Agent
from swarms.structs.swarm_router import SwarmRouter

agents = [
    Agent(
        agent_name="Researcher",
        system_prompt="Answer questions briefly.",
        model_name="gpt-4o-mini",
    ),
    Agent(
        agent_name="Coder",
        system_prompt="Write small Python functions.",
        model_name="gpt-4o-mini",
    ),
]

router = SwarmRouter(
    name="multi-agent-router-demo",
    description="Routes tasks to the most suitable agent",
    agents=agents,
    swarm_type="MultiAgentRouter"
)

result = router.run("Write a function that adds two numbers")
print(result)
```

View the source on [GitHub](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/mar/multi_agent_router_minimal.py).

--------------------------------------------------

# File: swarms/examples/multiple_images.md

# Processing Multiple Images

This tutorial shows how to process multiple images with a single agent using Swarms' multi-modal capabilities. You'll learn to configure an agent for batch image analysis, enabling efficient processing for quality control, object detection, or image comparison tasks.


## Installation

Install the swarms package using pip:

```bash
pip install -U swarms
```

## Basic Setup

1. First, set up your environment variables:

```python
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY=""
```


## Code

- Create a list of images by their file paths

- Pass it into the `Agent.run(imgs=[str])` parameter

- Activate `summarize_multiple_images=True` if you want the agent to output a summary of the image analyses


```python
from swarms import Agent
from swarms.prompts.logistics import (
    Quality_Control_Agent_Prompt,
)


# Image for analysis
factory_image = "image.jpg"

# Quality control agent
quality_control_agent = Agent(
    agent_name="Quality Control Agent",
    agent_description="A quality control agent that analyzes images and provides a detailed report on the quality of the product in the image.",
    model_name="claude-3-5-sonnet-20240620",
    system_prompt=Quality_Control_Agent_Prompt,
    multi_modal=True,
    max_loops=1,
    output_type="str-all-except-first",
    summarize_multiple_images=True,
)


response = quality_control_agent.run(
    task="what is in the image?",
    imgs=[factory_image, factory_image],
)

print(response)
```

## Support and Community

If you're facing issues or want to learn more, check out the following resources to join our Discord, stay updated on Twitter, and watch tutorials on YouTube!

| Platform | Link | Description |
|----------|------|-------------|
| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides |
| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles |
| 💬 Discord | [Join Discord](https://discord.gg/EamjgSaEQf) | Live chat and community support |
| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements |
| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates |
| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos |
| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events |



--------------------------------------------------

# File: swarms/examples/ollama.md

# Agent with Ollama

- No API key needed
- Select your model_name like `ollama/llama2` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/ollama)


```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="ollama/llama2",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

--------------------------------------------------

# File: swarms/examples/openai_example.md

# Agent with GPT-4o-Mini

- Add `OPENAI_API_KEY="your_key"` to your `.env` file
- Select your model like `gpt-4o-mini` or `gpt-4o`

```python
from swarms import Agent

Agent(
    agent_name="Stock-Analysis-Agent",
    model_name="gpt-4o-mini",
    max_loops="auto",
    interactive=True,
    streaming_on=True,
).run("What are 5 hft algorithms")
```

--------------------------------------------------

# File: swarms/examples/openrouter.md

# Agent with OpenRouter

- Add your `OPENROUTER_API_KEY` in the `.env` file

- Select your model_name like `openrouter/google/palm-2-chat-bison` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/openrouter)

- Execute your agent!


```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="openrouter/google/palm-2-chat-bison",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

--------------------------------------------------

# File: swarms/examples/quant_crypto_agent.md

# Quant Crypto Agent

- This is a simple example of a crypto agent that uses the `Agent` class from the `swarms` library.
- It uses the `fetch_htx_data` and `coin_gecko_coin_api` tools to fetch data from the `htx` and `CoinGecko` APIs.
- It uses the `Agent` class to create an agent that can analyze the current state of a crypto asset.

## Steps

1. Install the `swarms` library.
2. Install the `swarms_tools` library.
3. Setup your `.env` file with the `OPENAI_API_KEY` environment variables.
4. Run the code.

## Installation:

```bash
pip install swarms swarms-tools python-dotenv
```

## Code:

```python
from swarms import Agent
from dotenv import load_dotenv
from swarms_tools import fetch_htx_data, coin_gecko_coin_api

load_dotenv()

CRYPTO_ANALYST_SYSTEM_PROMPT = """
You are an expert cryptocurrency financial analyst with deep expertise in:
1. Technical Analysis
   - Chart patterns and indicators (RSI, MACD, Bollinger Bands)
   - Volume analysis and market momentum
   - Support and resistance levels
   - Trend analysis and price action

2. Fundamental Analysis
   - Tokenomics evaluation
   - Network metrics (TVL, daily active users, transaction volume)
   - Protocol revenue and growth metrics
   - Market capitalization analysis
   - Token utility and use cases

3. Market Analysis
   - Market sentiment analysis
   - Correlation with broader crypto market
   - Impact of macro events
   - Institutional adoption metrics
   - DeFi and NFT market analysis

4. Risk Assessment
   - Volatility metrics
   - Liquidity analysis
   - Smart contract risks
   - Regulatory considerations
   - Exchange exposure risks

5. Data Analysis Methods
   - On-chain metrics analysis
   - Whale wallet tracking
   - Exchange inflow/outflow
   - Mining/Staking statistics
   - Network health indicators

When analyzing crypto assets, always:
1. Start with a comprehensive market overview
2. Examine both on-chain and off-chain metrics
3. Consider multiple timeframes (short, medium, long-term)
4. Evaluate risk-reward ratios
5. Assess market sentiment and momentum
6. Consider regulatory and security factors
7. Analyze correlations with BTC, ETH, and traditional markets
8. Examine liquidity and volume profiles
9. Review recent protocol developments and updates
10. Consider macro economic factors

Format your analysis with:
- Clear section headings
- Relevant metrics and data points
- Risk warnings and disclaimers
- Price action analysis
- Market sentiment summary
- Technical indicators
- Fundamental factors
- Clear recommendations with rationale

Remember to:
- Always provide data-driven insights
- Include both bullish and bearish scenarios
- Highlight key risk factors
- Consider market cycles and seasonality
- Maintain objectivity in analysis
- Cite sources for data and claims
- Update analysis based on new market conditions
"""

# Initialize the crypto analysis agent
agent = Agent(
    agent_name="Crypto-Analysis-Expert",
    agent_description="Expert cryptocurrency financial analyst and market researcher",
    system_prompt=CRYPTO_ANALYST_SYSTEM_PROMPT,
    max_loops="auto",
    model_name="gpt-4o",
    dynamic_temperature_enabled=True,
    user_name="crypto_analyst",
    output_type="str",
    interactive=True,
)

print(fetch_htx_data("sol"))
print(coin_gecko_coin_api("solana"))

# Example usage
agent.run(
    f"""
    Analyze the current state of Solana (SOL), including:
    1. Technical analysis of price action
    2. On-chain metrics and network health
    3. Recent protocol developments
    4. Market sentiment
    5. Risk factors
    Please provide a comprehensive analysis with data-driven insights.
    
    # Solana CoinGecko Data
    Real-tim data from Solana CoinGecko: \n {coin_gecko_coin_api("solana")}
    
    """
)
```

--------------------------------------------------

# File: swarms/examples/sequential_example.md

# Sequential Workflow Example

!!! abstract "Overview"
    Learn how to create a sequential workflow with multiple specialized AI agents using the Swarms framework. This example demonstrates how to set up a legal practice workflow with different types of legal agents working in sequence.

## Prerequisites

!!! info "Before You Begin"
    Make sure you have:
    
    - Python 3.7+ installed
    
    - A valid API key for your model provider
    
    - The Swarms package installed

## Installation

```bash
pip3 install -U swarms
```

## Environment Setup

!!! tip "API Key Configuration"
    Set your API key in the `.env` file:
    ```bash
    OPENAI_API_KEY="your-api-key-here"
    ```

## Code Implementation

### Import Required Modules

```python
from swarms import Agent, SequentialWorkflow
```

### Configure Agents

!!! example "Legal Agent Configuration"
    Here's how to set up your specialized legal agents:

    ```python
    # Litigation Agent
    litigation_agent = Agent(
        agent_name="Alex Johnson",
        system_prompt="As a Litigator, you specialize in navigating the complexities of lawsuits. Your role involves analyzing intricate facts, constructing compelling arguments, and devising effective case strategies to achieve favorable outcomes for your clients.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )

    # Corporate Attorney Agent
    corporate_agent = Agent(
        agent_name="Emily Carter",
        system_prompt="As a Corporate Attorney, you provide expert legal advice on business law matters. You guide clients on corporate structure, governance, compliance, and transactions, ensuring their business operations align with legal requirements.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )

    # IP Attorney Agent
    ip_agent = Agent(
        agent_name="Michael Smith",
        system_prompt="As an IP Attorney, your expertise lies in protecting intellectual property rights. You handle various aspects of IP law, including patents, trademarks, copyrights, and trade secrets, helping clients safeguard their innovations.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )
    ```

### Initialize Sequential Workflow

!!! example "Workflow Setup"
    Configure the SequentialWorkflow with your agents:

    ```python
    swarm = SequentialWorkflow(
        agents=[litigation_agent, corporate_agent, ip_agent],
        name="litigation-practice",
        description="Handle all aspects of litigation with a focus on thorough legal analysis and effective case management.",
    )
    ```

### Run the Workflow

!!! example "Execute the Workflow"
    Start the sequential workflow:

    ```python
    swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.")
    ```

## Complete Example

!!! success "Full Implementation"
    Here's the complete code combined:

    ```python
    from swarms import Agent, SequentialWorkflow

    # Core Legal Agent Definitions with enhanced system prompts
    litigation_agent = Agent(
        agent_name="Alex Johnson",
        system_prompt="As a Litigator, you specialize in navigating the complexities of lawsuits. Your role involves analyzing intricate facts, constructing compelling arguments, and devising effective case strategies to achieve favorable outcomes for your clients.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )

    corporate_agent = Agent(
        agent_name="Emily Carter",
        system_prompt="As a Corporate Attorney, you provide expert legal advice on business law matters. You guide clients on corporate structure, governance, compliance, and transactions, ensuring their business operations align with legal requirements.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )

    ip_agent = Agent(
        agent_name="Michael Smith",
        system_prompt="As an IP Attorney, your expertise lies in protecting intellectual property rights. You handle various aspects of IP law, including patents, trademarks, copyrights, and trade secrets, helping clients safeguard their innovations.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )

    # Initialize and run the workflow
    swarm = SequentialWorkflow(
        agents=[litigation_agent, corporate_agent, ip_agent],
        name="litigation-practice",
        description="Handle all aspects of litigation with a focus on thorough legal analysis and effective case management.",
    )

    swarm.run("Create a report on how to patent an all-new AI invention and what platforms to use and more.")
    ```

## Agent Roles

!!! info "Specialized Legal Agents"
    | Agent | Role | Expertise |
    |-------|------|-----------|
    | Alex Johnson | Litigator | Lawsuit navigation, case strategy |
    | Emily Carter | Corporate Attorney | Business law, compliance |
    | Michael Smith | IP Attorney | Patents, trademarks, copyrights |

## Configuration Options

!!! info "Key Parameters"
    | Parameter | Description | Default |
    |-----------|-------------|---------|
    | `agent_name` | Human-readable name for the agent | Required |
    | `system_prompt` | Detailed role description and expertise | Required |
    | `model_name` | LLM model to use | "gpt-4o-mini" |
    | `max_loops` | Maximum number of processing loops | 1 |

## Next Steps

!!! tip "What to Try Next"
    1. Experiment with different agent roles and specializations
    2. Modify the system prompts to create different expertise areas
    3. Add more agents to the workflow for complex tasks
    4. Try different model configurations

## Troubleshooting

!!! warning "Common Issues"
    - Ensure your API key is correctly set in the `.env` file
    
    - Check that all required dependencies are installed
    
    - Verify that your model provider's API is accessible
    
    - Monitor agent responses for quality and relevance


--------------------------------------------------

# File: swarms/examples/swarm_router.md

# SwarmRouter Examples

The SwarmRouter is a flexible routing system designed to manage different types of swarms for task execution. It provides a unified interface to interact with various swarm types, including `AgentRearrange`, `MixtureOfAgents`, `SpreadSheetSwarm`, `SequentialWorkflow`, and `ConcurrentWorkflow`.

## Prerequisites

- Python 3.7+
- OpenAI API key or other supported LLM provider keys
- Swarms library

## Installation

```bash
pip3 install -U swarms
```

## Environment Variables

```plaintext
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
```

## Basic Usage

### 1. Initialize Specialized Agents

```python
from swarms import Agent
from swarms.structs.swarm_router import SwarmRouter, SwarmType

# Initialize specialized agents
data_extractor_agent = Agent(
    agent_name="Data-Extractor",
    system_prompt="You are a data extraction specialist...",
    model_name="gpt-4o",
    max_loops=1,
)

summarizer_agent = Agent(
    agent_name="Document-Summarizer",
    system_prompt="You are a document summarization expert...",
    model_name="gpt-4o",
    max_loops=1,
)

financial_analyst_agent = Agent(
    agent_name="Financial-Analyst",
    system_prompt="You are a financial analysis specialist...",
    model_name="gpt-4o",
    max_loops=1,
)
```

### 2. Create SwarmRouter with Sequential Workflow

```python
sequential_router = SwarmRouter(
    name="SequentialRouter",
    description="Process tasks in sequence",
    agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent],
    swarm_type=SwarmType.SequentialWorkflow,
    max_loops=1
)

# Run a task
result = sequential_router.run("Analyze and summarize the quarterly financial report")
```

### 3. Create SwarmRouter with Concurrent Workflow

```python
concurrent_router = SwarmRouter(
    name="ConcurrentRouter",
    description="Process tasks concurrently",
    agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent],
    swarm_type=SwarmType.ConcurrentWorkflow,
    max_loops=1
)

# Run a task
result = concurrent_router.run("Evaluate multiple aspects of the company simultaneously")
```

### 4. Create SwarmRouter with AgentRearrange

```python
rearrange_router = SwarmRouter(
    name="RearrangeRouter",
    description="Dynamically rearrange agents for optimal task processing",
    agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent],
    swarm_type=SwarmType.AgentRearrange,
    flow=f"{data_extractor_agent.agent_name} -> {summarizer_agent.agent_name} -> {financial_analyst_agent.agent_name}",
    max_loops=1
)

# Run a task
result = rearrange_router.run("Process and analyze company documents")
```

### 5. Create SwarmRouter with MixtureOfAgents

```python
mixture_router = SwarmRouter(
    name="MixtureRouter",
    description="Combine multiple expert agents",
    agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent],
    swarm_type=SwarmType.MixtureOfAgents,
    max_loops=1
)

# Run a task
result = mixture_router.run("Provide comprehensive analysis of company performance")
```

## Advanced Features

### 1. Error Handling and Logging

```python
try:
    result = router.run("Complex analysis task")
    
    # Retrieve and print logs
    for log in router.get_logs():
        print(f"{log.timestamp} - {log.level}: {log.message}")
except Exception as e:
    print(f"Error occurred: {str(e)}")
```

### 2. Custom Configuration

```python
router = SwarmRouter(
    name="CustomRouter",
    description="Custom router configuration",
    agents=[data_extractor_agent, summarizer_agent, financial_analyst_agent],
    swarm_type=SwarmType.SequentialWorkflow,
    max_loops=3,
    autosave=True,
    verbose=True,
    output_type="json"
)
```

# Best Practices

## Choose the appropriate swarm type based on your task requirements:

| Swarm Type | Use Case |
|------------|----------|
| `SequentialWorkflow` | Tasks that need to be processed in order |
| `ConcurrentWorkflow` | Independent tasks that can be processed simultaneously |
| `AgentRearrange` | Tasks requiring dynamic agent organization |
| `MixtureOfAgents` | Complex tasks needing multiple expert perspectives |

## Configure agents appropriately:

   | Configuration Aspect | Description |
   |---------------------|-------------|
   | Agent Names & Descriptions | Set meaningful and descriptive names that reflect the agent's role and purpose |
   | System Prompts | Define clear, specific prompts that outline the agent's responsibilities and constraints |
   | Model Parameters | Configure appropriate parameters like temperature, max_tokens, and other model-specific settings |

## Implement proper error handling:

| Error Handling Practice | Description |
|------------------------|-------------|
| Try-Except Blocks | Implement proper exception handling with try-except blocks |
| Log Monitoring | Regularly monitor and analyze system logs for potential issues |
| Edge Case Handling | Implement specific handling for edge cases and unexpected scenarios |

## Optimize performance:

| Performance Optimization | Description |
|------------------------|-------------|
| Concurrent Processing | Utilize parallel processing capabilities when tasks can be executed simultaneously |
| Max Loops Configuration | Set appropriate iteration limits based on task complexity and requirements |
| Resource Management | Continuously monitor and optimize system resource utilization |

## Example Implementation

Here's a complete example showing how to use SwarmRouter in a real-world scenario:

```python
import os
from swarms import Agent
from swarms.structs.swarm_router import SwarmRouter, SwarmType

# Initialize specialized agents
research_agent = Agent(
    agent_name="ResearchAgent",
    system_prompt="You are a research specialist...",
    model_name="gpt-4o",
    max_loops=1
)

analysis_agent = Agent(
    agent_name="AnalysisAgent",
    system_prompt="You are an analysis expert...",
    model_name="gpt-4o",
    max_loops=1
)

summary_agent = Agent(
    agent_name="SummaryAgent",
    system_prompt="You are a summarization specialist...",
    model_name="gpt-4o",
    max_loops=1
)

# Create router with sequential workflow
router = SwarmRouter(
    name="ResearchAnalysisRouter",
    description="Process research and analysis tasks",
    agents=[research_agent, analysis_agent, summary_agent],
    swarm_type=SwarmType.SequentialWorkflow,
    max_loops=1,
    verbose=True
)

# Run complex task
try:
    result = router.run(
        "Research and analyze the impact of AI on healthcare, "
        "providing a comprehensive summary of findings."
    )
    print("Task Result:", result)
    
    # Print logs
    for log in router.get_logs():
        print(f"{log.timestamp} - {log.level}: {log.message}")
        
except Exception as e:
    print(f"Error processing task: {str(e)}")
```

This comprehensive guide demonstrates how to effectively use the SwarmRouter in various scenarios, making it easier to manage and orchestrate multiple agents for complex tasks. 

--------------------------------------------------

# File: swarms/examples/swarms_api_finance.md


# Finance Swarm Example

1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys)
2. Create a `.env` file in the root directory and add your API key:

```bash
SWARMS_API_KEY=<your-api-key>
```

3. Create a Python script to create and trigger the financial swarm:


```python
import os
import requests
from dotenv import load_dotenv
import json

load_dotenv()

# Retrieve API key securely from .env
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

# Headers for secure API communication
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

def create_financial_swarm(equity_data: str):
    """
    Constructs and triggers a full-stack financial swarm consisting of three agents:
    Equity Analyst, Risk Assessor, and Market Advisor.
    Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability.
    """

    payload = {
        "swarm_name": "Enhanced Financial Analysis Swarm",
        "description": "A swarm of agents specialized in performing comprehensive financial analysis, risk assessment, and market recommendations.",
        "agents": [
            {
                "agent_name": "Equity Analyst",
                "description": "Agent specialized in analyzing equities data to provide insights on stock performance and valuation.",
                "system_prompt": (
                    "You are an experienced equity analyst with expertise in financial markets and stock valuation. "
                    "Your role is to analyze the provided equities data, including historical performance, financial statements, and market trends. "
                    "Provide a detailed analysis of the stock's potential, including valuation metrics and growth prospects. "
                    "Consider macroeconomic factors, industry trends, and company-specific news. Your analysis should be clear, actionable, and well-supported by data."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 4000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Risk Assessor",
                "description": "Agent responsible for evaluating the risks associated with equity investments.",
                "system_prompt": (
                    "You are a certified risk management professional with expertise in financial risk assessment. "
                    "Your task is to evaluate the risks associated with the provided equities data, including market risk, credit risk, and operational risk. "
                    "Provide a comprehensive risk analysis, including potential scenarios and their impact on investment performance. "
                    "Your output should be detailed, reliable, and compliant with current risk management standards."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 3000,
                "temperature": 0.2,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Market Advisor",
                "description": "Agent dedicated to suggesting investment strategies based on market conditions and equity analysis.",
                "system_prompt": (
                    "You are a knowledgeable market advisor with expertise in investment strategies and portfolio management. "
                    "Based on the analysis provided by the Equity Analyst and the risk assessment, your task is to recommend a comprehensive investment strategy. "
                    "Your suggestions should include asset allocation, diversification strategies, and considerations for market conditions. "
                    "Explain the rationale behind each recommendation and reference relevant market data where applicable. "
                    "Your recommendations should be reliable, detailed, and clearly prioritized based on risk and return."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 5000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            }
        ],
        "max_loops": 1,
        "swarm_type": "SequentialWorkflow",
        "task": equity_data,
    }

    # Payload includes the equity data as the task to be processed by the swarm

    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload,
    )

    if response.status_code == 200:
        print("Swarm successfully executed!")
        return json.dumps(response.json(), indent=4)
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None


# Example Equity Data for the Swarm to analyze
if __name__ == "__main__":
    equity_data = (
        "Analyze the equity data for Company XYZ, which has shown a 15% increase in revenue over the last quarter, "
        "with a P/E ratio of 20 and a market cap of $1 billion. Consider the current market conditions and potential risks."
    )

    financial_output = create_financial_swarm(equity_data)
    print(financial_output)
```

4. Run the script:

```bash
python financial_swarm.py
```



--------------------------------------------------

# File: swarms/examples/swarms_api_medical.md

# Medical Swarm Example

1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys)
2. Create a `.env` file in the root directory and add your API key:

```bash
SWARMS_API_KEY=<your-api-key>
```

3. Create a Python script to create and trigger the medical swarm:

```python
import os
import requests
from dotenv import load_dotenv
import json

load_dotenv()

# Retrieve API key securely from .env
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

# Headers for secure API communication
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

def create_medical_swarm(patient_case: str):
    """
    Constructs and triggers a full-stack medical swarm consisting of three agents:
    Diagnostic Specialist, Medical Coder, and Treatment Advisor.
    Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability.
    """

    payload = {
        "swarm_name": "Enhanced Medical Diagnostic Swarm",
        "description": "A swarm of agents specialized in performing comprehensive medical diagnostics, analysis, and coding.",
        "agents": [
            {
                "agent_name": "Diagnostic Specialist",
                "description": "Agent specialized in analyzing patient history, symptoms, lab results, and imaging data to produce accurate diagnoses.",
                "system_prompt": (
                    "You are an experienced, board-certified medical diagnostician with over 20 years of clinical practice. "
                    "Your role is to analyze all available patient information—including history, symptoms, lab tests, and imaging results—"
                    "with extreme attention to detail and clinical nuance. Provide a comprehensive differential diagnosis considering "
                    "common, uncommon, and rare conditions. Always cross-reference clinical guidelines and evidence-based medicine. "
                    "Explain your reasoning step by step and provide a final prioritized list of potential diagnoses along with their likelihood. "
                    "Consider patient demographics, comorbidities, and risk factors. Your diagnosis should be reliable, clear, and actionable."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 4000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Medical Coder",
                "description": "Agent responsible for translating medical diagnoses and procedures into accurate standardized medical codes (ICD-10, CPT, etc.).",
                "system_prompt": (
                    "You are a certified and experienced medical coder, well-versed in ICD-10, CPT, and other coding systems. "
                    "Your task is to convert detailed medical diagnoses and treatment procedures into precise, standardized codes. "
                    "Consider all aspects of the clinical documentation including severity, complications, and comorbidities. "
                    "Provide clear explanations for the codes chosen, referencing the latest coding guidelines and payer policies where relevant. "
                    "Your output should be comprehensive, reliable, and fully compliant with current medical coding standards."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 3000,
                "temperature": 0.2,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Treatment Advisor",
                "description": "Agent dedicated to suggesting evidence-based treatment options, including pharmaceutical and non-pharmaceutical interventions.",
                "system_prompt": (
                    "You are a highly knowledgeable medical treatment specialist with expertise in the latest clinical guidelines and research. "
                    "Based on the diagnostic conclusions provided, your task is to recommend a comprehensive treatment plan. "
                    "Your suggestions should include first-line therapies, potential alternative treatments, and considerations for patient-specific factors "
                    "such as allergies, contraindications, and comorbidities. Explain the rationale behind each treatment option and reference clinical guidelines where applicable. "
                    "Your recommendations should be reliable, detailed, and clearly prioritized based on efficacy and safety."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 5000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            }
        ],
        "max_loops": 1,
        "swarm_type": "SequentialWorkflow",
        "task": patient_case,
    }

    # Payload includes the patient case as the task to be processed by the swar

    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload,
    )

    if response.status_code == 200:
        print("Swarm successfully executed!")
        return json.dumps(response.json(), indent=4)
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None


# Example Patient Task for the Swarm to diagnose and analyze
if __name__ == "__main__":
    patient_case = (
        "Patient is a 55-year-old male presenting with severe chest pain, shortness of breath, elevated blood pressure, "
        "nausea, and a family history of cardiovascular disease. Blood tests show elevated troponin levels, and EKG indicates ST-segment elevations. "
        "The patient is currently unstable. Provide a detailed diagnosis, coding, and treatment plan."
    )

    diagnostic_output = create_medical_swarm(patient_case)
    print(diagnostic_output)
```

4. Run the script:

```bash
python medical_swarm.py
```

--------------------------------------------------

# File: swarms/examples/swarms_api_ml_model.md

# ML Model Code Generation Swarm Example

1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys)
2. Create a `.env` file in the root directory and add your API key:

```bash
SWARMS_API_KEY=<your-api-key>
```

3. Create a Python script to create and trigger the following swarm:


```python
import os
import requests
from dotenv import load_dotenv
import json

load_dotenv()

# Retrieve API key securely from .env
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

# Headers for secure API communication
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

def create_ml_code_swarm(task_description: str):
    """
    Constructs and triggers a swarm of agents for generating a complete machine learning project using PyTorch.
    The swarm includes:
      - Model Code Generator: Generates the PyTorch model architecture code.
      - Training Script Generator: Creates a comprehensive training, validation, and testing script using PyTorch.
      - Unit Test Creator: Produces extensive unit tests and helper code, ensuring correctness of the model and training scripts.
    Each agent's prompt is highly detailed to output only Python code, with exclusive use of PyTorch.
    """
    payload = {
        "swarm_name": "Comprehensive PyTorch Code Generation Swarm",
        "description": (
            "A production-grade swarm of agents tasked with generating a complete machine learning project exclusively using PyTorch. "
            "The swarm is divided into distinct roles: one agent generates the core model architecture code; "
            "another creates the training and evaluation scripts including data handling; and a third produces "
            "extensive unit tests and helper functions. Each agent's instructions are highly detailed to ensure that the "
            "output is strictly Python code with PyTorch as the only deep learning framework."
        ),
        "agents": [
            {
                "agent_name": "Model Code Generator",
                "description": "Generates the complete machine learning model architecture code using PyTorch.",
                "system_prompt": (
                    "You are an expert machine learning engineer with a deep understanding of PyTorch. "
                    "Your task is to generate production-ready Python code that defines a complete deep learning model architecture exclusively using PyTorch. "
                    "The code must include all necessary imports, class or function definitions, and should be structured in a modular and scalable manner. "
                    "Follow PEP8 standards and output only code—no comments, explanations, or extraneous text. "
                    "Your model definition should include proper layer initialization, activation functions, dropout, and any custom components as required. "
                    "Ensure that the entire output is strictly Python code based on PyTorch."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 2,
                "max_tokens": 4000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Training Script Generator",
                "description": "Creates a comprehensive training, validation, and testing script using PyTorch.",
                "system_prompt": (
                    "You are a highly skilled software engineer specializing in machine learning pipeline development with PyTorch. "
                    "Your task is to generate Python code that builds a complete training pipeline using PyTorch. "
                    "The script must include robust data loading, preprocessing, augmentation, and a complete training loop, along with validation and testing procedures. "
                    "All necessary imports should be included and the code should assume that the model code from the previous agent is available via proper module imports. "
                    "Follow best practices for reproducibility and modularity, and output only code without any commentary or non-code text. "
                    "The entire output must be strictly Python code that uses PyTorch for all deep learning operations."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 3000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Unit Test Creator",
                "description": "Develops a suite of unit tests and helper functions for verifying the PyTorch model and training pipeline.",
                "system_prompt": (
                    "You are an experienced software testing expert with extensive experience in writing unit tests for machine learning projects in PyTorch. "
                    "Your task is to generate Python code that consists solely of unit tests and any helper functions required to validate both the PyTorch model and the training pipeline. "
                    "Utilize testing frameworks such as pytest or unittest. The tests should cover key functionalities such as model instantiation, forward pass correctness, "
                    "training loop execution, data preprocessing verification, and error handling. "
                    "Ensure that your output is only Python code, without any additional text or commentary, and that it is ready to be integrated into a CI/CD pipeline. "
                    "The entire output must exclusively use PyTorch as the deep learning framework."
                ),
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 3000,
                "temperature": 0.3,
                "auto_generate_prompt": False
            }
        ],
        "max_loops": 3,
        "swarm_type": "SequentialWorkflow"  # Sequential workflow: later agents can assume outputs from earlier ones
    }

    # The task description provides the high-level business requirement for the swarm.
    payload = {
        "task": task_description,
        "swarm": payload
    }

    response = requests.post(
        f"{BASE_URL}/swarm/completion",
        headers=headers,
        json=payload,
    )

    if response.status_code == 200:
        print("PyTorch Code Generation Swarm successfully executed!")
        return json.dumps(response.json(), indent=4)
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None

# Example business task for the swarm: generating a full-stack machine learning pipeline for image classification using PyTorch.
if __name__ == "__main__":
    task_description = (
        "Develop a full-stack machine learning pipeline for image classification using PyTorch. "
        "The project must include a deep learning model using a CNN architecture for image recognition, "
        "a comprehensive training script for data preprocessing, augmentation, training, validation, and testing, "
        "and an extensive suite of unit tests to validate every component. "
        "Each component's output must be strictly Python code with no additional text or commentary, using PyTorch exclusively."
    )

    output = create_ml_code_swarm(task_description)
    print(output)

```

--------------------------------------------------

# File: swarms/examples/swarms_dao.md

# Swarms DAO Example

This example demonstrates how to create a swarm of agents to collaborate on a task. The agents are designed to work together to create a comprehensive strategy for a DAO focused on decentralized governance for climate action.

You can customize the agents and their system prompts to fit your specific needs.

And, this example is using the `deepseek-reasoner` model, which is a large language model that is optimized for reasoning tasks.


## Todo
- Add tools to check wallet of the treasury and check the balance of the treasury
- Add tools to check the price of the token
- Add tools to check the price of the token on different exchanges
- Add tools to check the price of the token on different chains
- Add tools to check twitter posts and check the sentiment of the posts

```python
import random
from swarms import Agent

# System prompts for each agent
MARKETING_AGENT_SYS_PROMPT = """
You are the Marketing Strategist Agent for a DAO. Your role is to develop, implement, and optimize all marketing and branding strategies to align with the DAO's mission and vision. The DAO is focused on decentralized governance for climate action, funding projects aimed at reducing carbon emissions, and incentivizing community participation through its native token.

### Objectives:
1. **Brand Awareness**: Build a globally recognized and trusted brand for the DAO.
2. **Community Growth**: Expand the DAO's community by onboarding individuals passionate about climate action and blockchain technology.
3. **Campaign Execution**: Launch high-impact marketing campaigns on platforms like Twitter, Discord, and YouTube to engage and retain community members.
4. **Partnerships**: Identify and build partnerships with like-minded organizations, NGOs, and influencers.
5. **Content Strategy**: Design educational and engaging content, including infographics, blog posts, videos, and AMAs.

### Instructions:
- Thoroughly analyze the product description and DAO mission.
- Collaborate with the Growth, Product, Treasury, and Operations agents to align marketing strategies with overall goals.
- Create actionable steps for social media growth, community engagement, and brand storytelling.
- Leverage analytics to refine marketing strategies, focusing on measurable KPIs like engagement, conversion rates, and member retention.
- Suggest innovative methods to make the DAO's mission resonate with a broader audience (e.g., gamified incentives, contests, or viral campaigns).
- Ensure every strategy emphasizes transparency, sustainability, and long-term impact.
"""

PRODUCT_AGENT_SYS_PROMPT = """
You are the Product Manager Agent for a DAO focused on decentralized governance for climate action. Your role is to design, manage, and optimize the DAO's product roadmap. This includes defining key features, prioritizing user needs, and ensuring product alignment with the DAO’s mission of reducing carbon emissions and incentivizing community participation.

### Objectives:
1. **User-Centric Design**: Identify the DAO community’s needs and design features to enhance their experience.
2. **Roadmap Prioritization**: Develop a prioritized product roadmap based on community feedback and alignment with climate action goals.
3. **Integration**: Suggest technical solutions and tools for seamless integration with other platforms and blockchains.
4. **Continuous Improvement**: Regularly evaluate product features and recommend optimizations to improve usability, engagement, and adoption.

### Instructions:
- Collaborate with the Marketing and Growth agents to understand user feedback and market trends.
- Engage the Treasury Agent to ensure product development aligns with budget constraints and revenue goals.
- Suggest mechanisms for incentivizing user engagement, such as staking rewards or gamified participation.
- Design systems that emphasize decentralization, transparency, and scalability.
- Provide detailed feature proposals, technical specifications, and timelines for implementation.
- Ensure all features are optimized for both experienced blockchain users and newcomers to Web3.
"""

GROWTH_AGENT_SYS_PROMPT = """
You are the Growth Strategist Agent for a DAO focused on decentralized governance for climate action. Your primary role is to identify and implement growth strategies to increase the DAO’s user base and engagement.

### Objectives:
1. **User Acquisition**: Identify effective strategies to onboard more users to the DAO.
2. **Retention**: Suggest ways to improve community engagement and retain active members.
3. **Data-Driven Insights**: Leverage data analytics to identify growth opportunities and areas of improvement.
4. **Collaborative Growth**: Work with other agents to align growth efforts with marketing, product development, and treasury goals.

### Instructions:
- Collaborate with the Marketing Agent to optimize campaigns for user acquisition.
- Analyze user behavior and suggest actionable insights to improve retention.
- Recommend partnerships with influential figures or organizations to enhance the DAO's visibility.
- Propose growth experiments (A/B testing, new incentives, etc.) and analyze their effectiveness.
- Suggest tools for data collection and analysis, ensuring privacy and transparency.
- Ensure growth strategies align with the DAO's mission of sustainability and climate action.
"""

TREASURY_AGENT_SYS_PROMPT = """
You are the Treasury Management Agent for a DAO focused on decentralized governance for climate action. Your role is to oversee the DAO's financial operations, including budgeting, funding allocation, and financial reporting.

### Objectives:
1. **Financial Transparency**: Maintain clear and detailed reports of the DAO's financial status.
2. **Budget Management**: Allocate funds strategically to align with the DAO's goals and priorities.
3. **Fundraising**: Identify and recommend strategies for fundraising to ensure the DAO's financial sustainability.
4. **Cost Optimization**: Suggest ways to reduce operational costs without sacrificing quality.

### Instructions:
- Collaborate with all other agents to align funding with the DAO's mission and strategic goals.
- Propose innovative fundraising campaigns (e.g., NFT drops, token sales) to generate revenue.
- Analyze financial risks and suggest mitigation strategies.
- Ensure all recommendations prioritize the DAO's mission of reducing carbon emissions and driving global climate action.
- Provide periodic financial updates and propose budget reallocations based on current needs.
"""

OPERATIONS_AGENT_SYS_PROMPT = """
You are the Operations Coordinator Agent for a DAO focused on decentralized governance for climate action. Your role is to ensure smooth day-to-day operations, coordinate workflows, and manage governance processes.

### Objectives:
1. **Workflow Optimization**: Streamline operational processes to maximize efficiency and effectiveness.
2. **Task Coordination**: Manage and delegate tasks to ensure timely delivery of goals.
3. **Governance**: Oversee governance processes, including proposal management and voting mechanisms.
4. **Communication**: Ensure seamless communication between all agents and community members.

### Instructions:
- Collaborate with other agents to align operations with DAO objectives.
- Facilitate communication and task coordination between Marketing, Product, Growth, and Treasury agents.
- Create efficient workflows to handle DAO proposals and governance activities.
- Suggest tools or platforms to improve operational efficiency.
- Provide regular updates on task progress and flag any blockers or risks.
"""

# Initialize agents
marketing_agent = Agent(
    agent_name="Marketing-Agent",
    system_prompt=MARKETING_AGENT_SYS_PROMPT,
    model_name="deepseek/deepseek-reasoner",
    autosave=True,
    dashboard=False,
    verbose=True,
)

product_agent = Agent(
    agent_name="Product-Agent",
    system_prompt=PRODUCT_AGENT_SYS_PROMPT,
    model_name="deepseek/deepseek-reasoner",
    autosave=True,
    dashboard=False,
    verbose=True,
)

growth_agent = Agent(
    agent_name="Growth-Agent",
    system_prompt=GROWTH_AGENT_SYS_PROMPT,
    model_name="deepseek/deepseek-reasoner",
    autosave=True,
    dashboard=False,
    verbose=True,
)

treasury_agent = Agent(
    agent_name="Treasury-Agent",
    system_prompt=TREASURY_AGENT_SYS_PROMPT,
    model_name="deepseek/deepseek-reasoner",
    autosave=True,
    dashboard=False,
    verbose=True,
)

operations_agent = Agent(
    agent_name="Operations-Agent",
    system_prompt=OPERATIONS_AGENT_SYS_PROMPT,
    model_name="deepseek/deepseek-reasoner",
    autosave=True,
    dashboard=False,
    verbose=True,
)

agents = [marketing_agent, product_agent, growth_agent, treasury_agent, operations_agent]


class DAOSwarmRunner:
    """
    A class to manage and run a swarm of agents in a discussion.
    """

    def __init__(self, agents: list, max_loops: int = 5, shared_context: str = "") -> None:
        """
        Initializes the DAO Swarm Runner.

        Args:
            agents (list): A list of agents in the swarm.
            max_loops (int, optional): The maximum number of discussion loops between agents. Defaults to 5.
            shared_context (str, optional): The shared context for all agents to base their discussion on. Defaults to an empty string.
        """
        self.agents = agents
        self.max_loops = max_loops
        self.shared_context = shared_context
        self.discussion_history = []

    def run(self, task: str) -> str:
        """
        Runs the swarm in a random discussion.

        Args:
            task (str): The task or context that agents will discuss.

        Returns:
            str: The final discussion output after all loops.
        """
        print(f"Task: {task}")
        print("Initializing Random Discussion...")
        
        # Initialize the discussion with the shared context
        current_message = f"Task: {task}\nContext: {self.shared_context}"
        self.discussion_history.append(current_message)

        # Run the agents in a randomized discussion
        for loop in range(self.max_loops):
            print(f"\n--- Loop {loop + 1}/{self.max_loops} ---")
            # Choose a random agent
            agent = random.choice(self.agents)
            print(f"Agent {agent.agent_name} is responding...")

            # Run the agent and get a response
            response = agent.run(current_message)
            print(f"Agent {agent.agent_name} says:\n{response}\n")

            # Append the response to the discussion history
            self.discussion_history.append(f"{agent.agent_name}: {response}")

            # Update the current message for the next agent
            current_message = response

        print("\n--- Discussion Complete ---")
        return "\n".join(self.discussion_history)


swarm = DAOSwarmRunner(agents=agents, max_loops=1, shared_context="")

# User input for product description
product_description = """
The DAO is focused on decentralized governance for climate action. 
It funds projects aimed at reducing carbon emissions and incentivizes community participation with a native token.
"""

# Assign a shared context for all agents
swarm.shared_context = product_description

# Run the swarm
task = """
Analyze the product description and create a collaborative strategy for marketing, product, growth, treasury, and operations. Ensure all recommendations align with the DAO's mission of reducing carbon emissions.
"""
output = swarm.run(task)

# Print the swarm output
print("Collaborative Strategy Output:\n", output)

```

--------------------------------------------------

# File: swarms/examples/swarms_of_browser_agents.md

# Swarms x Browser Use

- Import required modules

- Configure your agent first by making a new class

- Set your api keys for your model provider in the `.env` file such as `OPENAI_API_KEY="sk-"`

- Conigure your `ConcurrentWorkflow`

## Install

```bash
pip install swarms browser-use langchain-openai
```
--------


## Main
```python
import asyncio

from browser_use import Agent
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

from swarms import ConcurrentWorkflow

load_dotenv()


class BrowserAgent:
    def __init__(self, agent_name: str = "BrowserAgent"):
        self.agent_name = agent_name

    async def browser_agent_test(self, task: str):
        agent = Agent(
            task=task,
            llm=ChatOpenAI(model="gpt-4o"),
        )
        result = await agent.run()
        return result

    def run(self, task: str):
        return asyncio.run(self.browser_agent_test(task))


swarm = ConcurrentWorkflow(
    agents=[BrowserAgent() for _ in range(3)],
)

swarm.run(
    """
    Go to pump.fun.
    
    2. Make an account: use email: "test@test.com" and password: "test1234"
    
    3. Make a coin called and give it a cool description and etc. Fill in the form
    
    4. Sit back and watch the coin grow in value.
    
    """
)

```

--------------------------------------------------

# File: swarms/examples/swarms_tools_htx.md

# Swarms Tools Example with HTX + CoinGecko

- `pip3 install swarms swarms-tools`
- Add `OPENAI_API_KEY` to your `.env` file

```python
from swarms import Agent
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)
from swarms_tools import (
    coin_gecko_coin_api,
    fetch_htx_data,
)


# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Personal finance advisor agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    max_loops=1,
    model_name="gpt-4o",
    dynamic_temperature_enabled=True,
    user_name="swarms_corp",
    return_step_meta=False,
    output_type="str",  # "json", "dict", "csv" OR "string" "yaml" and
    auto_generate_prompt=False,  # Auto generate prompt for the agent based on name, description, and system prompt, task
    max_tokens=4000,  # max output tokens
    saved_state_path="agent_00.json",
    interactive=False,
)

agent.run(
    f"Analyze the $swarms token on HTX with data: {fetch_htx_data('swarms')}. Additionally, consider the following CoinGecko data: {coin_gecko_coin_api('swarms')}"
)
```

--------------------------------------------------

# File: swarms/examples/swarms_tools_htx_gecko.md

# Swarms Tools Example with HTX + CoinGecko

- `pip3 install swarms swarms-tools`
- Add `OPENAI_API_KEY` to your `.env` file
- Run `swarms_tools_htx_gecko.py`
- Agent will make a function call to the desired tool
- The tool will be executed and the result will be returned to the agent
- The agent will then analyze the result and return the final output


```python
from swarms import Agent
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)
from swarms_tools import (
    fetch_stock_news,
    coin_gecko_coin_api,
    fetch_htx_data,
)

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Personal finance advisor agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    max_loops=1,
    model_name="gpt-4o",
    dynamic_temperature_enabled=True,
    user_name="swarms_corp",
    retry_attempts=3,
    context_length=8192,
    return_step_meta=False,
    output_type="str",  # "json", "dict", "csv" OR "string" "yaml" and
    auto_generate_prompt=False,  # Auto generate prompt for the agent based on name, description, and system prompt, task
    max_tokens=4000,  # max output tokens
    saved_state_path="agent_00.json",
    interactive=False,
    tools=[fetch_stock_news, coin_gecko_coin_api, fetch_htx_data],
)

agent.run("Analyze the $swarms token on htx")
```

--------------------------------------------------

# File: swarms/examples/templates_index.md

# The Swarms Index

The Swarms Index is a comprehensive catalog of repositories under The Swarm Corporation, showcasing a wide array of tools, frameworks, and templates designed for building, deploying, and managing autonomous AI agents and multi-agent systems. These repositories focus on enterprise-grade solutions, spanning industries like healthcare, finance, marketing, and more, with an emphasis on scalability, security, and performance. Many repositories include templates to help developers quickly set up production-ready applications.

| Name | Description | Link |
|------|-------------|------|
| Phala-Deployment-Template | A guide and template for running Swarms Agents in a Trusted Execution Environment (TEE) using Phala Cloud, ensuring secure and isolated execution. | [https://github.com/The-Swarm-Corporation/Phala-Deployment-Template](https://github.com/The-Swarm-Corporation/Phala-Deployment-Template) |
| Swarms-API-Status-Page | A status page for monitoring the health and performance of the Swarms API. | [https://github.com/The-Swarm-Corporation/Swarms-API-Status-Page](https://github.com/The-Swarm-Corporation/Swarms-API-Status-Page) |
| Swarms-API-Phala-Template | A deployment solution template for running Swarms API on Phala Cloud, optimized for secure and scalable agent orchestration. | [https://github.com/The-Swarm-Corporation/Swarms-API-Phala-Template](https://github.com/The-Swarm-Corporation/Swarms-API-Phala-Template) |
| DevSwarm | Develop production-grade applications effortlessly with a single prompt, powered by a swarm of v0-driven autonomous agents operating 24/7 for fully autonomous software development. | [https://github.com/The-Swarm-Corporation/DevSwarm](https://github.com/The-Swarm-Corporation/DevSwarm) |
| Enterprise-Grade-Agents-Course | A comprehensive course teaching students to build, deploy, and manage autonomous agents for enterprise workflows using the Swarms library, focusing on scalability and integration. | [https://github.com/The-Swarm-Corporation/Enterprise-Grade-Agents-Course](https://github.com/The-Swarm-Corporation/Enterprise-Grade-Agents-Course) |
| agentverse | A collection of agents from top frameworks like Langchain, Griptape, and CrewAI, integrated into the Swarms ecosystem. | [https://github.com/The-Swarm-Corporation/agentverse](https://github.com/The-Swarm-Corporation/agentverse) |
| InsuranceSwarm | A swarm of agents to automate document processing and fraud detection in insurance claims. | [https://github.com/The-Swarm-Corporation/InsuranceSwarm](https://github.com/The-Swarm-Corporation/InsuranceSwarm) |
| swarms-examples | A vast array of examples for enterprise-grade and production-ready applications using the Swarms framework. | [https://github.com/The-Swarm-Corporation/swarms-examples](https://github.com/The-Swarm-Corporation/swarms-examples) |
| auto-ai-research-team | Automates AI research at an OpenAI level to accelerate innovation using swarms of agents. | [https://github.com/The-Swarm-Corporation/auto-ai-research-team](https://github.com/The-Swarm-Corporation/auto-ai-research-team) |
| Agents-Beginner-Guide | A definitive beginner's guide to AI agents and multi-agent systems, explaining fundamentals and industry applications. | [https://github.com/The-Swarm-Corporation/Agents-Beginner-Guide](https://github.com/The-Swarm-Corporation/Agents-Beginner-Guide) |
| Solana-Ecosystem-MCP | A collection of Solana tools wrapped in MCP servers for blockchain development. | [https://github.com/The-Swarm-Corporation/Solana-Ecosystem-MCP](https://github.com/The-Swarm-Corporation/Solana-Ecosystem-MCP) |
| automated-crypto-fund | A fully automated crypto fund leveraging swarms of LLM agents for real-money trading. | [https://github.com/The-Swarm-Corporation/automated-crypto-fund](https://github.com/The-Swarm-Corporation/automated-crypto-fund) |
| Mryaid | The first multi-agent social media platform powered by Swarms. | [https://github.com/The-Swarm-Corporation/Mryaid](https://github.com/The-Swarm-Corporation/Mryaid) |
| pharma-swarm | A swarm of autonomous agents for chemical analysis in the pharmaceutical industry. | [https://github.com/The-Swarm-Corporation/pharma-swarm](https://github.com/The-Swarm-Corporation/pharma-swarm) |
| Automated-Prompt-Engineering-Hub | A hub for tools and resources focused on automated prompt engineering for generative AI. | [https://github.com/The-Swarm-Corporation/Automated-Prompt-Engineering-Hub](https://github.com/The-Swarm-Corporation/Automated-Prompt-Engineering-Hub) |
| Multi-Agent-Template-App | A simple, reliable, and high-performance template for building multi-agent applications. | [https://github.com/The-Swarm-Corporation/Multi-Agent-Template-App](https://github.com/The-Swarm-Corporation/Multi-Agent-Template-App) |
| Cookbook | Examples and guides for using the Swarms Framework effectively. | [https://github.com/The-Swarm-Corporation/Cookbook](https://github.com/The-Swarm-Corporation/Cookbook) |
| SwarmDB | A production-grade message queue system for agent communication and LLM backend load balancing. | [https://github.com/The-Swarm-Corporation/SwarmDB](https://github.com/The-Swarm-Corporation/SwarmDB) |
| CryptoTaxSwarm | A personal advisory tax swarm for cryptocurrency transactions. | [https://github.com/The-Swarm-Corporation/CryptoTaxSwarm](https://github.com/The-Swarm-Corporation/CryptoTaxSwarm) |
| Multi-Agent-Marketing-Course | A course on automating marketing operations with enterprise-grade multi-agent collaboration. | [https://github.com/The-Swarm-Corporation/Multi-Agent-Marketing-Course](https://github.com/The-Swarm-Corporation/Multi-Agent-Marketing-Course) |
| Swarms-BrandBook | Branding guidelines and assets for Swarms.ai, embodying innovation and collaboration. | [https://github.com/The-Swarm-Corporation/Swarms-BrandBook](https://github.com/The-Swarm-Corporation/Swarms-BrandBook) |
| AgentAPI | A definitive API for managing and interacting with AI agents. | [https://github.com/The-Swarm-Corporation/AgentAPI](https://github.com/The-Swarm-Corporation/AgentAPI) |
| Research-Paper-Writer-Swarm | Automates the creation of high-quality research papers in LaTeX using Swarms agents. | [https://github.com/The-Swarm-Corporation/Research-Paper-Writer-Swarm](https://github.com/The-Swarm-Corporation/Research-Paper-Writer-Swarm) |
| swarms-sdk | A Python client for the Swarms API, providing a simple interface for managing AI swarms. | [https://github.com/The-Swarm-Corporation/swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) |
| FluidAPI | A framework for interacting with APIs using natural language, simplifying complex requests. | [https://github.com/The-Swarm-Corporation/FluidAPI](https://github.com/The-Swarm-Corporation/FluidAPI) |
| MedicalCoderSwarm | A multi-agent system for comprehensive medical diagnosis and coding using specialized AI agents. | [https://github.com/The-Swarm-Corporation/MedicalCoderSwarm](https://github.com/The-Swarm-Corporation/MedicalCoderSwarm) |
| BackTesterAgent | An AI-powered backtesting framework for automated trading strategy validation and optimization. | [https://github.com/The-Swarm-Corporation/BackTesterAgent](https://github.com/The-Swarm-Corporation/BackTesterAgent) |
| .ai | The first natural language programming language powered by Swarms. | [https://github.com/The-Swarm-Corporation/.ai](https://github.com/The-Swarm-Corporation/.ai) |
| AutoHedge | An autonomous hedge fund leveraging swarm intelligence for market analysis and trade execution. | [https://github.com/The-Swarm-Corporation/AutoHedge](https://github.com/The-Swarm-Corporation/AutoHedge) |
| radiology-swarm | A multi-agent system for advanced radiological analysis, diagnosis, and treatment planning. | [https://github.com/The-Swarm-Corporation/radiology-swarm](https://github.com/The-Swarm-Corporation/radiology-swarm) |
| MedGuard | A Python library ensuring HIPAA compliance for LLM agents in healthcare applications. | [https://github.com/The-Swarm-Corporation/MedGuard](https://github.com/The-Swarm-Corporation/MedGuard) |
| doc-master | A lightweight Python library for automated file reading and content extraction. | [https://github.com/The-Swarm-Corporation/doc-master](https://github.com/The-Swarm-Corporation/doc-master) |
| Open-Aladdin | An open-source risk-management tool for stock and security risk analysis. | [https://github.com/The-Swarm-Corporation/Open-Aladdin](https://github.com/The-Swarm-Corporation/Open-Aladdin) |
| TickrAgent | A scalable Python library for building financial agents for comprehensive stock analysis. | [https://github.com/The-Swarm-Corporation/TickrAgent](https://github.com/The-Swarm-Corporation/TickrAgent) |
| NewsAgent | An enterprise-grade news aggregation agent for fetching, querying, and summarizing news. | [https://github.com/The-Swarm-Corporation/NewsAgent](https://github.com/The-Swarm-Corporation/NewsAgent) |
| Research-Paper-Hive | A platform for discovering and engaging with relevant research papers efficiently. | [https://github.com/The-Swarm-Corporation/Research-Paper-Hive](https://github.com/The-Swarm-Corporation/Research-Paper-Hive) |
| MedInsight-Pro | Revolutionizes medical research summarization for healthcare innovators. | [https://github.com/The-Swarm-Corporation/MedInsight-Pro](https://github.com/The-Swarm-Corporation/MedInsight-Pro) |
| swarms-memory | Pre-built wrappers for RAG systems like ChromaDB, Weaviate, and Pinecone. | [https://github.com/The-Swarm-Corporation/swarms-memory](https://github.com/The-Swarm-Corporation/swarms-memory) |
| CryptoAgent | An enterprise-grade solution for fetching, analyzing, and summarizing cryptocurrency data. | [https://github.com/The-Swarm-Corporation/CryptoAgent](https://github.com/The-Swarm-Corporation/CryptoAgent) |
| AgentParse | A high-performance parsing library for mapping structured data into agent-understandable blocks. | [https://github.com/The-Swarm-Corporation/AgentParse](https://github.com/The-Swarm-Corporation/AgentParse) |
| CodeGuardian | An intelligent agent for automating the generation of production-grade unit tests for Python code. | [https://github.com/The-Swarm-Corporation/CodeGuardian](https://github.com/The-Swarm-Corporation/CodeGuardian) |
| Marketing-Swarm-Template | A framework for creating multi-platform marketing content using Swarms AI agents. | [https://github.com/The-Swarm-Corporation/Marketing-Swarm-Template](https://github.com/The-Swarm-Corporation/Marketing-Swarm-Template) |
| HTX-Swarm | A multi-agent system for real-time market analysis of HTX exchange data. | [https://github.com/The-Swarm-Corporation/HTX-Swarm](https://github.com/The-Swarm-Corporation/HTX-Swarm) |
| MultiModelOptimizer | A hierarchical parameter synchronization approach for joint training of transformer models. | [https://github.com/The-Swarm-Corporation/MultiModelOptimizer](https://github.com/The-Swarm-Corporation/MultiModelOptimizer) |
| MortgageUnderwritingSwarm | A multi-agent pipeline for automating mortgage underwriting processes. | [https://github.com/The-Swarm-Corporation/MortgageUnderwritingSwarm](https://github.com/The-Swarm-Corporation/MortgageUnderwritingSwarm) |
| DermaSwarm | A multi-agent system for dermatologists to diagnose and treat skin conditions collaboratively. | [https://github.com/The-Swarm-Corporation/DermaSwarm](https://github.com/The-Swarm-Corporation/DermaSwarm) |
| IoTAgents | Integrates IoT data with AI agents for seamless parsing and processing of data streams. | [https://github.com/The-Swarm-Corporation/IoTAgents](https://github.com/The-Swarm-Corporation/IoTAgents) |
| eth-agent | An autonomous agent for analyzing on-chain Ethereum data. | [https://github.com/The-Swarm-Corporation/eth-agent](https://github.com/The-Swarm-Corporation/eth-agent) |
| Medical-Swarm-One-Click | A template for building safe, reliable, and production-grade medical multi-agent systems. | [https://github.com/The-Swarm-Corporation/Medical-Swarm-One-Click](https://github.com/The-Swarm-Corporation/Medical-Swarm-One-Click) |
| Swarms-Example-1-Click-Template | A one-click template for building Swarms applications quickly. | [https://github.com/The-Swarm-Corporation/Swarms-Example-1-Click-Template](https://github.com/The-Swarm-Corporation/Swarms-Example-1-Click-Template) |
| Custom-Swarms-Spec-Template | An official specification template for custom swarm development using the Swarms Framework. | [https://github.com/The-Swarm-Corporation/Custom-Swarms-Spec-Template](https://github.com/The-Swarm-Corporation/Custom-Swarms-Spec-Template) |
| Swarms-LlamaIndex-RAG-Template | A template for integrating Llama Index into Swarms applications for RAG capabilities. | [https://github.com/The-Swarm-Corporation/Swarms-LlamaIndex-RAG-Template](https://github.com/The-Swarm-Corporation/Swarms-LlamaIndex-RAG-Template) |
| ForexTreeSwarm | A forex market analysis system using a swarm of AI agents organized in a forest structure. | [https://github.com/The-Swarm-Corporation/ForexTreeSwarm](https://github.com/The-Swarm-Corporation/ForexTreeSwarm) |
| Generalist-Mathematician-Swarm | A swarm of agents for solving complex mathematical problems collaboratively. | [https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm](https://github.com/The-Swarm-Corporation/Generalist-Mathematician-Swarm) |
| Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template | A template for analyzing X-rays, MRIs, and more using a swarm of agents. | [https://github.com/The-Swarm-Corporation/Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template](https://github.com/The-Swarm-Corporation/Multi-Modal-XRAY-Diagnosis-Medical-Swarm-Template) |
| AgentRAGProtocol | A protocol for integrating Retrieval-Augmented Generation (RAG) into AI agents. | [https://github.com/The-Swarm-Corporation/AgentRAGProtocol](https://github.com/The-Swarm-Corporation/AgentRAGProtocol) |
| Multi-Agent-RAG-Template | A template for creating collaborative AI agent teams for document processing and analysis. | [https://github.com/The-Swarm-Corporation/Multi-Agent-RAG-Template](https://github.com/The-Swarm-Corporation/Multi-Agent-RAG-Template) |
| REACT-Yaml-Agent | An implementation of a REACT agent using YAML instead of JSON. | [https://github.com/The-Swarm-Corporation/REACT-Yaml-Agent](https://github.com/The-Swarm-Corporation/REACT-Yaml-Agent) |
| SwarmsXGCP | A template for deploying Swarms agents on Google Cloud Run. | [https://github.com/The-Swarm-Corporation/SwarmsXGCP](https://github.com/The-Swarm-Corporation/SwarmsXGCP) |
| Legal-Swarm-Template | A one-click template for building legal-focused Swarms applications. | [https://github.com/The-Swarm-Corporation/Legal-Swarm-Template](https://github.com/The-Swarm-Corporation/Legal-Swarm-Template) |
| swarms_sim | A simulation of a swarm of agents in a professional workplace environment. | [https://github.com/The-Swarm-Corporation/swarms_sim](https://github.com/The-Swarm-Corporation/swarms_sim) |
| medical-problems | A repository for medical problems to create Swarms applications for. | [https://github.com/The-Swarm-Corporation/medical-problems](https://github.com/The-Swarm-Corporation/medical-problems) |
| swarm-ecosystem | An overview of the Swarm Ecosystem and its components. | [https://github.com/The-Swarm-Corporation/swarm-ecosystem](https://github.com/The-Swarm-Corporation/swarm-ecosystem) |
| swarms_ecosystem_md | MDX documentation for the Swarm Ecosystem. | [https://github.com/The-Swarm-Corporation/swarms_ecosystem_md](https://github.com/The-Swarm-Corporation/swarms_ecosystem_md) |
| Hierarchical Swarm Examples | Simple, practical examples of HierarchicalSwarm usage for various real-world scenarios. | [Documentation](hierarchical_swarm_example.md) |




--------------------------------------------------

# File: swarms/examples/unique_swarms.md


In this section, we present a diverse collection of unique swarms, each with its own distinct characteristics and applications. These examples are designed to illustrate the versatility and potential of swarm intelligence in various domains. By exploring these examples, you can gain a deeper understanding of how swarms can be leveraged to solve complex problems and improve decision-making processes.

# Documentation

## Table of Contents
1. [Common Parameters](#common-parameters)
2. [Basic Swarm Patterns](#basic-swarm-patterns)
3. [Mathematical Swarm Patterns](#mathematical-swarm-patterns)
4. [Advanced Swarm Patterns](#advanced-swarm-patterns)
5. [Communication Patterns](#communication-patterns)
6. [Best Practices](#best-practices)
7. [Common Use Cases](#common-use-cases)

## Common Parameters

All swarm architectures accept these base parameters:

- `agents: AgentListType` - List of Agent objects to participate in the swarm
- `tasks: List[str]` - List of tasks to be processed by the agents
- `return_full_history: bool` (optional) - If True, returns conversation history. Defaults to True

Return types are generally `Union[dict, List[str]]`, where:
- If `return_full_history=True`: Returns a dictionary containing the full conversation history
- If `return_full_history=False`: Returns a list of agent responses

## Basic Swarm Patterns

### Circular Swarm
```python
def circular_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True)
```

**Information Flow:**
```mermaid
flowchart LR
    subgraph Circular Flow
    A1((Agent 1)) --> A2((Agent 2))
    A2 --> A3((Agent 3))
    A3 --> A4((Agent 4))
    A4 --> A1
    end
    Task1[Task 1] --> A1
    Task2[Task 2] --> A2
    Task3[Task 3] --> A3
```

**Best Used When:**

- You need continuous processing of tasks

- Tasks need to be processed by every agent in sequence

- You want predictable, ordered task distribution

**Key Features:**

- Tasks move in a circular pattern through all agents

- Each agent processes each task once

- Maintains strict ordering of task processing

### Linear Swarm
```python
def linear_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True)
```

**Information Flow:**
```mermaid
flowchart LR
    Input[Task Input] --> A1
    subgraph Sequential Processing
    A1((Agent 1)) --> A2((Agent 2))
    A2 --> A3((Agent 3))
    A3 --> A4((Agent 4))
    A4 --> A5((Agent 5))
    end
    A5 --> Output[Final Result]
```

**Best Used When:**

- Tasks need sequential, pipeline-style processing

- Each agent performs a specific transformation step

- Order of processing is critical

### Star Swarm
```python
def star_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True)
```

**Information Flow:**
```mermaid
flowchart TD
    subgraph Star Pattern
    A1((Central Agent))
    A2((Agent 2))
    A3((Agent 3))
    A4((Agent 4))
    A5((Agent 5))
    A1 --> A2
    A1 --> A3
    A1 --> A4
    A1 --> A5
    end
    Task[Initial Task] --> A1
    A2 --> Result2[Result 2]
    A3 --> Result3[Result 3]
    A4 --> Result4[Result 4]
    A5 --> Result5[Result 5]
```

**Best Used When:**

- You need centralized control

- Tasks require coordination or oversight

- You want to maintain a single point of task distribution

### Mesh Swarm
```python
def mesh_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True)
```

**Information Flow:**
```mermaid
flowchart TD
    subgraph Mesh Network
    A1((Agent 1)) <--> A2((Agent 2))
    A2 <--> A3((Agent 3))
    A1 <--> A4((Agent 4))
    A2 <--> A5((Agent 5))
    A3 <--> A6((Agent 6))
    A4 <--> A5
    A5 <--> A6
    end
    Tasks[Task Pool] --> A1
    Tasks --> A2
    Tasks --> A3
    Tasks --> A4
    Tasks --> A5
    Tasks --> A6
```

**Best Used When:**

- You need maximum flexibility

- Task processing order isn't critical

- You want fault tolerance

## Mathematical Swarm Patterns

### Fibonacci Swarm
```python
def fibonacci_swarm(agents: AgentListType, tasks: List[str])
```

**Information Flow:**
```mermaid
flowchart TD
    subgraph Fibonacci Pattern
    L1[Level 1: 1 Agent] --> L2[Level 2: 1 Agent]
    L2 --> L3[Level 3: 2 Agents]
    L3 --> L4[Level 4: 3 Agents]
    L4 --> L5[Level 5: 5 Agents]
    end
    Task[Initial Task] --> L1
    L5 --> Results[Processed Results]
```

**Best Used When:**

- You need natural scaling patterns

- Tasks have increasing complexity

- You want organic growth in processing capacity

### Pyramid Swarm
```python
def pyramid_swarm(agents: AgentListType, tasks: List[str], return_full_history: bool = True)
```

**Information Flow:**
```mermaid
flowchart TD
    subgraph Pyramid Structure
    A1((Leader Agent))
    A2((Manager 1))
    A3((Manager 2))
    A4((Worker 1))
    A5((Worker 2))
    A6((Worker 3))
    A7((Worker 4))
    A1 --> A2
    A1 --> A3
    A2 --> A4
    A2 --> A5
    A3 --> A6
    A3 --> A7
    end
    Task[Complex Task] --> A1
    A4 --> Result1[Output 1]
    A5 --> Result2[Output 2]
    A6 --> Result3[Output 3]
    A7 --> Result4[Output 4]
```

**Best Used When:**

- You need hierarchical task processing

- Tasks require multiple levels of oversight

- You want organized task delegation

### Grid Swarm
```python
def grid_swarm(agents: AgentListType, tasks: List[str])
```

**Information Flow:**
```mermaid
flowchart TD
    subgraph Grid Layout
    A1((1)) <--> A2((2)) <--> A3((3))
    A4((4)) <--> A5((5)) <--> A6((6))
    A7((7)) <--> A8((8)) <--> A9((9))
    A1 <--> A4 <--> A7
    A2 <--> A5 <--> A8
    A3 <--> A6 <--> A9
    end
    Tasks[Task Queue] --> A1
    Tasks --> A5
    Tasks --> A9
```

**Best Used When:**

- Tasks have spatial relationships

- You need neighbor-based processing

- You want structured parallel processing

## Communication Patterns

### One-to-One Communication
```python
def one_to_one(sender: Agent, receiver: Agent, task: str, max_loops: int = 1) -> str
```

**Information Flow:**
```mermaid
flowchart LR
    Task[Task] --> S((Sender))
    S --> R((Receiver))
    R --> Result[Result]
```

**Best Used When:**

- Direct agent communication is needed

- Tasks require back-and-forth interaction

- You need controlled message exchange

### Broadcast Communication
```python
async def broadcast(sender: Agent, agents: AgentListType, task: str) -> None
```

**Information Flow:**
```mermaid
flowchart TD
    T[Task] --> S((Sender))
    S --> A1((Agent 1))
    S --> A2((Agent 2))
    S --> A3((Agent 3))
    S --> A4((Agent 4))
```

**Best Used When:**

- Information needs to reach all agents

- Tasks require global coordination

- You need system-wide updates

## Best Practices

1. **Choose the Right Pattern:**
   - Consider your task's natural structure
   - Think about scaling requirements
   - Consider fault tolerance needs

2. **Performance Considerations:**
   - More complex patterns have higher overhead
   - Consider communication costs
   - Match pattern to available resources

3. **Error Handling:**
   - All patterns include basic error checking
   - Consider adding additional error handling for production
   - Monitor agent performance and task completion

4. **Scaling:**
   - Different patterns scale differently
   - Consider future growth needs
   - Test with expected maximum load

## Common Use Cases

1. **Data Processing Pipelines**
   - Linear Swarm
   - Circular Swarm

2. **Distributed Computing**
   - Mesh Swarm
   - Grid Swarm

3. **Hierarchical Systems**
   - Pyramid Swarm
   - Star Swarm

4. **Dynamic Workloads**
   - Exponential Swarm
   - Fibonacci Swarm

5. **Conflict-Free Processing**
   - Prime Swarm
   - Harmonic Swarm


```python
import asyncio
from typing import List

from swarms.structs.agent import Agent
from swarms.structs.swarming_architectures import (
    broadcast,
    circular_swarm,
    exponential_swarm,
    fibonacci_swarm,
    grid_swarm,
    linear_swarm,
    mesh_swarm,
    one_to_three,
    prime_swarm,
    sigmoid_swarm,
    sinusoidal_swarm,
    staircase_swarm,
    star_swarm,
)


def create_finance_agents() -> List[Agent]:
    """Create specialized finance agents"""
    return [
        Agent(
            agent_name="MarketAnalyst",
            system_prompt="You are a market analysis expert. Analyze market trends and provide insights.",
            model_name="gpt-4o-mini"
        ),
        Agent(
            agent_name="RiskManager",
            system_prompt="You are a risk management specialist. Evaluate risks and provide mitigation strategies.",
            model_name="gpt-4o-mini"
        ),
        Agent(
            agent_name="PortfolioManager",
            system_prompt="You are a portfolio management expert. Optimize investment portfolios and asset allocation.",
            model_name="gpt-4o-mini"
        ),
        Agent(
            agent_name="ComplianceOfficer",
            system_prompt="You are a financial compliance expert. Ensure regulatory compliance and identify issues.",
            model_name="gpt-4o-mini"
        )
    ]

def create_healthcare_agents() -> List[Agent]:
    """Create specialized healthcare agents"""
    return [
        Agent(
            agent_name="Diagnostician",
            system_prompt="You are a medical diagnostician. Analyze symptoms and suggest potential diagnoses.",
            model_name="gpt-4o-mini"
        ),
        Agent(
            agent_name="Treatment_Planner",
            system_prompt="You are a treatment planning specialist. Develop comprehensive treatment plans.",
            model_name="gpt-4o-mini"
        ),
        Agent(
            agent_name="MedicalResearcher",
            system_prompt="You are a medical researcher. Analyze latest research and provide evidence-based recommendations.",
            model_name="gpt-4o-mini"
        ),
        Agent(
            agent_name="PatientCareCoordinator",
            system_prompt="You are a patient care coordinator. Manage patient care workflow and coordination.",
            model_name="gpt-4o-mini"
        )
    ]

def print_separator():
    print("\n" + "="*50 + "\n")

def run_finance_circular_swarm():
    """Investment analysis workflow using circular swarm"""
    print_separator()
    print("FINANCE - INVESTMENT ANALYSIS (Circular Swarm)")
    
    agents = create_finance_agents()
    tasks = [
        "Analyze Tesla stock performance for Q4 2024",
        "Assess market risks and potential hedging strategies",
        "Recommend portfolio adjustments based on analysis"
    ]
    
    print("\nTasks:")
    for i, task in enumerate(tasks, 1):
        print(f"{i}. {task}")
    
    result = circular_swarm(agents, tasks)
    print("\nResults:")
    for log in result['history']:
        print(f"\n{log['agent_name']}:")
        print(f"Task: {log['task']}")
        print(f"Response: {log['response']}")

def run_healthcare_grid_swarm():
    """Patient diagnosis and treatment planning using grid swarm"""
    print_separator()
    print("HEALTHCARE - PATIENT DIAGNOSIS (Grid Swarm)")
    
    agents = create_healthcare_agents()
    tasks = [
        "Review patient symptoms: fever, fatigue, joint pain",
        "Research latest treatment protocols",
        "Develop preliminary treatment plan",
        "Coordinate with specialists"
    ]
    
    print("\nTasks:")
    for i, task in enumerate(tasks, 1):
        print(f"{i}. {task}")
        
    result = grid_swarm(agents, tasks)
    print("\nGrid swarm processing completed")
    print(result)

def run_finance_linear_swarm():
    """Loan approval process using linear swarm"""
    print_separator()
    print("FINANCE - LOAN APPROVAL PROCESS (Linear Swarm)")
    
    agents = create_finance_agents()[:3]
    tasks = [
        "Review loan application and credit history",
        "Assess risk factors and compliance requirements",
        "Generate final loan recommendation"
    ]
    
    print("\nTasks:")
    for i, task in enumerate(tasks, 1):
        print(f"{i}. {task}")
    
    result = linear_swarm(agents, tasks)
    print("\nResults:")
    for log in result['history']:
        print(f"\n{log['agent_name']}:")
        print(f"Task: {log['task']}")
        print(f"Response: {log['response']}")

def run_healthcare_star_swarm():
    """Complex medical case management using star swarm"""
    print_separator()
    print("HEALTHCARE - COMPLEX CASE MANAGEMENT (Star Swarm)")
    
    agents = create_healthcare_agents()
    tasks = [
        "Complex case: Patient with multiple chronic conditions",
        "Develop integrated care plan"
    ]
    
    print("\nTasks:")
    for i, task in enumerate(tasks, 1):
        print(f"{i}. {task}")
    
    result = star_swarm(agents, tasks)
    print("\nResults:")
    for log in result['history']:
        print(f"\n{log['agent_name']}:")
        print(f"Task: {log['task']}")
        print(f"Response: {log['response']}")

def run_finance_mesh_swarm():
    """Market risk assessment using mesh swarm"""
    print_separator()
    print("FINANCE - MARKET RISK ASSESSMENT (Mesh Swarm)")
    
    agents = create_finance_agents()
    tasks = [
        "Analyze global market conditions",
        "Assess currency exchange risks",
        "Evaluate sector-specific risks",
        "Review portfolio exposure"
    ]
    
    print("\nTasks:")
    for i, task in enumerate(tasks, 1):
        print(f"{i}. {task}")
    
    result = mesh_swarm(agents, tasks)
    print("\nResults:")
    for log in result['history']:
        print(f"\n{log['agent_name']}:")
        print(f"Task: {log['task']}")
        print(f"Response: {log['response']}")

def run_mathematical_finance_swarms():
    """Complex financial analysis using mathematical swarms"""
    print_separator()
    print("FINANCE - MARKET PATTERN ANALYSIS")
    
    agents = create_finance_agents()
    tasks = [
        "Analyze historical market patterns",
        "Predict market trends using technical analysis",
        "Identify potential arbitrage opportunities"
    ]
    
    print("\nTasks:")
    for i, task in enumerate(tasks, 1):
        print(f"{i}. {task}")
    
    print("\nFibonacci Swarm Results:")
    result = fibonacci_swarm(agents, tasks.copy())
    print(result)
    
    print("\nPrime Swarm Results:")
    result = prime_swarm(agents, tasks.copy())
    print(result)
    
    print("\nExponential Swarm Results:")
    result = exponential_swarm(agents, tasks.copy())
    print(result)

def run_healthcare_pattern_swarms():
    """Patient monitoring using pattern swarms"""
    print_separator()
    print("HEALTHCARE - PATIENT MONITORING PATTERNS")
    
    agents = create_healthcare_agents()
    task = "Monitor and analyze patient vital signs: BP, heart rate, temperature, O2 saturation"
    
    print(f"\nTask: {task}")
    
    print("\nStaircase Pattern Analysis:")
    result = staircase_swarm(agents, task)
    print(result)
    
    print("\nSigmoid Pattern Analysis:")
    result = sigmoid_swarm(agents, task)
    print(result)
    
    print("\nSinusoidal Pattern Analysis:")
    result = sinusoidal_swarm(agents, task)
    print(result)

async def run_communication_examples():
    """Communication patterns for emergency scenarios"""
    print_separator()
    print("EMERGENCY COMMUNICATION PATTERNS")
    
    # Finance market alert
    finance_sender = create_finance_agents()[0]
    finance_receivers = create_finance_agents()[1:]
    market_alert = "URGENT: Major market volatility detected - immediate risk assessment required"
    
    print("\nFinance Market Alert:")
    print(f"Alert: {market_alert}")
    result = await broadcast(finance_sender, finance_receivers, market_alert)
    print("\nBroadcast Results:")
    for log in result['history']:
        print(f"\n{log['agent_name']}:")
        print(f"Response: {log['response']}")
    
    # Healthcare emergency
    health_sender = create_healthcare_agents()[0]
    health_receivers = create_healthcare_agents()[1:4]
    emergency_case = "EMERGENCY: Trauma patient with multiple injuries - immediate consultation required"
    
    print("\nHealthcare Emergency:")
    print(f"Case: {emergency_case}")
    result = await one_to_three(health_sender, health_receivers, emergency_case)
    print("\nConsultation Results:")
    for log in result['history']:
        print(f"\n{log['agent_name']}:")
        print(f"Response: {log['response']}")

async def run_all_examples():
    """Execute all swarm examples"""
    print("\n=== SWARM ARCHITECTURE EXAMPLES ===\n")
    
    # Finance examples
    run_finance_circular_swarm()
    run_finance_linear_swarm()
    run_finance_mesh_swarm()
    run_mathematical_finance_swarms()
    
    # Healthcare examples
    run_healthcare_grid_swarm()
    run_healthcare_star_swarm()
    run_healthcare_pattern_swarms()
    
    # Communication examples
    await run_communication_examples()
    
    print("\n=== ALL EXAMPLES COMPLETED ===")

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

--------------------------------------------------

# File: swarms/examples/vision_processing.md

# Vision Processing Examples

This example demonstrates how to use vision-enabled agents in Swarms to analyze images and process visual information. You'll learn how to work with both OpenAI and Anthropic vision models for various use cases.

## Prerequisites

- Python 3.7+

- OpenAI API key (for GPT-4V)

- Anthropic API key (for Claude 3)

- Swarms library

## Installation

```bash
pip3 install -U swarms
```

## Environment Variables

```plaintext
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""  # Required for GPT-4V
ANTHROPIC_API_KEY=""  # Required for Claude 3
```

## Working with Images

### Supported Image Formats

Vision-enabled agents support various image formats:

| Format | Description |
|--------|-------------|
| JPEG/JPG | Standard image format with lossy compression |
| PNG | Lossless format supporting transparency |
| GIF | Animated format (only first frame used) |
| WebP | Modern format with both lossy and lossless compression |

### Image Guidelines

- Maximum file size: 20MB
- Recommended resolution: At least 512x512 pixels
- Image should be clear and well-lit
- Avoid heavily compressed or blurry images

## Examples

### 1. Quality Control with GPT-4V

```python
from swarms.structs import Agent
from swarms.prompts.logistics import Quality_Control_Agent_Prompt

# Load your image
factory_image = "path/to/your/image.jpg"  # Local file path
# Or use a URL
# factory_image = "https://example.com/image.jpg"

# Initialize quality control agent with GPT-4V
quality_control_agent = Agent(
    agent_name="Quality Control Agent",
    agent_description="A quality control agent that analyzes images and provides detailed quality reports.",
    model_name="gpt-4.1-mini",
    system_prompt=Quality_Control_Agent_Prompt,
    multi_modal=True,
    max_loops=1
)

# Run the analysis
response = quality_control_agent.run(
    task="Analyze this image and provide a detailed quality control report",
    img=factory_image
)

print(response)
```

### 2. Visual Analysis with Claude 3

```python
from swarms.structs import Agent
from swarms.prompts.logistics import Visual_Analysis_Prompt

# Load your image
product_image = "path/to/your/product.jpg"

# Initialize visual analysis agent with Claude 3
visual_analyst = Agent(
    agent_name="Visual Analyst",
    agent_description="An agent that performs detailed visual analysis of products and scenes.",
    model_name="anthropic/claude-3-opus-20240229",
    system_prompt=Visual_Analysis_Prompt,
    multi_modal=True,
    max_loops=1
)

# Run the analysis
response = visual_analyst.run(
    task="Provide a comprehensive analysis of this product image",
    img=product_image
)

print(response)
```

### 3. Image Batch Processing

```python
from swarms.structs import Agent
import os

def process_image_batch(image_folder, agent):
    """Process multiple images in a folder"""
    results = []
    for image_file in os.listdir(image_folder):
        if image_file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp')):
            image_path = os.path.join(image_folder, image_file)
            response = agent.run(
                task="Analyze this image",
                img=image_path
            )
            results.append((image_file, response))
    return results

# Example usage
image_folder = "path/to/image/folder"
batch_results = process_image_batch(image_folder, visual_analyst)
```

## Best Practices

| Category | Best Practice | Description |
|----------|---------------|-------------|
| Image Preparation | Format Support | Ensure images are in supported formats (JPEG, PNG, GIF, WebP) |
| | Size & Quality | Optimize image size and quality for better processing |
| | Image Quality | Use clear, well-lit images for accurate analysis |
| Model Selection | GPT-4V Usage | Use for general vision tasks and detailed analysis |
| | Claude 3 Usage | Use for complex reasoning and longer outputs |
| | Batch Processing | Consider batch processing for multiple images |
| Error Handling | Path Validation | Always validate image paths before processing |
| | API Error Handling | Implement proper error handling for API calls |
| | Rate Monitoring | Monitor API rate limits and token usage |
| Performance Optimization | Result Caching | Cache results when processing the same images |
| | Batch Processing | Use batch processing for multiple images |
| | Parallel Processing | Implement parallel processing for large datasets |




--------------------------------------------------

# File: swarms/examples/vision_tools.md

# Agents with Vision and Tool Usage

This tutorial demonstrates how to create intelligent agents that can analyze images and use custom tools to perform specific actions based on their visual observations. You'll learn to build a quality control agent that can process images, identify potential security concerns, and automatically trigger appropriate responses using function calling capabilities.

## What You'll Learn

- How to configure an agent with multi-modal capabilities for image analysis
- How to integrate custom tools and functions with vision-enabled agents
- How to implement automated security analysis based on visual observations
- How to use function calling to trigger specific actions from image analysis results
- Best practices for building production-ready vision agents with tool integration

## Use Cases

This approach is perfect for:

- **Quality Control Systems**: Automated inspection of manufacturing processes

- **Security Monitoring**: Real-time threat detection and response

- **Object Detection**: Identifying and categorizing items in images

- **Compliance Checking**: Ensuring standards are met in various environments

- **Automated Reporting**: Generating detailed analysis reports from visual data

## Installation

Install the swarms package using pip:

```bash
pip install -U swarms
```

## Basic Setup

1. First, set up your environment variables:

```python
WORKSPACE_DIR="agent_workspace"
OPENAI_API_KEY=""
```


## Code

- Create tools for your agent as a function with types and documentation

- Pass tools to your agent `Agent(tools=[list_of_callables])`

- Add your image path to the run method like: `Agent().run(task=task, img=img)`

```python
from swarms.structs import Agent
from swarms.prompts.logistics import (
    Quality_Control_Agent_Prompt,
)


# Image for analysis
factory_image = "image.jpg"


def security_analysis(danger_level: str) -> str:
    """
    Analyzes the security danger level and returns an appropriate response.

    Args:
        danger_level (str, optional): The level of danger to analyze.
            Can be "low", "medium", "high", or None. Defaults to None.

    Returns:
        str: A string describing the danger level assessment.
            - "No danger level provided" if danger_level is None
            - "No danger" if danger_level is "low"
            - "Medium danger" if danger_level is "medium"
            - "High danger" if danger_level is "high"
            - "Unknown danger level" for any other value
    """
    if danger_level is None:
        return "No danger level provided"

    if danger_level == "low":
        return "No danger"

    if danger_level == "medium":
        return "Medium danger"

    if danger_level == "high":
        return "High danger"

    return "Unknown danger level"


custom_system_prompt = f"""
{Quality_Control_Agent_Prompt}

You have access to tools that can help you with your analysis. When you need to perform a security analysis, you MUST use the security_analysis function with an appropriate danger level (low, medium, or high) based on your observations.

Always use the available tools when they are relevant to the task. If you determine there is any level of danger or security concern, call the security_analysis function with the appropriate danger level.
"""

# Quality control agent
quality_control_agent = Agent(
    agent_name="Quality Control Agent",
    agent_description="A quality control agent that analyzes images and provides a detailed report on the quality of the product in the image.",
    # model_name="anthropic/claude-3-opus-20240229",
    model_name="gpt-4o-mini",
    system_prompt=custom_system_prompt,
    multi_modal=True,
    max_loops=1,
    output_type="str-all-except-first",
    # tools_list_dictionary=[schema],
    tools=[security_analysis],
)


response = quality_control_agent.run(
    task="Analyze the image and then perform a security analysis. Based on what you see in the image, determine if there is a low, medium, or high danger level and call the security_analysis function with that danger level",
    img=factory_image,
)
```


## Support and Community

If you're facing issues or want to learn more, check out the following resources to join our Discord, stay updated on Twitter, and watch tutorials on YouTube!

| Platform | Link | Description |
|----------|------|-------------|
| 📚 Documentation | [docs.swarms.world](https://docs.swarms.world) | Official documentation and guides |
| 📝 Blog | [Medium](https://medium.com/@kyeg) | Latest updates and technical articles |
| 💬 Discord | [Join Discord](https://discord.gg/EamjgSaEQf) | Live chat and community support |
| 🐦 Twitter | [@kyegomez](https://twitter.com/kyegomez) | Latest news and announcements |
| 👥 LinkedIn | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) | Professional network and updates |
| 📺 YouTube | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) | Tutorials and demos |
| 🎫 Events | [Sign up here](https://lu.ma/5p2jnc2v) | Join our community events |



--------------------------------------------------

# File: swarms/examples/vllm.md

# VLLM Swarm Agents

!!! tip "Quick Summary"
    This guide demonstrates how to create a sophisticated multi-agent system using VLLM and Swarms for comprehensive stock market analysis. You'll learn how to configure and orchestrate multiple AI agents working together to provide deep market insights.

## Overview

The example showcases how to build a stock analysis system with 5 specialized agents:

- Technical Analysis Agent
- Fundamental Analysis Agent  
- Market Sentiment Agent
- Quantitative Strategy Agent
- Portfolio Strategy Agent

Each agent has specific expertise and works collaboratively through a concurrent workflow.

## Prerequisites

!!! warning "Requirements"
    Before starting, ensure you have:

    - Python 3.7 or higher
    - The Swarms package installed
    - Access to VLLM compatible models
    - Sufficient compute resources for running VLLM

## Installation

!!! example "Setup Steps"

    1. Install the Swarms package:
    ```bash
    pip install swarms
    ```

    2. Install VLLM dependencies (if not already installed):
    ```bash
    pip install vllm
    ```

## Basic Usage

Here's a complete example of setting up the stock analysis swarm:

```python
from swarms import Agent, ConcurrentWorkflow
from swarms.utils.vllm_wrapper import VLLMWrapper

# Initialize the VLLM wrapper
vllm = VLLMWrapper(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    system_prompt="You are a helpful assistant.",
)
```

!!! note "Model Selection"
    The example uses Llama-2-7b-chat, but you can use any VLLM-compatible model. Make sure you have the necessary permissions and resources to run your chosen model.

## Agent Configuration

### Technical Analysis Agent

```python
technical_analyst = Agent(
    agent_name="Technical-Analysis-Agent",
    agent_description="Expert in technical analysis and chart patterns",
    system_prompt="""You are an expert Technical Analysis Agent specializing in market technicals and chart patterns. Your responsibilities include:

1. PRICE ACTION ANALYSIS
- Identify key support and resistance levels
- Analyze price trends and momentum
- Detect chart patterns (e.g., head & shoulders, triangles, flags)
- Evaluate volume patterns and their implications

2. TECHNICAL INDICATORS
- Calculate and interpret moving averages (SMA, EMA)
- Analyze momentum indicators (RSI, MACD, Stochastic)
- Evaluate volume indicators (OBV, Volume Profile)
- Monitor volatility indicators (Bollinger Bands, ATR)

3. TRADING SIGNALS
- Generate clear buy/sell signals based on technical criteria
- Identify potential entry and exit points
- Set appropriate stop-loss and take-profit levels
- Calculate position sizing recommendations

4. RISK MANAGEMENT
- Assess market volatility and trend strength
- Identify potential reversal points
- Calculate risk/reward ratios for trades
- Suggest position sizing based on risk parameters

Your analysis should be data-driven, precise, and actionable. Always include specific price levels, time frames, and risk parameters in your recommendations.""",
    max_loops=1,
    llm=vllm,
)
```

!!! tip "Agent Customization"
    Each agent can be customized with different:
    
    - System prompts
    
    - Temperature settings
    
    - Max token limits
    
    - Response formats

## Running the Swarm

To execute the swarm analysis:

```python
swarm = ConcurrentWorkflow(
    name="Stock-Analysis-Swarm",
    description="A swarm of agents that analyze stocks and provide comprehensive analysis.",
    agents=stock_analysis_agents,
)

# Run the analysis
response = swarm.run("Analyze the best etfs for gold and other similar commodities in volatile markets")
```



## Full Code Example

```python
from swarms import Agent, ConcurrentWorkflow
from swarms.utils.vllm_wrapper import VLLMWrapper

# Initialize the VLLM wrapper
vllm = VLLMWrapper(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    system_prompt="You are a helpful assistant.",
)

# Technical Analysis Agent
technical_analyst = Agent(
    agent_name="Technical-Analysis-Agent",
    agent_description="Expert in technical analysis and chart patterns",
    system_prompt="""You are an expert Technical Analysis Agent specializing in market technicals and chart patterns. Your responsibilities include:

1. PRICE ACTION ANALYSIS
- Identify key support and resistance levels
- Analyze price trends and momentum
- Detect chart patterns (e.g., head & shoulders, triangles, flags)
- Evaluate volume patterns and their implications

2. TECHNICAL INDICATORS
- Calculate and interpret moving averages (SMA, EMA)
- Analyze momentum indicators (RSI, MACD, Stochastic)
- Evaluate volume indicators (OBV, Volume Profile)
- Monitor volatility indicators (Bollinger Bands, ATR)

3. TRADING SIGNALS
- Generate clear buy/sell signals based on technical criteria
- Identify potential entry and exit points
- Set appropriate stop-loss and take-profit levels
- Calculate position sizing recommendations

4. RISK MANAGEMENT
- Assess market volatility and trend strength
- Identify potential reversal points
- Calculate risk/reward ratios for trades
- Suggest position sizing based on risk parameters

Your analysis should be data-driven, precise, and actionable. Always include specific price levels, time frames, and risk parameters in your recommendations.""",
    max_loops=1,
    llm=vllm,
)

# Fundamental Analysis Agent
fundamental_analyst = Agent(
    agent_name="Fundamental-Analysis-Agent",
    agent_description="Expert in company fundamentals and valuation",
    system_prompt="""You are an expert Fundamental Analysis Agent specializing in company valuation and financial metrics. Your core responsibilities include:

1. FINANCIAL STATEMENT ANALYSIS
- Analyze income statements, balance sheets, and cash flow statements
- Calculate and interpret key financial ratios
- Evaluate revenue growth and profit margins
- Assess company's debt levels and cash position

2. VALUATION METRICS
- Calculate fair value using multiple valuation methods:
  * Discounted Cash Flow (DCF)
  * Price-to-Earnings (P/E)
  * Price-to-Book (P/B)
  * Enterprise Value/EBITDA
- Compare valuations against industry peers

3. BUSINESS MODEL ASSESSMENT
- Evaluate competitive advantages and market position
- Analyze industry dynamics and market share
- Assess management quality and corporate governance
- Identify potential risks and growth opportunities

4. ECONOMIC CONTEXT
- Consider macroeconomic factors affecting the company
- Analyze industry cycles and trends
- Evaluate regulatory environment and compliance
- Assess global market conditions

Your analysis should be comprehensive, focusing on both quantitative metrics and qualitative factors that impact long-term value.""",
    max_loops=1,
    llm=vllm,
)

# Market Sentiment Agent
sentiment_analyst = Agent(
    agent_name="Market-Sentiment-Agent",
    agent_description="Expert in market psychology and sentiment analysis",
    system_prompt="""You are an expert Market Sentiment Agent specializing in analyzing market psychology and investor behavior. Your key responsibilities include:

1. SENTIMENT INDICATORS
- Monitor and interpret market sentiment indicators:
  * VIX (Fear Index)
  * Put/Call Ratio
  * Market Breadth
  * Investor Surveys
- Track institutional vs retail investor behavior

2. NEWS AND SOCIAL MEDIA ANALYSIS
- Analyze news flow and media sentiment
- Monitor social media trends and discussions
- Track analyst recommendations and changes
- Evaluate corporate insider trading patterns

3. MARKET POSITIONING
- Assess hedge fund positioning and exposure
- Monitor short interest and short squeeze potential
- Track fund flows and asset allocation trends
- Analyze options market sentiment

4. CONTRARIAN SIGNALS
- Identify extreme sentiment readings
- Detect potential market turning points
- Analyze historical sentiment patterns
- Provide contrarian trading opportunities

Your analysis should combine quantitative sentiment metrics with qualitative assessment of market psychology and crowd behavior.""",
    max_loops=1,
    llm=vllm,
)

# Quantitative Strategy Agent
quant_analyst = Agent(
    agent_name="Quantitative-Strategy-Agent",
    agent_description="Expert in quantitative analysis and algorithmic strategies",
    system_prompt="""You are an expert Quantitative Strategy Agent specializing in data-driven investment strategies. Your primary responsibilities include:

1. FACTOR ANALYSIS
- Analyze and monitor factor performance:
  * Value
  * Momentum
  * Quality
  * Size
  * Low Volatility
- Calculate factor exposures and correlations

2. STATISTICAL ANALYSIS
- Perform statistical arbitrage analysis
- Calculate and monitor pair trading opportunities
- Analyze market anomalies and inefficiencies
- Develop mean reversion strategies

3. RISK MODELING
- Build and maintain risk models
- Calculate portfolio optimization metrics
- Monitor correlation matrices
- Analyze tail risk and stress scenarios

4. ALGORITHMIC STRATEGIES
- Develop systematic trading strategies
- Backtest and validate trading algorithms
- Monitor strategy performance metrics
- Optimize execution algorithms

Your analysis should be purely quantitative, based on statistical evidence and mathematical models rather than subjective opinions.""",
    max_loops=1,
    llm=vllm,
)

# Portfolio Strategy Agent
portfolio_strategist = Agent(
    agent_name="Portfolio-Strategy-Agent",
    agent_description="Expert in portfolio management and asset allocation",
    system_prompt="""You are an expert Portfolio Strategy Agent specializing in portfolio construction and management. Your core responsibilities include:

1. ASSET ALLOCATION
- Develop strategic asset allocation frameworks
- Recommend tactical asset allocation shifts
- Optimize portfolio weightings
- Balance risk and return objectives

2. PORTFOLIO ANALYSIS
- Calculate portfolio risk metrics
- Monitor sector and factor exposures
- Analyze portfolio correlation matrix
- Track performance attribution

3. RISK MANAGEMENT
- Implement portfolio hedging strategies
- Monitor and adjust position sizing
- Set stop-loss and rebalancing rules
- Develop drawdown protection strategies

4. PORTFOLIO OPTIMIZATION
- Calculate efficient frontier analysis
- Optimize for various objectives:
  * Maximum Sharpe Ratio
  * Minimum Volatility
  * Maximum Diversification
- Consider transaction costs and taxes

Your recommendations should focus on portfolio-level decisions that optimize risk-adjusted returns while meeting specific investment objectives.""",
    max_loops=1,
    llm=vllm,
)

# Create a list of all agents
stock_analysis_agents = [
    technical_analyst,
    fundamental_analyst,
    sentiment_analyst,
    quant_analyst,
    portfolio_strategist
]

swarm = ConcurrentWorkflow(
    name="Stock-Analysis-Swarm",
    description="A swarm of agents that analyze stocks and provide a comprehensive analysis of the current trends and opportunities.",
    agents=stock_analysis_agents,
)

swarm.run("Analyze the best etfs for gold and other similiar commodities in volatile markets")
```

## Best Practices

!!! success "Optimization Tips"
    1. **Agent Design**
        - Keep system prompts focused and specific
        
        - Use clear role definitions
        
        - Include error handling guidelines
    
    2. **Resource Management**
        
        - Monitor memory usage with large models
        
        - Implement proper cleanup procedures
        
        - Use batching for multiple queries
    
    3. **Output Handling**
        
        - Implement proper logging
        
        - Format outputs consistently
        
        - Include error checking

## Common Issues and Solutions

!!! warning "Troubleshooting"
    Common issues you might encounter:

    1. **Memory Issues**
        
        - *Problem*: VLLM consuming too much memory
        
        - *Solution*: Adjust batch sizes and model parameters
    
    2. **Agent Coordination**
        
        - *Problem*: Agents providing conflicting information
        
        - *Solution*: Implement consensus mechanisms or priority rules
    
    3. **Performance**
        
        - *Problem*: Slow response times
        
        - *Solution*: Use proper batching and optimize model loading

## FAQ

??? question "Can I use different models for different agents?"
    Yes, you can initialize multiple VLLM wrappers with different models for each agent. However, be mindful of memory usage.

??? question "How many agents can run concurrently?"
    The number depends on your hardware resources. Start with 3-5 agents and scale based on performance.

??? question "Can I customize agent communication patterns?"
    Yes, you can modify the ConcurrentWorkflow class or create custom workflows for specific communication patterns.

## Advanced Configuration

!!! example "Extended Settings"
    ```python
    vllm = VLLMWrapper(
        model_name="meta-llama/Llama-2-7b-chat-hf",
        system_prompt="You are a helpful assistant.",
        temperature=0.7,
        max_tokens=2048,
        top_p=0.95,
    )
    ```

## Contributing

!!! info "Get Involved"
    We welcome contributions! Here's how you can help:

    1. Report bugs and issues
    2. Submit feature requests
    3. Contribute to documentation
    4. Share example use cases

## Resources

!!! abstract "Additional Reading"
    - [VLLM Documentation](https://docs.vllm.ai/en/latest/)
    

--------------------------------------------------

# File: swarms/examples/vllm_integration.md



# vLLM Integration Guide

!!! info "Overview"
    vLLM is a high-performance and easy-to-use library for LLM inference and serving. This guide explains how to integrate vLLM with Swarms for efficient, production-grade language model deployment.


## Installation

!!! note "Prerequisites"
    Before you begin, make sure you have Python 3.8+ installed on your system.

=== "pip"
    ```bash
    pip install -U vllm swarms
    ```

=== "poetry"
    ```bash
    poetry add vllm swarms
    ```

## Basic Usage

Here's a simple example of how to use vLLM with Swarms:

```python title="basic_usage.py"
from swarms.utils.vllm_wrapper import VLLMWrapper

# Initialize the vLLM wrapper
vllm = VLLMWrapper(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    system_prompt="You are a helpful assistant.",
    temperature=0.7,
    max_tokens=4000
)

# Run inference
response = vllm.run("What is the capital of France?")
print(response)
```

## VLLMWrapper Class

!!! abstract "Class Overview"
    The `VLLMWrapper` class provides a convenient interface for working with vLLM models.

### Key Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `model_name` | str | Name of the model to use | "meta-llama/Llama-2-7b-chat-hf" |
| `system_prompt` | str | System prompt to use | None |
| `stream` | bool | Whether to stream the output | False |
| `temperature` | float | Sampling temperature | 0.5 |
| `max_tokens` | int | Maximum number of tokens to generate | 4000 |

### Example with Custom Parameters

```python title="custom_parameters.py"
vllm = VLLMWrapper(
    model_name="meta-llama/Llama-2-13b-chat-hf",
    system_prompt="You are an expert in artificial intelligence.",
    temperature=0.8,
    max_tokens=2000
)
```

## Integration with Agents

You can easily integrate vLLM with Swarms agents for more complex workflows:

```python title="agent_integration.py"
from swarms import Agent
from swarms.utils.vllm_wrapper import VLLMWrapper

# Initialize vLLM
vllm = VLLMWrapper(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    system_prompt="You are a helpful assistant."
)

# Create an agent with vLLM
agent = Agent(
    agent_name="Research-Agent",
    agent_description="Expert in conducting research and analysis",
    system_prompt="""You are an expert research agent. Your tasks include:
    1. Analyzing complex topics
    2. Providing detailed summaries
    3. Making data-driven recommendations""",
    llm=vllm,
    max_loops=1
)

# Run the agent
response = agent.run("Research the impact of AI on healthcare")
```

## Advanced Features

### Batch Processing

!!! tip "Performance Optimization"
    Use batch processing for efficient handling of multiple tasks simultaneously.

```python title="batch_processing.py"
tasks = [
    "What is machine learning?",
    "Explain neural networks",
    "Describe deep learning"
]

results = vllm.batched_run(tasks, batch_size=3)
```

### Error Handling

!!! warning "Error Management"
    Always implement proper error handling in production environments.

```python title="error_handling.py"
from loguru import logger

try:
    response = vllm.run("Complex task")
except Exception as error:
    logger.error(f"Error occurred: {error}")
```

## Best Practices

!!! success "Recommended Practices"
    === "Model Selection"
        - Choose appropriate model sizes based on your requirements
        - Consider the trade-off between model size and inference speed

    === "System Resources"
        - Ensure sufficient GPU memory for your chosen model
        - Monitor resource usage during batch processing

    === "Prompt Engineering"
        - Use clear and specific system prompts
        - Structure user prompts for optimal results

    === "Error Handling"
        - Implement proper error handling and logging
        - Set up monitoring for production deployments

    === "Performance"
        - Use batch processing for multiple tasks
        - Adjust max_tokens based on your use case
        - Fine-tune temperature for optimal output quality

## Example: Multi-Agent System

Here's an example of creating a multi-agent system using vLLM:

```python title="multi_agent_system.py"
from swarms import Agent, ConcurrentWorkflow
from swarms.utils.vllm_wrapper import VLLMWrapper

# Initialize vLLM
vllm = VLLMWrapper(
    model_name="meta-llama/Llama-2-7b-chat-hf",
    system_prompt="You are a helpful assistant."
)

# Create specialized agents
research_agent = Agent(
    agent_name="Research-Agent",
    agent_description="Expert in research",
    system_prompt="You are a research expert.",
    llm=vllm
)

analysis_agent = Agent(
    agent_name="Analysis-Agent",
    agent_description="Expert in analysis",
    system_prompt="You are an analysis expert.",
    llm=vllm
)

# Create a workflow
agents = [research_agent, analysis_agent]
workflow = ConcurrentWorkflow(
    name="Research-Analysis-Workflow",
    description="Comprehensive research and analysis workflow",
    agents=agents
)

# Run the workflow
result = workflow.run("Analyze the impact of renewable energy")
```

--------------------------------------------------

# File: swarms/examples/xai.md

# Agent with XAI

- Add your `XAI_API_KEY` in the `.env` file

- Select your model_name like `xai/grok-beta` follows [LiteLLM conventions](https://docs.litellm.ai/docs/providers/xai)

- Execute your agent!


```python
from swarms import Agent
import os
from dotenv import load_dotenv

load_dotenv()

# Initialize the agent with ChromaDB memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="xai/grok-beta",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
)

# Run a query
agent.run("What are the components of a startup's stock incentive equity plan?")
```

--------------------------------------------------

# File: swarms/examples/yahoo_finance.md

# Swarms Tools Example with Yahoo Finance

- `pip3 install swarms swarms-tools`
- Add `OPENAI_API_KEY` to your `.env` file
- Run `yahoo_finance_agent.py`
- Agent will make a function call to the desired tool
- The tool will be executed and the result will be returned to the agent
- The agent will then analyze the result and return the final output


```python
from swarms import Agent
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)
from swarms_tools import (
    yahoo_finance_api,
)

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Personal finance advisor agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    max_loops=1,
    model_name="gpt-4o",
    dynamic_temperature_enabled=True,
    user_name="swarms_corp",
    retry_attempts=3,
    context_length=8192,
    return_step_meta=False,
    output_type="str",  # "json", "dict", "csv" OR "string" "yaml" and
    auto_generate_prompt=False,  # Auto generate prompt for the agent based on name, description, and system prompt, task
    max_tokens=4000,  # max output tokens
    saved_state_path="agent_00.json",
    interactive=False,
    tools=[yahoo_finance_api],
)

agent.run("Analyze the latest metrics for nvidia")
# Less than 30 lines of code....
```

--------------------------------------------------

# File: swarms/features.md

## ✨ Enterprise Features

Swarms delivers a comprehensive, enterprise-grade multi-agent infrastructure platform designed for production-scale deployments and seamless integration with existing systems.

| Category | Enterprise Capabilities | Business Value |
|----------|------------------------|----------------|
| 🏢 **Enterprise Architecture** | • Production-Ready Infrastructure<br>• High Availability Systems<br>• Modular Microservices Design<br>• Comprehensive Observability<br>• Backwards Compatibility | • 99.9%+ Uptime Guarantee<br>• Reduced Operational Overhead<br>• Seamless Legacy Integration<br>• Enhanced System Monitoring<br>• Risk-Free Migration Path |
| 🤖 **Multi-Agent Orchestration** | • Hierarchical Agent Swarms<br>• Parallel Processing Pipelines<br>• Sequential Workflow Orchestration<br>• Graph-Based Agent Networks<br>• Dynamic Agent Composition<br>• Agent Registry Management | • Complex Business Process Automation<br>• Scalable Task Distribution<br>• Flexible Workflow Adaptation<br>• Optimized Resource Utilization<br>• Centralized Agent Governance<br>• Enterprise-Grade Agent Lifecycle Management |
| 🔄 **Enterprise Integration** | • Multi-Model Provider Support<br>• Custom Agent Development Framework<br>• Extensive Enterprise Tool Library<br>• Multiple Memory Systems<br>• Backwards Compatibility with LangChain, AutoGen, CrewAI<br>• Standardized API Interfaces | • Vendor-Agnostic Architecture<br>• Custom Solution Development<br>• Extended Functionality Integration<br>• Enhanced Knowledge Management<br>• Seamless Framework Migration<br>• Reduced Integration Complexity |
| 📈 **Enterprise Scalability** | • Concurrent Multi-Agent Processing<br>• Intelligent Resource Management<br>• Load Balancing & Auto-Scaling<br>• Horizontal Scaling Capabilities<br>• Performance Optimization<br>• Capacity Planning Tools | • High-Throughput Processing<br>• Cost-Effective Resource Utilization<br>• Elastic Scaling Based on Demand<br>• Linear Performance Scaling<br>• Optimized Response Times<br>• Predictable Growth Planning |
| 🛠️ **Developer Experience** | • Intuitive Enterprise API<br>• Comprehensive Documentation<br>• Active Enterprise Community<br>• CLI & SDK Tools<br>• IDE Integration Support<br>• Code Generation Templates | • Accelerated Development Cycles<br>• Reduced Learning Curve<br>• Expert Community Support<br>• Rapid Deployment Capabilities<br>• Enhanced Developer Productivity<br>• Standardized Development Patterns |
| 🔐 **Enterprise Security** | • Comprehensive Error Handling<br>• Advanced Rate Limiting<br>• Real-Time Monitoring Integration<br>• Detailed Audit Logging<br>• Role-Based Access Control<br>• Data Encryption & Privacy | • Enhanced System Reliability<br>• API Security Protection<br>• Proactive Issue Detection<br>• Regulatory Compliance Support<br>• Granular Access Management<br>• Enterprise Data Protection |
| 📊 **Advanced Enterprise Features** | • SpreadsheetSwarm for Mass Agent Management<br>• Group Chat for Collaborative AI<br>• Centralized Agent Registry<br>• Mixture of Agents for Complex Solutions<br>• Agent Performance Analytics<br>• Automated Agent Optimization | • Large-Scale Agent Operations<br>• Team-Based AI Collaboration<br>• Centralized Agent Governance<br>• Sophisticated Problem Solving<br>• Performance Insights & Optimization<br>• Continuous Agent Improvement |
| 🔌 **Provider Ecosystem** | • OpenAI Integration<br>• Anthropic Claude Support<br>• ChromaDB Vector Database<br>• Custom Provider Framework<br>• Multi-Cloud Deployment<br>• Hybrid Infrastructure Support | • Provider Flexibility & Independence<br>• Advanced Vector Search Capabilities<br>• Custom Integration Development<br>• Cloud-Agnostic Architecture<br>• Flexible Deployment Options<br>• Risk Mitigation Through Diversification |
| 💪 **Production Readiness** | • Automatic Retry Mechanisms<br>• Asynchronous Processing Support<br>• Environment Configuration Management<br>• Type Safety & Validation<br>• Health Check Endpoints<br>• Graceful Degradation | • Enhanced System Reliability<br>• Improved Performance Characteristics<br>• Simplified Configuration Management<br>• Reduced Runtime Errors<br>• Proactive Health Monitoring<br>• Continuous Service Availability |
| 🎯 **Enterprise Use Cases** | • Industry-Specific Agent Solutions<br>• Custom Workflow Development<br>• Regulatory Compliance Support<br>• Extensible Framework Architecture<br>• Multi-Tenant Support<br>• Enterprise SLA Guarantees | • Rapid Industry Deployment<br>• Flexible Solution Architecture<br>• Compliance-Ready Implementations<br>• Future-Proof Technology Investment<br>• Scalable Multi-Client Operations<br>• Predictable Service Quality |

---

## 🚀 Missing a Feature?

Swarms is continuously evolving to meet enterprise needs. If you don't see a specific feature or capability that your organization requires:

### 📝 **Report Missing Features**

- Create a [GitHub Issue](https://github.com/kyegomez/swarms/issues) to request new features

- Describe your use case and business requirements

- Our team will evaluate and prioritize based on enterprise demand

### 📞 **Schedule a Consultation**

- [Book a call with our enterprise team](https://cal.com/swarms/swarms-onboarding-session) for personalized guidance

- Discuss your specific multi-agent architecture requirements

- Get expert recommendations for your implementation strategy

- Explore custom enterprise solutions and integrations

Our team is committed to ensuring Swarms meets your enterprise multi-agent infrastructure needs. We welcome feedback and collaboration to build the most comprehensive platform for production-scale AI agent deployments.


--------------------------------------------------

# File: swarms/framework/agents_explained.md

# An Analysis of Agents

In the Swarms framework, agents are designed to perform tasks autonomously by leveraging large language models (LLMs), various tools, and long-term memory systems. This guide provides an extensive conceptual walkthrough of how an agent operates, detailing the sequence of actions it takes to complete a task and how it utilizes its internal components.

#### Agent Components Overview
- **LLM (Large Language Model)**: The core component responsible for understanding and generating natural language.
- **Tools**: External functions and services that the agent can call to perform specific tasks, such as querying databases or interacting with APIs.
- **Long-term Memory**: Systems like ChromaDB or Pinecone that store and retrieve information over extended periods, enabling the agent to remember past interactions and contexts.

#### Agent Workflow
The workflow of an agent can be divided into several stages: task initiation, initial LLM processing, tool usage, memory interaction, and final LLM processing.

##### Stage 1: Task Initiation
- **Input**: The task or query that the agent needs to address.
- **Output**: A structured plan or approach for handling the task.

##### Stage 2: Initial LLM Processing
- **Input**: The task or query.
- **Process**: The LLM interprets the task, understanding the context and requirements.
- **Output**: An initial response or action plan.

##### Stage 3: Tool Usage
- **Input**: The action plan or specific sub-tasks identified by the LLM.
- **Process**: The agent calls various tools to gather information, perform calculations, or interact with external systems.
  - **Function Calling as Tools**: Tools are called as functions with specific inputs and outputs, enabling the agent to perform a wide range of tasks.
- **Output**: Data or results from the tools.

##### Stage 4: Memory Interaction
- **Input**: Intermediate results and context from the tools.
- **Process**: The agent interacts with long-term memory systems to store new information and retrieve relevant past data.
  - **RAG Systems (ChromaDB, Pinecone)**: These systems are used to enhance the agent’s responses by providing relevant historical data and context.
- **Output**: Enhanced context and data for final processing.

##### Stage 5: Final LLM Processing
- **Input**: Comprehensive data and context from the tools and memory systems.
- **Process**: The LLM generates the final response or completes the task using the enriched data.
- **Output**: The final output or action taken by the agent.

### Detailed Workflow with Mermaid Diagrams

#### Agent Components and Workflow

```mermaid
graph TD
    A[Task Initiation] -->|Receives Task| B[Initial LLM Processing]
    B -->|Interprets Task| C[Tool Usage]
    C -->|Calls Tools| D[Function 1]
    C -->|Calls Tools| E[Function 2]
    D -->|Returns Data| C
    E -->|Returns Data| C
    C -->|Provides Data| F[Memory Interaction]
    F -->|Stores and Retrieves Data| G[RAG System]
    G -->|ChromaDB/Pinecone| H[Enhanced Data]
    F -->|Provides Enhanced Data| I[Final LLM Processing]
    I -->|Generates Final Response| J[Output]
```

### Explanation of Each Stage

#### Stage 1: Task Initiation
- **Task**: The agent receives a task or query from an external source (e.g., a user query, a system trigger).
- **Objective**: To understand what needs to be done and prepare an initial approach.

#### Stage 2: Initial LLM Processing
- **Interpretation**: The LLM processes the task to comprehend its context and requirements.
- **Planning**: The LLM generates an initial plan or identifies the sub-tasks required to complete the task.

#### Stage 3: Tool Usage
- **Function Calls**: The agent uses predefined functions (tools) to perform specific actions, such as querying a database or making API calls.
- **Tool Integration**: Each tool is called with specific parameters, and the results are collected for further processing.

#### Stage 4: Memory Interaction
- **Long-term Memory**: Systems like ChromaDB and Pinecone store and retrieve long-term data, providing the agent with historical context and past interactions.
- **Retrieval-Augmented Generation (RAG)**: The agent uses RAG systems to enhance the current context with relevant past data, improving the quality and relevance of the final output.

#### Stage 5: Final LLM Processing
- **Enhanced Processing**: The LLM processes the enriched data and context provided by the tools and memory systems.
- **Final Output**: The LLM generates a comprehensive response or completes the task using the enhanced information.

### Conclusion

The Swarms framework's agents are powerful units that combine LLMs, tools, and long-term memory systems to perform complex tasks efficiently. By leveraging function calling for tools and RAG systems like ChromaDB and Pinecone, agents can enhance their capabilities and deliver highly relevant and accurate results. This conceptual guide and walkthrough provide a detailed understanding of how agents operate within the Swarms framework, enabling the development of sophisticated and collaborative AI systems.

--------------------------------------------------

# File: swarms/framework/code_cleanliness.md

# Code Cleanliness in Python: A Comprehensive Guide

Code cleanliness is an essential aspect of software development that ensures code is easy to read, understand, and maintain. Clean code leads to fewer bugs, easier debugging, and more efficient collaboration among developers. This blog article delves into the principles of writing clean Python code, emphasizing the use of type annotations, docstrings, and the Loguru logging library. We'll explore the importance of each component and provide practical examples to illustrate best practices.

## Table of Contents
1. Introduction to Code Cleanliness
2. Importance of Type Annotations
3. Writing Effective Docstrings
4. Structuring Your Code
5. Error Handling and Logging with Loguru
6. Refactoring for Clean Code
7. Examples of Clean Code
8. Conclusion

## 1. Introduction to Code Cleanliness

Code cleanliness refers to the practice of writing code that is easy to read, understand, and maintain. Clean code follows consistent conventions and is organized logically, making it easier for developers to collaborate and for new team members to get up to speed quickly.

### Why Clean Code Matters

1. **Readability**: Clean code is easy to read and understand, which reduces the time needed to grasp what the code does.
2. **Maintainability**: Clean code is easier to maintain and modify, reducing the risk of introducing bugs when making changes.
3. **Collaboration**: Clean code facilitates collaboration among team members, as everyone can easily understand and follow the codebase.
4. **Debugging**: Clean code makes it easier to identify and fix bugs, leading to more reliable software.

## 2. Importance of Type Annotations

Type annotations in Python provide a way to specify the types of variables, function arguments, and return values. They enhance code readability and help catch type-related errors early in the development process.

### Benefits of Type Annotations

1. **Improved Readability**: Type annotations make it clear what types of values are expected, improving code readability.
2. **Error Detection**: Type annotations help catch type-related errors during development, reducing runtime errors.
3. **Better Tooling**: Many modern IDEs and editors use type annotations to provide better code completion and error checking.

### Example of Type Annotations

```python
from typing import List

def calculate_average(numbers: List[float]) -> float:
    """
    Calculates the average of a list of numbers.

    Args:
        numbers (List[float]): A list of numbers.

    Returns:
        float: The average of the numbers.
    """
    return sum(numbers) / len(numbers)
```

In this example, the `calculate_average` function takes a list of floats as input and returns a float. The type annotations make it clear what types are expected and returned, enhancing readability and maintainability.

## 3. Writing Effective Docstrings

Docstrings are an essential part of writing clean code in Python. They provide inline documentation for modules, classes, methods, and functions. Effective docstrings improve code readability and make it easier for other developers to understand and use your code.

### Benefits of Docstrings

1. **Documentation**: Docstrings serve as inline documentation, making it easier to understand the purpose and usage of code.
2. **Consistency**: Well-written docstrings ensure consistent documentation across the codebase.
3. **Ease of Use**: Docstrings make it easier for developers to use and understand code without having to read through the implementation details.

### Example of Effective Docstrings

```python
def calculate_factorial(n: int) -> int:
    """
    Calculates the factorial of a given non-negative integer.

    Args:
        n (int): The non-negative integer to calculate the factorial of.

    Returns:
        int: The factorial of the given number.

    Raises:
        ValueError: If the input is a negative integer.
    """
    if n < 0:
        raise ValueError("Input must be a non-negative integer.")
    factorial = 1
    for i in range(1, n + 1):
        factorial *= i
    return factorial
```

In this example, the docstring clearly explains the purpose of the `calculate_factorial` function, its arguments, return value, and the exception it may raise.

## 4. Structuring Your Code

Proper code structure is crucial for code cleanliness. A well-structured codebase is easier to navigate, understand, and maintain. Here are some best practices for structuring your Python code:

### Organizing Code into Modules and Packages

Organize your code into modules and packages to group related functionality together. This makes it easier to find and manage code.

```python
# project/
# ├── main.py
# ├── utils/
# │   ├── __init__.py
# │   ├── file_utils.py
# │   └── math_utils.py
# └── models/
#     ├── __init__.py
#     ├── user.py
#     └── product.py
```

### Using Functions and Classes

Break down your code into small, reusable functions and classes. This makes your code more modular and easier to test.

```python
class User:
    def __init__(self, name: str, age: int):
        """
        Initializes a new user.

        Args:
            name (str): The name of the user.
            age (int): The age of the user.
        """
        self.name = name
        self.age = age

    def greet(self) -> str:
        """
        Greets the user.

        Returns:
            str: A greeting message.
        """
        return f"Hello, {self.name}!"
```

### Keeping Functions Small

Functions should do one thing and do it well. Keep functions small and focused on a single task.

```python
def save_user(user: User, filename: str) -> None:
    """
    Saves user data to a file.

    Args:
        user (User): The user object to save.
        filename (str): The name of the file to save the user data to.
    """
    with open(filename, 'w') as file:
        file.write(f"{user.name},{user.age}")
```

## 5. Error Handling and Logging with Loguru

Effective error handling and logging are critical components of clean code. They help you manage and diagnose issues that arise during the execution of your code.

### Error Handling Best Practices

1. **Use Specific Exceptions**: Catch specific exceptions rather than using a generic `except` clause.
2. **Provide Meaningful Messages**: When raising exceptions, provide meaningful error messages to help diagnose the issue.
3. **Clean Up Resources**: Use `finally` blocks or context managers to ensure that resources are properly cleaned up.

### Example of Error Handling

```python
def divide_numbers(numerator: float, denominator: float) -> float:
    """
    Divides the numerator by the denominator.

    Args:
        numerator (float): The number to be divided.
        denominator (float): The number to divide by.

    Returns:
        float: The result of the division.

    Raises:
        ValueError: If the denominator is zero.
    """
    if denominator == 0:
        raise ValueError("The denominator cannot be zero.")
    return numerator / denominator
```

### Logging with Loguru

Loguru is a powerful logging library for Python that makes logging simple and enjoyable. It provides a clean and easy-to-use API for logging messages with different severity levels.

#### Installing Loguru

```bash
pip install loguru
```

#### Basic Usage of Loguru

```python
from loguru import logger

logger.debug("This is a debug message")
logger.info("This is an info message")
logger.warning("This is a warning message")
logger.error("This is an error message")
logger.critical("This is a critical message")
```

### Example of Logging in a Function

```python
from loguru import logger

def fetch_data(url: str) -> str:
    """
    Fetches data from a given URL and returns it as a string.

    Args:
        url (str): The URL to fetch data from.

    Returns:
        str: The data fetched from the URL.

    Raises:
        requests.exceptions.RequestException: If there is an error with the request.
    """
    try:
        logger.info(f"Fetching data from {url}")
        response = requests.get(url)
        response.raise_for_status()
        logger.info("Data fetched successfully")
        return response.text
    except requests.exceptions.RequestException as e:
        logger.error(f"Error fetching data: {e}")
        raise
```

In this example, Loguru is used to log messages at different severity levels. The `fetch_data` function logs informational messages when fetching data and logs an error message if an exception is raised.

## 6. Refactoring for Clean Code

Refactoring is the process of restructuring existing code without changing its external behavior. It is an essential practice for maintaining clean code. Refactoring helps improve code readability, reduce complexity, and eliminate redundancy.

### Identifying Code Smells

Code smells are indicators of potential issues in the code that may require refactoring. Common code smells include:
1. **Long Methods**: Methods that are too long and do too many things.
2. **Duplicated Code**: Code that is duplicated in multiple places.
3. **Large Classes**: Classes that have too many responsibilities.
4. **Poor Naming**: Variables, functions, or classes with unclear or misleading names.

### Refactoring Techniques

1. **Extract Method**: Break down long methods into smaller, more focused methods.
2. **Rename Variables**: Use meaningful names for variables, functions, and classes.
3. **Remove Duplicated Code**: Consolidate duplicated code into a single location.
4. **Simplify Conditional Expressions**: Simplify complex conditional expressions for

 better readability.

### Example of Refactoring

Before refactoring:
```python
def process_data(data: List[int]) -> int:
    total = 0
    for value in data:
        if value > 0:
            total += value
    return total
```

After refactoring:
```python
def filter_positive_values(data: List[int]) -> List[int]:
    """
    Filters the positive values from the input data.

    Args:
        data (List[int]): The input data.

    Returns:
        List[int]: A list of positive values.
    """
    return [value for value in data if value > 0]

def sum_values(values: List[int]) -> int:
    """
    Sums the values in the input list.

    Args:
        values (List[int]): A list of values to sum.

    Returns:
        int: The sum of the values.
    """
    return sum(values)

def process_data(data: List[int]) -> int:
    """
    Processes the data by filtering positive values and summing them.

    Args:
        data (List[int]): The input data.

    Returns:
        int: The sum of the positive values.
    """
    positive_values = filter_positive_values(data)
    return sum_values(positive_values)
```

In this example, the `process_data` function is refactored into smaller, more focused functions. This improves readability and maintainability.

## 7. Examples of Clean Code

### Example 1: Reading a File

```python
def read_file(file_path: str) -> str:
    """
    Reads the content of a file and returns it as a string.

    Args:
        file_path (str): The path to the file to read.

    Returns:
        str: The content of the file.

    Raises:
        FileNotFoundError: If the file does not exist.
        IOError: If there is an error reading the file.
    """
    try:
        with open(file_path, 'r') as file:
            return file.read()
    except FileNotFoundError as e:
        logger.error(f"File not found: {file_path}")
        raise
    except IOError as e:
        logger.error(f"Error reading file: {file_path}")
        raise
```

### Example 2: Fetching Data from a URL

```python
import requests
from loguru import logger

def fetch_data(url: str) -> str:
    """
    Fetches data from a given URL and returns it as a string.

    Args:
        url (str): The URL to fetch data from.

    Returns:
        str: The data fetched from the URL.

    Raises:
        requests.exceptions.RequestException: If there is an error with the request.
    """
    try:
        logger.info(f"Fetching data from {url}")
        response = requests.get(url)
        response.raise_for_status()
        logger.info("Data fetched successfully")
        return response.text
    except requests.exceptions.RequestException as e:
        logger.error(f"Error fetching data: {e}")
        raise
```

### Example 3: Calculating Factorial

```python
def calculate_factorial(n: int) -> int:
    """
    Calculates the factorial of a given non-negative integer.

    Args:
        n (int): The non-negative integer to calculate the factorial of.

    Returns:
        int: The factorial of the given number.

    Raises:
        ValueError: If the input is a negative integer.
    """
    if n < 0:
        raise ValueError("Input must be a non-negative integer.")
    factorial = 1
    for i in range(1, n + 1):
        factorial *= i
    return factorial
```

## 8. Conclusion

Writing clean code in Python is crucial for developing maintainable, readable, and error-free software. By using type annotations, writing effective docstrings, structuring your code properly, and leveraging logging with Loguru, you can significantly improve the quality of your codebase.

Remember to refactor your code regularly to eliminate code smells and improve readability. Clean code not only makes your life as a developer easier but also enhances collaboration and reduces the likelihood of bugs.

By following the principles and best practices outlined in this article, you'll be well on your way to writing clean, maintainable Python code.

--------------------------------------------------

# File: swarms/framework/concept.md

To create a comprehensive overview of the Swarms framework, we can break it down into key concepts such as models, agents, tools, Retrieval-Augmented Generation (RAG) systems, and swarm systems. Below are conceptual explanations of these components along with mermaid diagrams to illustrate their interactions.

### Swarms Framework Overview

#### 1. **Models**
Models are the core component of the Swarms framework, representing the neural networks and machine learning models used to perform various tasks. These can be Large Language Models (LLMs), vision models, or any other AI models.

#### 2. **Agents**
Agents are autonomous units that use models to perform specific tasks. In the Swarms framework, agents can leverage tools and interact with RAG systems.

- **LLMs with Tools**: These agents use large language models along with tools like databases, APIs, and external knowledge sources to enhance their capabilities.
- **RAG Systems**: These systems combine retrieval mechanisms with generative models to produce more accurate and contextually relevant outputs.

#### 3. **Swarm Systems**
Swarm systems involve multiple agents working collaboratively to achieve complex tasks. These systems coordinate and communicate among agents to ensure efficient and effective task execution.

### Mermaid Diagrams

#### Models

```mermaid
graph TD
    A[Model] -->|Uses| B[Data]
    A -->|Trains| C[Algorithm]
    A -->|Outputs| D[Predictions]
```

#### Agents: LLMs with Tools and RAG Systems

```mermaid
graph TD
    A[Agent] -->|Uses| B[LLM]
    A -->|Interacts with| C[Tool]
    C -->|Provides Data to| B
    A -->|Queries| D[RAG System]
    D -->|Retrieves Information from| E[Database]
    D -->|Generates Responses with| F[Generative Model]
```

#### Swarm Systems

```mermaid
graph TD
    A[Swarm System]
    A -->|Coordinates| B[Agent 1]
    A -->|Coordinates| C[Agent 2]
    A -->|Coordinates| D[Agent 3]
    B -->|Communicates with| C
    C -->|Communicates with| D
    D -->|Communicates with| B
    B -->|Performs Task| E[Task 1]
    C -->|Performs Task| F[Task 2]
    D -->|Performs Task| G[Task 3]
    E -->|Reports to| A
    F -->|Reports to| A
    G -->|Reports to| A
```

### Conceptualization

1. **Models**: The basic building blocks trained on specific datasets to perform tasks.
2. **Agents**: Intelligent entities that utilize models and tools to perform actions. LLM agents can use additional tools to enhance their capabilities.
3. **RAG Systems**: Enhance agents by combining retrieval mechanisms (to fetch relevant information) with generative models (to create contextually relevant responses).
4. **Swarm Systems**: Complex systems where multiple agents collaborate, communicate, and coordinate to perform complex, multi-step tasks efficiently.

### Summary
The Swarms framework leverages models, agents, tools, RAG systems, and swarm systems to create a robust, collaborative environment for executing complex AI tasks. By coordinating multiple agents and enhancing their capabilities with tools and retrieval-augmented generation, Swarms can handle sophisticated and multi-faceted applications effectively.

--------------------------------------------------

# File: swarms/framework/index.md

## Swarms Framework Conceptual Breakdown

The `swarms` framework is a sophisticated structure designed to orchestrate the collaborative work of multiple agents in a hierarchical manner. This breakdown provides a conceptual and visual representation of the framework, highlighting the interactions between models, tools, memory, agents, and swarms.

### Hierarchical Structure

The framework can be visualized as a multi-layered hierarchy:

1. **Models, Tools, Memory**: These form the foundational components that agents utilize to perform tasks.
2. **Agents**: Individual entities that encapsulate specific functionalities, utilizing models, tools, and memory.
3. **Swarm**: A collection of multiple agents working together in a coordinated manner.
4. **Structs**: High-level structures that organize and manage swarms, enabling complex workflows and interactions.

### Visual Representation

Below are visual graphs illustrating the hierarchical and tree structure of the `swarms` framework.

#### 1. Foundational Components: Models, Tools, Memory

![Diagram](assets/img/agent_def.png)

#### 2. Agents and Their Interactions

```mermaid
graph TD;
    Agents --> Swarm
    subgraph Agents_Collection
        Agent1
        Agent2
        Agent3
    end
    subgraph Individual_Agents
        Agent1 --> Models
        Agent1 --> Tools
        Agent1 --> Memory
        Agent2 --> Models
        Agent2 --> Tools
        Agent2 --> Memory
        Agent3 --> Models
        Agent3 --> Tools
        Agent3 --> Memory
    end
```

#### 3. Multiple Agents Form a Swarm

```mermaid
graph TD;
    Swarm1 --> Struct
    Swarm2 --> Struct
    Swarm3 --> Struct
    subgraph Swarms_Collection
        Swarm1
        Swarm2
        Swarm3
    end
    subgraph Individual_Swarms
        Swarm1 --> Agent1
        Swarm1 --> Agent2
        Swarm1 --> Agent3
        Swarm2 --> Agent4
        Swarm2 --> Agent5
        Swarm2 --> Agent6
        Swarm3 --> Agent7
        Swarm3 --> Agent8
        Swarm3 --> Agent9
    end
```

#### 4. Structs Organizing Multiple Swarms

```mermaid
graph TD;
    Struct --> Swarms_Collection
    subgraph High_Level_Structs
        Struct1
        Struct2
        Struct3
    end
    subgraph Struct1
        Swarm1
        Swarm2
    end
    subgraph Struct2
        Swarm3
    end
    subgraph Struct3
        Swarm4
        Swarm5
    end
```

### Directory Breakdown

The directory structure of the `swarms` framework is organized to support its hierarchical architecture:

```sh
swarms/
├── agents/
├── artifacts/
├── marketplace/
├── memory/
├── models/
├── prompts/
├── schemas/
├── structs/
├── telemetry/
├── tools/
├── utils/
└── __init__.py
```

### Summary

The `swarms` framework is designed to facilitate complex multi-agent interactions through a structured and layered approach. By leveraging foundational components like models, tools, and memory, individual agents are empowered to perform specialized tasks. These agents are then coordinated within swarms to achieve collective goals, and swarms are managed within high-level structs to orchestrate sophisticated workflows.

This hierarchical design ensures scalability, flexibility, and robustness, making the `swarms` framework a powerful tool for various applications in AI, data analysis, optimization, and beyond.

--------------------------------------------------

# File: swarms/framework/reference.md

# API Reference Documentation



### `swarms.__init__`

**Description**:  
This module initializes the Swarms package by concurrently executing the bootup process and activating Sentry for telemetry. It imports various components from other modules within the Swarms package.

**Imports**:
- `concurrent.futures`: A module that provides a high-level interface for asynchronously executing callables.

- `swarms.telemetry.bootup`: Contains the `bootup` function for initializing telemetry.

- `swarms.telemetry.sentry_active`: Contains the `activate_sentry` function to enable Sentry for error tracking.

- Other modules from the Swarms package are imported for use, including agents, artifacts, prompts, structs, telemetry, tools, utils, and schemas.


**Concurrent Execution**:
The module uses `ThreadPoolExecutor` to run the `bootup` and `activate_sentry` functions concurrently.

```python
import concurrent.futures
from swarms.telemetry.bootup import bootup  # noqa: E402, F403
from swarms.telemetry.sentry_active import activate_sentry

# Use ThreadPoolExecutor to run bootup and activate_sentry concurrently
with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
    executor.submit(bootup)
    executor.submit(activate_sentry)

from swarms.agents import *  # noqa: E402, F403
from swarms.artifacts import *  # noqa: E402, F403
from swarms.prompts import *  # noqa: E402, F403
from swarms.structs import *  # noqa: E402, F403
from swarms.telemetry import *  # noqa: E402, F403
from swarms.tools import *  # noqa: E402, F403
from swarms.utils import *  # noqa: E402, F403
from swarms.schemas import *  # noqa: E402, F403
```

**Note**: There are no documentable functions or classes within this module itself, as it primarily serves to execute initial setup tasks and import other modules.




### `swarms.artifacts.base_artifact`

**Description**:  
This module defines the `BaseArtifact` abstract base class for representing artifacts in the system. It provides methods to convert artifact values to various formats and enforces the implementation of an addition method for subclasses.

**Imports**:
- `json`: A module for parsing JSON data.

- `uuid`: A module for generating unique identifiers.

- `ABC`, `abstractmethod`: Tools from the `abc` module to define abstract base classes.

- `dataclass`: A decorator for creating data classes.

- `Any`: A type hint for any data type.


### `BaseArtifact`
**Description**:  
An abstract base class for artifacts that includes common attributes and methods for handling artifact values.

**Attributes**:  
- `id` (`str`): A unique identifier for the artifact, generated if not provided.

- `name` (`str`): The name of the artifact. If not provided, it defaults to the artifact's ID.

- `value` (`Any`): The value associated with the artifact.


**Methods**:

- `__post_init__(self) -> None`

    - **Description**: Initializes the artifact, setting the `id` and `name` attributes if they are not provided.
    
    - **Parameters**: None.
    
    - **Return**: None.
    

- `value_to_bytes(cls, value: Any) -> bytes`

    - **Description**: Converts the given value to bytes.
    
    - **Parameters**: 
    
      - `value` (`Any`): The value to convert.
      
    - **Return**: 
    
      - (`bytes`): The value converted to bytes.
      

- `value_to_dict(cls, value: Any) -> dict`

    - **Description**: Converts the given value to a dictionary.
    
    - **Parameters**: 
    
      - `value` (`Any`): The value to convert.
      
    - **Return**: 
    
      - (`dict`): The value converted to a dictionary.
      

- `to_text(self) -> str`

    - **Description**: Converts the artifact's value to a text representation.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`str`): The string representation of the artifact's value.
      

- `__str__(self) -> str`

    - **Description**: Returns a string representation of the artifact.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`str`): The string representation of the artifact.
      

- `__bool__(self) -> bool`

    - **Description**: Returns the boolean value of the artifact based on its value.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`bool`): The boolean value of the artifact.
      

- `__len__(self) -> int`

    - **Description**: Returns the length of the artifact's value.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`int`): The length of the artifact's value.
      

- `__add__(self, other: BaseArtifact) -> BaseArtifact`

    - **Description**: Abstract method for adding two artifacts together. Must be implemented by subclasses.
    
    - **Parameters**: 
    
      - `other` (`BaseArtifact`): The other artifact to add.
      
    - **Return**: 
    
      - (`BaseArtifact`): The result of adding the two artifacts.
      

**Example**:
```python
from swarms.artifacts.base_artifact import BaseArtifact

class MyArtifact(BaseArtifact):
    def __add__(self, other: BaseArtifact) -> BaseArtifact:
      
        return MyArtifact(id=self.id, name=self.name, value=self.value + other.value)

artifact1 = MyArtifact(id="123", name="Artifact1", value=10)
artifact2 = MyArtifact(id="456", name="Artifact2", value=20)
result = artifact1 + artifact2
print(result)  # Output: MyArtifact with the combined value
```




### `swarms.artifacts.text_artifact`

**Description**:  
This module defines the `TextArtifact` class, which represents a text-based artifact. It extends the `BaseArtifact` class and includes attributes and methods specific to 
handling text values, including encoding options, embedding generation, and token counting.

**Imports**:
- `dataclass`, `field`: Decorators and functions from the `dataclasses` module for creating data classes.

- `Callable`: A type hint indicating a callable object from the `typing` module.

- `BaseArtifact`: The abstract base class for artifacts, imported from `swarms.artifacts.base_artifact`.


### `TextArtifact`
**Description**:  
Represents a text artifact with additional functionality for handling text values, encoding, and embeddings.

**Attributes**:  
- `value` (`str`): The text value of the artifact.

- `encoding` (`str`, optional): The encoding of the text (default is "utf-8").

- `encoding_error_handler` (`str`, optional): The error handler for encoding errors (default is "strict").

- `tokenizer` (`Callable`, optional): A callable for tokenizing the text value.

- `_embedding` (`list[float]`): The embedding of the text artifact (default is an empty list).


**Properties**:
- `embedding` (`Optional[list[float]]`): Returns the embedding of the text artifact if available; otherwise, returns `None`.


**Methods**:

- `__add__(self, other: BaseArtifact) -> TextArtifact`

    - **Description**: Concatenates the text value of this artifact with the text value of another artifact.
    
    - **Parameters**: 
    
      - `other` (`BaseArtifact`): The other artifact to concatenate with.
      
    - **Return**: 
    
      - (`TextArtifact`): A new `TextArtifact` instance with the concatenated value.
      

- `__bool__(self) -> bool`

    - **Description**: Checks if the text value of the artifact is non-empty.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`bool`): `True` if the text value is non-empty; otherwise, `False`.
      

- `generate_embedding(self, model) -> list[float] | None`

    - **Description**: Generates the embedding of the text artifact using a given embedding model.
    
    - **Parameters**: 
    
      - `model`: An embedding model that provides the `embed_string` method.
      
    - **Return**: 
    
      - (`list[float] | None`): The generated embedding as a list of floats, or `None` if the embedding could not be generated.
      

- `token_count(self) -> int`

    - **Description**: Counts the number of tokens in the text artifact using a specified tokenizer.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`int`): The number of tokens in the text value.
      

- `to_bytes(self) -> bytes`

    - **Description**: Converts the text value of the artifact to bytes using the specified encoding and error handler.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`bytes`): The text value encoded as bytes.
      

**Example**:
```python
from swarms.artifacts.text_artifact import TextArtifact

# Create a TextArtifact instance
text_artifact = TextArtifact(value="Hello, World!")

# Generate embedding (assuming an appropriate model is provided)
# embedding = text_artifact.generate_embedding(model)

# Count tokens in the text artifact
token_count = text_artifact.token_count()

# Convert to bytes
bytes_value = text_artifact.to_bytes()

print(text_artifact)  # Output: Hello, World!
print(token_count)    # Output: Number of tokens
print(bytes_value)    # Output: b'Hello, World!'
```




### `swarms.artifacts.main_artifact`

**Description**:  
This module defines the `Artifact` class, which represents a file artifact with versioning capabilities. It allows for the creation, editing, saving, loading, and exporting of file artifacts, as well as managing their version history. The module also includes a `FileVersion` class to encapsulate the details of each version of the artifact.

**Imports**:
- `time`: A module for time-related functions.

- `logger`: A logging utility from `swarms.utils.loguru_logger`.

- `os`: A module providing a way of using operating system-dependent functionality.

- `json`: A module for parsing JSON data.

- `List`, `Union`, `Dict`, `Any`: Type hints from the `typing` module.

- `BaseModel`, `Field`, `validator`: Tools from the `pydantic` module for data validation and settings management.

- `datetime`: A module for manipulating dates and times.


### `FileVersion`
**Description**:  
Represents a version of a file with its content and timestamp.

**Attributes**:  
- `version_number` (`int`): The version number of the file.

- `content` (`str`): The content of the file version.

- `timestamp` (`str`): The timestamp of the file version, formatted as "YYYY-MM-DD HH:MM:SS".


**Methods**:

- `__str__(self) -> str`

    - **Description**: Returns a string representation of the file version.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`str`): A formatted string containing the version number, timestamp, and content.
      

### `Artifact`
**Description**:  
Represents a file artifact with attributes to manage its content and version history.

**Attributes**:  
- `file_path` (`str`): The path to the file.

- `file_type` (`str`): The type of the file (e.g., ".txt").

- `contents` (`str`): The contents of the file.

- `versions` (`List[FileVersion]`): The list of file versions.

- `edit_count` (`int`): The number of times the file has been edited.


**Methods**:

- `validate_file_type(cls, v, values) -> str`

    - **Description**: Validates the file type based on the file extension.
    
    - **Parameters**: 
    
      - `v` (`str`): The file type to validate.
      
      - `values` (`dict`): A dictionary of other field values.
      
    - **Return**: 
    
      - (`str`): The validated file type.
      

- `create(self, initial_content: str) -> None`

    - **Description**: Creates a new file artifact with the initial content.
    
    - **Parameters**: 
    
      - `initial_content` (`str`): The initial content to set for the artifact.
      
    - **Return**: None.
    

- `edit(self, new_content: str) -> None`

    - **Description**: Edits the artifact's content, tracking the change in the version history.
    
    - **Parameters**: 
    
      - `new_content` (`str`): The new content to set for the artifact.
      
    - **Return**: None.
    

- `save(self) -> None`

    - **Description**: Saves the current artifact's contents to the specified file path.
    
    - **Parameters**: None.
    
    - **Return**: None.
    

- `load(self) -> None`

    - **Description**: Loads the file contents from the specified file path into the artifact.
    
    - **Parameters**: None.
    
    - **Return**: None.
    

- `get_version(self, version_number: int) -> Union[FileVersion, None]`

    - **Description**: Retrieves a specific version of the artifact by its version number.
    
    - **Parameters**: 
    
      - `version_number` (`int`): The version number to retrieve.
      
    - **Return**: 
    
      - (`FileVersion | None`): The requested version if found; otherwise, `None`.
      

- `get_contents(self) -> str`

    - **Description**: Returns the current contents of the artifact as a string.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`str`): The current contents of the artifact.
      

- `get_version_history(self) -> str`

    - **Description**: Returns the version history of the artifact as a formatted string.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`str`): A formatted string containing the version history.
      

- `export_to_json(self, file_path: str) -> None`

    - **Description**: Exports the artifact to a JSON file.
    
    - **Parameters**: 
    
      - `file_path` (`str`): The path to the JSON file where the artifact will be saved.
      
    - **Return**: None.
    

- `import_from_json(cls, file_path: str) -> "Artifact"`

    - **Description**: Imports an artifact from a JSON file.
    
    - **Parameters**: 
    
      - `file_path` (`str`): The path to the JSON file to import the artifact from.
      
    - **Return**: 
    
      - (`Artifact`): The imported artifact instance.
      

- `get_metrics(self) -> str`

    - **Description**: Returns all metrics of the artifact as a formatted string.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`str`): A string containing all metrics of the artifact.
      

- `to_dict(self) -> Dict[str, Any]`

    - **Description**: Converts the artifact instance to a dictionary representation.
    
    - **Parameters**: None.
    
    - **Return**: 
    
      - (`Dict[str, Any]`): The dictionary representation of the artifact.
      

- `from_dict(cls, data: Dict[str, Any]) -> "Artifact"`

    - **Description**: Creates an artifact instance from a dictionary representation.
    
    - **Parameters**: 
    
      - `data` (`Dict[str, Any]`): The dictionary to create the artifact from.
      
    - **Return**: 
    
      - (`Artifact`): The created artifact instance.
      

**Example**:
```python
from swarms.artifacts.main_artifact import Artifact

# Create an Artifact instance
artifact = Artifact(file_path="example.txt", file_type=".txt")
artifact.create("Initial content")
artifact.edit("First edit")
artifact.edit("Second edit")
artifact.save()

# Export to JSON
artifact.export_to_json("artifact.json")

# Import from JSON
imported_artifact = Artifact.import_from_json("artifact.json")

# Get metrics
print(artifact.get_metrics())
```




### `swarms.artifacts.__init__`

**Description**:  
This module serves as the initialization point for the artifacts subpackage within the Swarms framework. It imports and exposes the key classes related to artifacts, including `BaseArtifact`, `TextArtifact`, and `Artifact`, making them available for use in other parts of the application.

**Imports**:
- `BaseArtifact`: The abstract base class for artifacts, imported from `swarms.artifacts.base_artifact`.

- `TextArtifact`: A class representing text-based artifacts, imported from `swarms.artifacts.text_artifact`.

- `Artifact`: A class representing file artifacts with versioning capabilities, imported from `swarms.artifacts.main_artifact`.


**Exported Classes**:
- `BaseArtifact`: The base class for all artifacts.

- `TextArtifact`: A specialized artifact class for handling text values.

- `Artifact`: A class for managing file artifacts, including their content and version history.


**Example**:
```python
from swarms.artifacts import *

# Create instances of the artifact classes
base_artifact = BaseArtifact(id="1", name="Base Artifact", value="Some value")  # This will raise an error since BaseArtifact is abstract
text_artifact = TextArtifact(value="Sample text")
file_artifact = Artifact(file_path="example.txt", file_type=".txt")

# Use the classes as needed
print(text_artifact)  # Output: Sample text
``` 

**Note**: Since `BaseArtifact` is an abstract class, it cannot be instantiated directly.


# Agents

### `swarms.agents.__init__`

**Description**:  
This module serves as the initialization point for the agents subpackage within the Swarms framework. It imports and exposes key classes and functions related to agent operations, including stopping conditions and the `ToolAgent` class, making them available for use in other parts of the application.

**Imports**:
- `check_cancelled`: A function to check if the operation has been cancelled.

- `check_complete`: A function to check if the operation is complete.

- `check_done`: A function to check if the operation is done.

- `check_end`: A function to check if the operation has ended.

- `check_error`: A function to check if there was an error during the operation.

- `check_exit`: A function to check if the operation has exited.

- `check_failure`: A function to check if the operation has failed.

- `check_finished`: A function to check if the operation has finished.

- `check_stopped`: A function to check if the operation has been stopped.

- `check_success`: A function to check if the operation was successful.

- `ToolAgent`: A class representing an agent that utilizes tools.


**Exported Classes and Functions**:
- `ToolAgent`: The class for managing tool-based agents.

- `check_done`: Checks if the operation is done.

- `check_finished`: Checks if the operation has finished.

- `check_complete`: Checks if the operation is complete.

- `check_success`: Checks if the operation was successful.

- `check_failure`: Checks if the operation has failed.

- `check_error`: Checks if there was an error during the operation.

- `check_stopped`: Checks if the operation has been stopped.

- `check_cancelled`: Checks if the operation has been cancelled.

- `check_exit`: Checks if the operation has exited.

- `check_end`: Checks if the operation has ended.


**Example**:
```python
from swarms.agents import *

# Create an instance of ToolAgent
tool_agent = ToolAgent()

# Check the status of an operation
if check_done():
    print("The operation is done.")
```

**Note**: The specific implementations of the stopping condition functions and the `ToolAgent` class are not detailed in this module, as they are imported from other modules within the `swarms.agents` package.




### `swarms.agents.tool_agent`

**Description**:  
This module defines the `ToolAgent` class, which represents a specialized agent capable of performing tasks using a specified model and tokenizer. It is designed to run operations that require input validation against a JSON schema, generating outputs based on defined tasks.

**Imports**:
- `Any`, `Optional`, `Callable`: Type hints from the `typing` module for flexible parameter types.

- `Agent`: The base class for agents, imported from `swarms.structs.agent`.

- `Jsonformer`: A class responsible for transforming JSON data, imported from `swarms.tools.json_former`.

- `logger`: A logging utility from `swarms.utils.loguru_logger`.


### `ToolAgent`
**Description**:  
Represents a tool agent that performs a specific task using a model and tokenizer. It facilitates the execution of tasks by calling the appropriate model or using the defined JSON schema for structured output.

**Attributes**:  
- `name` (`str`): The name of the tool agent.

- `description` (`str`): A description of what the tool agent does.

- `model` (`Any`): The model used by the tool agent for processing.

- `tokenizer` (`Any`): The tokenizer used by the tool agent to prepare input data.

- `json_schema` (`Any`): The JSON schema that defines the structure of the expected output.

- `max_number_tokens` (`int`): The maximum number of tokens to generate (default is 500).

- `parsing_function` (`Optional[Callable]`): A function for parsing the output, if provided.

- `llm` (`Any`): A language model, if utilized instead of a custom model.


**Methods**:

- `__init__(self, name: str, description: str, model: Any, tokenizer: Any, json_schema: Any, max_number_tokens: int, parsing_function: Optional[Callable], llm: Any, *args, 
**kwargs) -> None`

    - **Description**: Initializes a new instance of the ToolAgent class.
    
    - **Parameters**: 
    
      - `name` (`str`): The name of the tool agent.
      
      - `description` (`str`): A description of the tool agent.
      
      - `model` (`Any`): The model to use (if applicable).
      
      - `tokenizer` (`Any`): The tokenizer to use (if applicable).
      
      - `json_schema` (`Any`): The JSON schema that outlines the expected output format.
      
      - `max_number_tokens` (`int`): Maximum token output size.
      
      - `parsing_function` (`Optional[Callable]`): Optional function to parse the output.
      
      - `llm` (`Any`): The language model to use as an alternative to a custom model.
      
      - `*args` and `**kwargs`: Additional arguments and keyword arguments for flexibility.
      
    - **Return**: None.
    

- `run(self, task: str, *args, **kwargs) -> Any`

    - **Description**: Executes the tool agent for the specified task, utilizing either a model or a language model based on provided parameters.
    
    - **Parameters**: 
    
      - `task` (`str`): The task or prompt to be processed by the tool agent.
      
      - `*args`: Additional positional arguments for flexibility.
      
      - `**kwargs`: Additional keyword arguments for flexibility.
      
    - **Return**: 
    
      - (`Any`): The output generated by the tool agent based on the input task.
      
    - **Raises**: 
    
      - `Exception`: If neither `model` nor `llm` is provided or if an error occurs during task execution.
      

**Example**:
```python
from transformers import AutoModelForCausalLM, AutoTokenizer
from swarms.agents.tool_agent import ToolAgent

# Load model and tokenizer
model = AutoModelForCausalLM.from_pretrained("databricks/dolly-v2-12b")

tokenizer = AutoTokenizer.from_pretrained("databricks/dolly-v2-12b")


# Define a JSON schema
json_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "is_student": {"type": "boolean"},
        "courses": {
            "type": "array",
            "items": {"type": "string"}
        }
    }
}

# Create and run a ToolAgent
task = "Generate a person's information based on the following schema:"
agent = ToolAgent(model=model, tokenizer=tokenizer, json_schema=json_schema)
generated_data = agent.run(task)

print(generated_data)
```




### `swarms.agents.stopping_conditions`

**Description**:  
This module contains a set of functions that check specific stopping conditions based on strings. These functions return boolean values indicating the presence of certain keywords, which can be used to determine the status of an operation or process.

### Functions:

- `check_done(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "<DONE>". 
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "<DONE>" is found in the string; otherwise, `False`.
      

- `check_finished(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "finished".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "finished" is found in the string; otherwise, `False`.
      

- `check_complete(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "complete".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "complete" is found in the string; otherwise, `False`.
      

- `check_success(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "success".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "success" is found in the string; otherwise, `False`.
      

- `check_failure(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "failure".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "failure" is found in the string; otherwise, `False`.
      

- `check_error(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "error".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "error" is found in the string; otherwise, `False`.
      

- `check_stopped(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "stopped".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "stopped" is found in the string; otherwise, `False`.
      

- `check_cancelled(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "cancelled".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "cancelled" is found in the string; otherwise, `False`.
      

- `check_exit(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "exit".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "exit" is found in the string; otherwise, `False`.
      

- `check_end(s: str) -> bool`

    - **Description**: Checks if the string contains the keyword "end".
    
    - **Parameters**: 
    
      - `s` (`str`): The input string to check.
      
    - **Return**: 
    
      - (`bool`): `True` if "end" is found in the string; otherwise, `False`.
      

**Example**:
```python
from swarms.agents.stopping_conditions import check_done, check_error

status_message = "The process has finished and <DONE>!"

if check_done(status_message):
    print("The operation is done!")

if check_error(status_message):
    print("An error has occurred!")
``` 

**Note**: Each of these functions provides a simple way to check for specific keywords in a given string, which can be helpful in managing and monitoring tasks or operations.



# Schemas

### `swarms.schemas.base_schemas`

**Description**:  
This module defines various Pydantic models that represent schemas used in machine learning applications. These models facilitate data validation and serialization for different types of content, such as model cards, chat messages, and responses. 

**Imports**:
- `uuid`: A module for generating unique identifiers.

- `time`: A module for time-related functions.

- `List`, `Literal`, `Optional`, `Union`: Type hints from the `typing` module for flexible parameter types.

- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management.


### `ModelCard`
**Description**:  
A Pydantic model that represents a model card, which provides metadata about a machine learning model.

**Attributes**:  
- `id` (`str`): The unique identifier for the model.

- `object` (`str`): A fixed string indicating the type of object ("model").

- `created` (`int`): The timestamp of model creation, defaults to the current time.

- `owned_by` (`str`): The owner of the model.

- `root` (`Optional[str]`): The root model identifier if applicable.

- `parent` (`Optional[str]`): The parent model identifier if applicable.

- `permission` (`Optional[list]`): A list of permissions associated with the model.


### `ModelList`
**Description**:  
A Pydantic model that represents a list of model cards.

**Attributes**:  
- `object` (`str`): A fixed string indicating the type of object ("list").

- `data` (`List[ModelCard]`): A list containing instances of `ModelCard`.


### `ImageUrl`
**Description**:  
A Pydantic model representing an image URL.

**Attributes**:  
- `url` (`str`): The URL of the image.


### `TextContent`
**Description**:  
A Pydantic model representing text content.

**Attributes**:  
- `type` (`Literal["text"]`): A fixed string indicating the type of content (text).

- `text` (`str`): The actual text content.


### `ImageUrlContent`
**Description**:  
A Pydantic model representing image content via URL.

**Attributes**:  
- `type` (`Literal["image_url"]`): A fixed string indicating the type of content (image URL).

- `image_url` (`ImageUrl`): An instance of `ImageUrl` containing the URL of the image.


### `ContentItem`
**Description**:  
A type alias for a union of `TextContent` and `ImageUrlContent`, representing any content type that can be processed.

### `ChatMessageInput`
**Description**:  
A Pydantic model representing an input message for chat applications.

**Attributes**:  
- `role` (`str`): The role of the sender (e.g., "user", "assistant", or "system").

- `content` (`Union[str, List[ContentItem]]`): The content of the message, which can be a string or a list of content items.


### `ChatMessageResponse`
**Description**:  
A Pydantic model representing a response message in chat applications.

**Attributes**:  
- `role` (`str`): The role of the sender (e.g., "user", "assistant", or "system").

- `content` (`str`, optional): The content of the response message.


### `DeltaMessage`
**Description**:  
A Pydantic model representing a delta update for messages in chat applications.

**Attributes**:  
- `role` (`Optional[Literal["user", "assistant", "system"]]`): The role of the sender, if specified.

- `content` (`Optional[str]`): The content of the delta message, if provided.


### `ChatCompletionRequest`
**Description**:  
A Pydantic model representing a request for chat completion.

**Attributes**:  
- `model` (`str`): The model to use for completing the chat (default is "gpt-4o").

- `messages` (`List[ChatMessageInput]`): A list of input messages for the chat.

- `temperature` (`Optional[float]`): Controls the randomness of the output (default is 0.8).

- `top_p` (`Optional[float]`): An alternative to sampling with temperature (default is 0.8).

- `max_tokens` (`Optional[int]`): The maximum number of tokens to generate (default is 4000).

- `stream` (`Optional[bool]`): If true, the response will be streamed (default is False).

- `repetition_penalty` (`Optional[float]`): A penalty for repeated tokens (default is 1.0).

- `echo` (`Optional[bool]`): If true, the input will be echoed in the output (default is False).


### `ChatCompletionResponseChoice`
**Description**:  
A Pydantic model representing a choice in a chat completion response.

**Attributes**:  
- `index` (`int`): The index of the choice.

- `input` (`str`): The input message.

- `message` (`ChatMessageResponse`): The output message.


### `ChatCompletionResponseStreamChoice`
**Description**:  
A Pydantic model representing a choice in a streamed chat completion response.

**Attributes**:  
- `index` (`int`): The index of the choice.

- `delta` (`DeltaMessage`): The delta update for the message.


### `UsageInfo`
**Description**:  
A Pydantic model representing usage information for a chat completion request.

**Attributes**:  
- `prompt_tokens` (`int`): The number of tokens used in the prompt (default is 0).

- `total_tokens` (`int`): The total number of tokens used (default is 0).

- `completion_tokens` (`Optional[int]`): The number of tokens used in the completion (default is 0).


### `ChatCompletionResponse`
**Description**:  
A Pydantic model representing a response from a chat completion request.

**Attributes**:  
- `model` (`str`): The model used for the completion.

- `object` (`Literal["chat.completion", "chat.completion.chunk"]`): The type of response object.

- `choices` (`List[Union[ChatCompletionResponseChoice, ChatCompletionResponseStreamChoice]]`): A list of choices from the completion.

- `created` (`Optional[int]`): The timestamp of when the response was created.


### `AgentChatCompletionResponse`
**Description**:  
A Pydantic model representing a completion response from an agent.

**Attributes**:  
- `id` (`Optional[str]`): The ID of the agent that generated the completion response (default is a new UUID).

- `agent_name` (`Optional[str]`): The name of the agent that generated the response.

- `object` (`Optional[Literal["chat.completion", "chat.completion.chunk"]]`): The type of response object.

- `choices` (`Optional[ChatCompletionResponseChoice]`): The choice from the completion response.

- `created` (`Optional[int]`): The timestamp of when the response was created.


**Example**:
```python
from swarms.schemas.base_schemas import ChatCompletionRequest, ChatMessageInput

# Create a chat completion request
request = ChatCompletionRequest(
    model="gpt-4",
    
    messages=[
        ChatMessageInput(role="user", content="Hello! How can I help you?")
    ]
)
``` 

**Note**: The Pydantic models in this module provide a structured way to handle data related to machine learning models and chat interactions, ensuring that the data adheres to defined schemas.




### `swarms.schemas.plan`

**Description**:  
This module defines the `Plan` class, which represents a sequence of steps in a structured format. It utilizes Pydantic for data validation and configuration, ensuring that each plan consists of a list of defined steps.

**Imports**:
- `List`: A type hint from the `typing` module for work with lists.

- `BaseModel`: The Pydantic base class for data models, providing validation and serialization features.

- `Step`: A model representing individual steps in the plan, imported from `swarms.schemas.agent_step_schemas`.


### `Plan`
**Description**:  
Represents a sequence of steps that comprise a plan. This class ensures that the data structure adheres to the expected model for steps.

**Attributes**:  
- `steps` (`List[Step]`): A list of steps, where each step is an instance of the `Step` model.


**Config**:
- `orm_mode` (bool): Enables compatibility with ORM models to facilitate data loading from database objects.


**Example**:
```python
from swarms.schemas.plan import Plan
from swarms.schemas.agent_step_schemas import Step

# Create a list of steps
steps = [
    Step(/* initialize step attributes */),
    Step(/* initialize step attributes */),
]

# Create a Plan instance
plan = Plan(steps=steps)

# Access the steps
for step in plan.steps:
    print(step)
```

**Note**: The `Plan` class relies on the `Step` model for its structure, ensuring that the steps in a plan conform to the validation rules defined in the `Step` model.




### `swarms.schemas.__init__`

**Description**:  
This module serves as the initialization point for the schemas subpackage within the Swarms framework. It imports and exposes key classes related to agent steps and agent input schemas, making them available for use in other parts of the application.

**Imports**:
- `Step`: A model representing an individual step in an agent's operation, imported from `swarms.schemas.agent_step_schemas`.

- `ManySteps`: A model representing multiple steps, also imported from `swarms.schemas.agent_step_schemas`.

- `AgentSchema`: A model representing the schema for agent inputs, imported from `swarms.schemas.agent_input_schema`.


**Exported Classes**:
- `Step`: The class for defining individual steps in an agent's operation.

- `ManySteps`: The class for defining multiple steps in an agent's operation.

- `AgentSchema`: The class for defining the input schema for agents.


**Example**:
```python
from swarms.schemas import *

# Create an instance of Step
step = Step(/* initialize step attributes */)

# Create an instance of ManySteps
many_steps = ManySteps(steps=[step, step])

# Create an instance of AgentSchema
agent_schema = AgentSchema(/* initialize agent schema attributes */)
```

**Note**: This module acts as a central point for importing and utilizing the various schema classes defined in the Swarms framework, facilitating structured data handling for agents and their operations.




### `swarms.schemas.agent_step_schemas`

**Description**:  
This module defines the `Step` and `ManySteps` classes, which represent individual steps and collections of steps in a task, respectively. These classes utilize Pydantic for data validation and serialization, ensuring that each step adheres to the defined schema.

**Imports**:
- `time`: A module for time-related functions.

- `uuid`: A module for generating unique identifiers.

- `List`, `Optional`, `Any`: Type hints from the `typing` module for flexible parameter types.

- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management.

- `AgentChatCompletionResponse`: A model representing the response from an agent's chat completion, imported from `swarms.schemas.base_schemas`.


### `get_current_time() -> str`

**Description**:  
Returns the current time formatted as "YYYY-MM-DD HH:MM:SS".


**Return**:  
- (`str`): The current time as a formatted string.


### `Step`
**Description**:  
A Pydantic model representing a single step in a task, including its ID, completion time, and response from an agent.

**Attributes**:  
- `step_id` (`Optional[str]`): The unique identifier for the step, generated if not provided.

- `time` (`Optional[float]`): The time taken to complete the task step, formatted as a string.

- `response` (`Optional[AgentChatCompletionResponse]`): The response from the agent for this step.


### `ManySteps`
**Description**:  
A Pydantic model representing a collection of steps associated with a specific agent and task.

**Attributes**:  
- `agent_id` (`Optional[str]`): The unique identifier for the agent.

- `agent_name` (`Optional[str]`): The name of the agent.

- `task` (`Optional[str]`): The name of the task being performed.

- `max_loops` (`Optional[Any]`): The maximum number of steps in the task.

- `run_id` (`Optional[str]`): The ID of the task this collection of steps belongs to.

- `steps` (`Optional[List[Step]]`): A list of `Step` instances representing the steps of the task.

- `full_history` (`Optional[str]`): A string containing the full history of the task.

- `total_tokens` (`Optional[int]`): The total number of tokens generated during the task.

- `stopping_token` (`Optional[str]`): The token at which the task stopped.

- `interactive` (`Optional[bool]`): Indicates whether the task is interactive.

- `dynamic_temperature_enabled` (`Optional[bool]`): Indicates whether dynamic temperature adjustments are enabled for the task.


**Example**:
```python
from swarms.schemas.agent_step_schemas import Step, ManySteps

# Create a step instance
step = Step(step_id="12345", response=AgentChatCompletionResponse(...))

# Create a ManySteps instance
many_steps = ManySteps(
    agent_id="agent-1",
    
    agent_name="Test Agent",
    task="Example Task",
    max_loops=5,
    steps=[step],
    full_history="Task executed successfully.",
    total_tokens=100
)

print(many_steps)
```

**Note**: The `Step` and `ManySteps` classes provide structured representations of task steps, ensuring that all necessary information is captured and validated according to the defined schemas.




### `swarms.schemas.agent_input_schema`

**Description**:  
This module defines the `AgentSchema` class using Pydantic, which represents the input parameters necessary for configuring an agent in the Swarms framework. It includes a variety of attributes for specifying the agent's behavior, model settings, and operational parameters.

**Imports**:
- `Any`, `Callable`, `Dict`, `List`, `Optional`: Type hints from the `typing` module for flexible parameter types.

- `BaseModel`, `Field`: Tools from the `pydantic` module for data validation and settings management.

- `validator`: A decorator from Pydantic used for custom validation of fields.


### `AgentSchema`
**Description**:  
Represents the configuration for an agent, including attributes that govern its behavior, capabilities, and interaction with language models. This class ensures that the input data adheres to defined validation rules.

**Attributes**:  
- `llm` (`Any`): The language model to use.

- `max_tokens` (`int`): The maximum number of tokens the agent can generate, must be greater than or equal to 1.

- `context_window` (`int`): The size of the context window, must be greater than or equal to 1.

- `user_name` (`str`): The name of the user interacting with the agent.

- `agent_name` (`str`): The name of the agent.

- `system_prompt` (`str`): The system prompt provided to the agent.

- `template` (`Optional[str]`): An optional template for the agent, default is `None`.

- `max_loops` (`Optional[int]`): The maximum number of loops the agent can perform (default is 1, must be greater than or equal to 1).

- `stopping_condition` (`Optional[Callable[[str], bool]]`): A callable function that defines a stopping condition for the agent.

- `loop_interval` (`Optional[int]`): The interval between loops (default is 0, must be greater than or equal to 0).

- `retry_attempts` (`Optional[int]`): Number of times to retry an operation if it fails (default is 3, must be greater than or equal to 0).

- `retry_interval` (`Optional[int]`): The time between retry attempts (default is 1, must be greater than or equal to 0).

- `return_history` (`Optional[bool]`): Flag indicating whether to return the history of the agent's operations (default is `False`).

- `stopping_token` (`Optional[str]`): Token indicating when to stop processing (default is `None`).

- `dynamic_loops` (`Optional[bool]`): Indicates whether dynamic loops are enabled (default is `False`).

- `interactive` (`Optional[bool]`): Indicates whether the agent operates in an interactive mode (default is `False`).

- `dashboard` (`Optional[bool]`): Flag indicating whether a dashboard interface is enabled (default is `False`).

- `agent_description` (`Optional[str]`): A description of the agent's functionality (default is `None`).

- `tools` (`Optional[List[Callable]]`): List of callable tools the agent can use (default is `None`).

- `dynamic_temperature_enabled` (`Optional[bool]`): Indicates whether dynamic temperature adjustments are enabled (default is `False`).

- Additional attributes for managing various functionalities and configurations related to the agent's behavior, such as logging, saving states, and managing tools.


### Validators:

- **check_list_items_not_none(v)**: Ensures that items within certain list attributes (`tools`, `docs`, `sop_list`, etc.) are not `None`.

- **check_optional_callable_not_none(v)**: Ensures that optional callable attributes are either `None` or callable.


**Example**:
```python
from swarms.schemas.agent_input_schema import AgentSchema

# Define the agent configuration data
agent_data = {
    "llm": "OpenAIChat",
    "max_tokens": 4096,
    "context_window": 8192,
    "user_name": "Human",
    "agent_name": "test-agent",
    
    "system_prompt": "Custom system prompt",
}

# Create an AgentSchema instance
agent = AgentSchema(**agent_data)
print(agent)
```

**Note**: The `AgentSchema` class provides a structured way to configure agents in the Swarms framework, ensuring that all necessary parameters are validated before use.




--------------------------------------------------

# File: swarms/framework/test.md

# How to Run Tests Using Pytest: A Comprehensive Guide

In modern software development, automated testing is crucial for ensuring the reliability and functionality of your code. One of the most popular testing frameworks for Python is `pytest`. 

This blog will provide an in-depth look at how to run tests using `pytest`, including testing a single file, multiple files, every file in the test repository, and providing guidelines for contributors to run tests reliably.

## What is Pytest?

`pytest` is a testing framework for Python that makes it easy to write simple and scalable test cases. It supports fixtures, parameterized testing, and has a rich plugin architecture. `pytest` is widely used because of its ease of use and powerful features that help streamline the testing process.

## Installation

To get started with `pytest`, you need to install it. You can install `pytest` using `pip`:

```bash
pip install pytest
```

## Writing Your First Test

Before diving into running tests, let’s write a simple test. Create a file named `test_sample.py` with the following content:

```python
def test_addition():
    assert 1 + 1 == 2

def test_subtraction():
    assert 2 - 1 == 1
```

In this example, we have defined two basic tests: `test_addition` and `test_subtraction`.

## Running Tests

### Running a Single Test File

To run a single test file, you can use the `pytest` command followed by the filename. For example, to run the tests in `test_sample.py`, use the following command:

```bash
pytest test_sample.py
```

The output will show the test results, including the number of tests passed, failed, or skipped.

### Running Multiple Test Files

You can also run multiple test files by specifying their filenames separated by a space. For example:

```bash
pytest test_sample.py test_another_sample.py
```

If you have multiple test files in a directory, you can run all of them by specifying the directory name:

```bash
pytest tests/
```

### Running All Tests in the Repository

To run all tests in the repository, navigate to the root directory of your project and simply run:

```bash
pytest
```

`pytest` will automatically discover and run all the test files that match the pattern `test_*.py` or `*_test.py`.

### Test Discovery

`pytest` automatically discovers test files and test functions based on their naming conventions. By default, it looks for files that match the pattern `test_*.py` or `*_test.py` and functions or methods that start with `test_`.

### Using Markers

`pytest` allows you to use markers to group tests or add metadata to them. Markers can be used to run specific subsets of tests. For example, you can mark a test as `slow` and then run only the slow tests or skip them.

```python
import pytest

@pytest.mark.slow
def test_long_running():
    import time
    time.sleep(5)
    assert True

def test_fast():
    assert True
```

To run only the tests marked as `slow`, use the `-m` option:

```bash
pytest -m slow
```

### Parameterized Tests

`pytest` supports parameterized testing, which allows you to run a test with different sets of input data. This can be done using the `@pytest.mark.parametrize` decorator.

```python
import pytest

@pytest.mark.parametrize("a,b,expected", [
    (1, 2, 3),
    (2, 3, 5),
    (3, 5, 8),
])
def test_add(a, b, expected):
    assert a + b == expected
```

In this example, `test_add` will run three times with different sets of input data.

### Fixtures

Fixtures are a powerful feature of `pytest` that allow you to set up some context for your tests. They can be used to provide a fixed baseline upon which tests can reliably and repeatedly execute.

```python
import pytest

@pytest.fixture
def sample_data():
    return {"name": "John", "age": 30}

def test_sample_data(sample_data):
    assert sample_data["name"] == "John"
    assert sample_data["age"] == 30
```

Fixtures can be used to share setup and teardown code between tests.

## Advanced Usage

### Running Tests in Parallel

`pytest` can run tests in parallel using the `pytest-xdist` plugin. To install `pytest-xdist`, run:

```bash
pip install pytest-xdist
```

To run tests in parallel, use the `-n` option followed by the number of CPU cores you want to use:

```bash
pytest -n 4
```

### Generating Test Reports

`pytest` can generate detailed test reports. You can use the `--html` option to generate an HTML report:

```bash
pip install pytest-html
pytest --html=report.html
```

This command will generate a file named `report.html` with a detailed report of the test results.

### Code Coverage

You can use the `pytest-cov` plugin to measure code coverage. To install `pytest-cov`, run:

```bash
pip install pytest-cov
```

To generate a coverage report, use the `--cov` option followed by the module name:

```bash
pytest --cov=my_module
```

This command will show the coverage summary in the terminal. You can also generate an HTML report:

```bash
pytest --cov=my_module --cov-report=html
```

The coverage report will be generated in the `htmlcov` directory.

## Best Practices for Writing Tests

1. **Write Clear and Concise Tests**: Each test should focus on a single piece of functionality.
2. **Use Descriptive Names**: Test function names should clearly describe what they are testing.
3. **Keep Tests Independent**: Tests should not depend on each other and should run in isolation.
4. **Use Fixtures**: Use fixtures to set up the context for your tests.
5. **Mock External Dependencies**: Use mocking to isolate the code under test from external dependencies.

## Running Tests Reliably

For contributors and team members, it’s important to run tests reliably to ensure consistent results. Here are some guidelines:

1. **Set Up a Virtual Environment**: Use a virtual environment to manage dependencies and ensure a consistent testing environment.
   
    ```bash
    python -m venv venv
    source venv/bin/activate  # On Windows use `venv\Scripts\activate`
    ```

2. **Install Dependencies**: Install all required dependencies from the `requirements.txt` file.
   
    ```bash
    pip install -r requirements.txt
    ```

3. **Run Tests Before Pushing**: Ensure all tests pass before pushing code to the repository.

4. **Use Continuous Integration (CI)**: Set up CI pipelines to automatically run tests on each commit or pull request.

### Example CI Configuration (GitHub Actions)

Here is an example of a GitHub Actions workflow to run tests using `pytest`:

```yaml
name: Python package

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.8'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Run tests
      run: |
        pytest
```

This configuration will run the tests on every push and pull request, ensuring that your codebase remains stable.

## Conclusion

`pytest` is a powerful and flexible testing framework that makes it easy to write and run tests for your Python code. By following the guidelines and best practices outlined in this blog, you can ensure that your tests are reliable and your codebase is robust. Whether you are testing a single file, multiple files, or the entire repository, `pytest` provides the tools you need to automate and streamline your testing process.

Happy testing!

--------------------------------------------------

# File: swarms/framework/vision.md

### Swarms Vision

**Swarms** is dedicated to transforming enterprise automation by offering a robust and intuitive interface for multi-agent collaboration and seamless integration with multiple models. Our mission is to enable enterprises to enhance their operational efficiency and effectiveness through intelligent automation.

#### Vision Statement

**To become the preeminent framework for orchestrating multi-agent collaboration and integration, empowering enterprises to achieve exceptional automation efficiency and operational excellence.**

#### Core Principles

1. **Multi-Agent Collaboration**: Facilitate seamless collaboration between diverse agents to solve complex and dynamic problems.
2. **Integration**: Provide robust and flexible integration with various models and frameworks to maximize functionality.
3. **Enterprise Automation**: Deliver enterprise-grade solutions designed for reliability, scalability, and security.
4. **Open Ecosystem**: Promote an open and extensible ecosystem that encourages innovation, community engagement, and collaborative development.

### Vision Document with Mermaid Graphs

#### Overview Diagram

```mermaid
graph TD
    A[Swarms Framework] --> B[Multi-Agent Collaboration]
    A --> C[Integration with Multiple Models]
    A --> D[Enterprise Automation]
    A --> E[Open Ecosystem]

    B --> F[Seamless Communication]
    B --> G[Collaboration Protocols]
    
    C --> H[Model Integration]
    C --> I[Framework Compatibility]

    D --> J[Operational Efficiency]
    D --> K[Reliability and Scalability]

    E --> L[Encourage Innovation]
    E --> M[Community Driven]
```

#### Multi-Agent Collaboration

```mermaid
graph TD
    B[Multi-Agent Collaboration] --> F[Seamless Communication]
    B --> G[Collaboration Protocols]

    F --> N[Cross-Agent Messaging]
    F --> O[Task Coordination]
    F --> P[Real-Time Updates]

    G --> Q[Standard APIs]
    G --> R[Extensible Protocols]
    G --> S[Security and Compliance]

    N --> T[Agent Messaging Hub]
    O --> U[Task Assignment and Monitoring]
    P --> V[Instantaneous Data Sync]

    Q --> W[Unified API Interface]
    R --> X[Customizable Protocols]
    S --> Y[Compliance with Standards]
    S --> Z[Secure Communication Channels]
```

#### Integration with Multiple Models

```mermaid
graph TD
    C[Integration with Multiple Models] --> H[Model Integration]
    C --> I[Framework Compatibility]

    H --> R[Plug-and-Play Models]
    H --> S[Model Orchestration]
    H --> T[Model Versioning]

    I --> U[Support for OpenAI]
    I --> V[Support for Anthropic]
    I --> W[Support for Gemini]
    I --> X[Support for LangChain]
    I --> Y[Support for AutoGen]
    I --> Z[Support for Custom Models]

    R --> AA[Easy Model Integration]
    S --> AB[Dynamic Model Orchestration]
    T --> AC[Version Control]

    U --> AD[Integration with OpenAI Models]
    V --> AE[Integration with Anthropic Models]
    W --> AF[Integration with Gemini Models]
    X --> AG[Integration with LangChain Models]
    Y --> AH[Integration with AutoGen Models]
    Z --> AI[Support for Proprietary Models]
```

#### Enterprise Automation

```mermaid
graph TD
    D[Enterprise Automation] --> J[Operational Efficiency]
    D --> K[Reliability and Scalability]

    J --> Y[Automate Workflows]
    J --> Z[Reduce Manual Work]
    J --> AA[Increase Productivity]

    K --> AB[High Uptime]
    K --> AC[Enterprise-Grade Security]
    K --> AD[Scalable Solutions]

    Y --> AE[Workflow Automation Tools]
    Z --> AF[Eliminate Redundant Tasks]
    AA --> AG[Boost Employee Efficiency]

    AB --> AH[Robust Infrastructure]
    AC --> AI[Security Compliance]
    AD --> AJ[Scale with Demand]
```

#### Open Ecosystem

```mermaid
graph TD
    E[Open Ecosystem] --> L[Encourage Innovation]
    E --> M[Community Driven]

    L --> AC[Open Source Contributions]
    L --> AD[Hackathons and Workshops]
    L --> AE[Research and Development]

    M --> AF[Active Community Support]
    M --> AG[Collaborative Development]
    M --> AH[Shared Resources]

    AC --> AI[Community Contributions]
    AD --> AJ[Innovative Events]
    AE --> AK[Continuous R&D]

    AF --> AL[Supportive Community]
    AG --> AM[Joint Development Projects]
    AH --> AN[Shared Knowledge Base]
```

---

### Conclusion

Swarms excels in enabling seamless communication and coordination between multiple agents, fostering a collaborative environment where agents can work together to solve complex tasks. Our platform supports cross-agent messaging, task coordination, and real-time updates, ensuring that all agents are synchronized and can efficiently contribute to the collective goal.

Swarms provides robust integration capabilities with a wide array of models, including OpenAI, Anthropic, Gemini, LangChain, AutoGen, and custom models. This ensures that enterprises can leverage the best models available to meet their specific needs, while also allowing for dynamic model orchestration and version control to keep operations up-to-date and effective.

Our framework is designed to enhance operational efficiency through automation. By automating workflows, reducing manual work, and increasing productivity, Swarms helps enterprises achieve higher efficiency and operational excellence. Our solutions are built for high uptime, enterprise-grade security, and scalability, ensuring reliable and secure operations.

Swarms promotes an open and extensible ecosystem, encouraging community-driven innovation and development. We support open-source contributions, organize hackathons and workshops, and continuously invest in research and development. Our active community fosters collaborative development, shared resources, and a supportive environment for innovation.

**Swarms** is dedicated to providing a comprehensive and powerful framework for enterprises seeking to automate operations through multi-agent collaboration and integration with various models. Our commitment to an open ecosystem, enterprise-grade automation solutions, and seamless multi-agent collaboration ensures that Swarms remains the leading choice for enterprises aiming to achieve operational excellence through intelligent automation.

--------------------------------------------------

# File: swarms/glossary.md

# Glossary of Terms

**Agent**:  
An LLM (Large Language Model) equipped with tools and memory, operating with a specific objective in a loop. An agent can perform tasks, interact with other agents, and utilize external tools and memory systems to achieve its goals.

**Swarms**:  
A group of more than two agents working together and communicating to accomplish a shared objective. Swarms enable complex, collaborative tasks that leverage the strengths of multiple agents.

**Tool**:  
A Python function that is converted into a function call, allowing agents to perform specific actions or access external resources. Tools enhance the capabilities of agents by providing specialized functionalities.

**Memory System**:  
A system for managing information retrieval and storage, often implemented as a Retrieval-Augmented Generation (RAG) system or a memory vector database. Memory systems enable agents to recall previous interactions, store new information, and improve decision-making based on historical data.

**LLM (Large Language Model)**:  
A type of AI model designed to understand and generate human-like text. LLMs, such as GPT-3 or GPT-4, are used as the core computational engine for agents.

**System Prompt**:  
A predefined prompt that sets the context and instructions for an agent's task. The system prompt guides the agent's behavior and response generation.

**Max Loops**:  
The maximum number of iterations an agent will perform to complete its task. This parameter helps control the extent of an agent's processing and ensures tasks are completed efficiently.

**Dashboard**:  
A user interface that provides real-time monitoring and control over the agents and their activities. Dashboards can display agent status, logs, and performance metrics.

**Streaming On**:  
A setting that enables agents to stream their output incrementally, providing real-time feedback as they process tasks. This feature is useful for monitoring progress and making adjustments on the fly.

**Verbose**:  
A setting that controls the level of detail in an agent's output and logging. When verbose mode is enabled, the agent provides more detailed information about its operations and decisions.

**Multi-modal**:  
The capability of an agent to process and integrate multiple types of data, such as text, images, and audio. Multi-modal agents can handle more complex tasks that require diverse inputs.

**Autosave**:  
A feature that automatically saves the agent's state and progress at regular intervals. Autosave helps prevent data loss and allows for recovery in case of interruptions.

**Flow**:  
The predefined sequence in which agents in a swarm interact and process tasks. The flow ensures that each agent's output is appropriately passed to the next agent, facilitating coordinated efforts.

**Long Term Memory**:  
A component of the memory system that retains information over extended periods, enabling agents to recall and utilize past interactions and experiences.

**Output Schema**:  
A structured format for the output generated by agents, often defined using data models like Pydantic's BaseModel. Output schemas ensure consistency and clarity in the information produced by agents.

By understanding these terms, you can effectively build and orchestrate agents and swarms, leveraging their capabilities to perform complex, collaborative tasks.

--------------------------------------------------

# File: swarms/install/docker_setup.md

# Docker Setup Guide for Contributors to Swarms


Welcome to the `swarms` project Docker setup guide. This document will help you establish a Docker-based environment for contributing to `swarms`. Docker provides a consistent and isolated environment, ensuring that all contributors can work in the same settings, reducing the "it works on my machine" syndrome.

### Purpose

The purpose of this guide is to:

- Ensure contributors can quickly set up their development environment.
- Provide a consistent testing and deployment workflow.
- Introduce Docker basics and best practices.

### Scope

This guide covers:

- Installing Docker
- Cloning the `swarms` repository
- Building a Docker image
- Running the `swarms` application in a Docker container
- Running tests using Docker
- Pushing changes and working with Docker Hub


## Docker Installation

### Windows

1. Download Docker Desktop for Windows from the official website.
2. Install Docker Desktop, ensuring that the "Use Windows containers instead of Linux containers" option is unchecked.
3. Start Docker Desktop and wait for the Docker engine to start.

### macOS

1. Download Docker Desktop for macOS from the official website.
2. Follow the installation instructions, drag-and-drop Docker into the Applications folder.
3. Start Docker Desktop from the Applications folder.

### Linux (Ubuntu)

1. Update your package index: `sudo apt-get update`.
2. Install packages to allow apt to use a repository over HTTPS.
3. Add Docker’s official GPG key.
4. Set up the stable repository.
5. Install the latest version of Docker Engine and containerd.

```bash
sudo apt-get install docker-ce docker-ce-cli containerd.io
```

6. Verify that Docker Engine is installed correctly by running the hello-world image.

```bash
sudo docker run hello-world
```

### Post-installation Steps for Linux

- Manage Docker as a non-root user.
- Configure Docker to start on boot.

## Cloning the Repository

```bash
git clone https://github.com/your-username/swarms.git
cd swarms
```

## Docker Basics

### Dockerfile Overview

- Explain the structure and commands of a Dockerfile used in the `swarms` project.

### Building the Image

```bash
docker build -t swarms-dev .
```

### Running a Container

```bash
docker run -it --rm swarms-dev
```

## Development Workflow with Docker

### Running the Application

- Commands to run the `swarms` application within Docker.

### Making Changes

- How to make changes to the code and reflect those changes within the Docker container.

### Running Tests

- Instructions on running tests using `pytest` within the Docker environment.

## Docker Compose for Local Development

- Introduce Docker Compose and its role in simplifying multi-container setups.
- Create a `docker-compose.yml` file for the `swarms` project.


## Dockerfile

Creating a Dockerfile for deploying the `swarms` framework to the cloud involves setting up the necessary environment to run your Python application, ensuring all dependencies are installed, and configuring the container to execute the desired tasks. Here's an example Dockerfile that sets up such an environment:

```Dockerfile
# Use an official Python runtime as a parent image
FROM python:3.11-slim

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE 1
ENV PYTHONUNBUFFERED 1

# Set the working directory in the container
WORKDIR /usr/src/swarm_cloud

# Install system dependencies
RUN apt-get update \
    && apt-get -y install gcc \
    && apt-get clean

# Install Python dependencies
# COPY requirements.txt and pyproject.toml if you're using poetry for dependency management
COPY requirements.txt .
RUN pip install --upgrade pip
RUN pip install --no-cache-dir -r requirements.txt

# Install the 'swarms' package, assuming it's available on PyPI
ENV SWARM_API_KEY=your_swarm_api_key_here
ENV OPENAI_API_KEY=your_openai_key
RUN pip install swarms

# Copy the rest of the application
COPY . .

# Add entrypoint script if needed
# COPY ./entrypoint.sh .
# RUN chmod +x /usr/src/swarm_cloud/entrypoint.sh

# Expose port if your application has a web interface
# EXPOSE 5000

# Define environment variable for the swarm to work
# Add Docker CMD or ENTRYPOINT script to run the application
# CMD python your_swarm_startup_script.py
# Or use the entrypoint script if you have one
# ENTRYPOINT ["/usr/src/swarm_cloud/entrypoint.sh"]

# If you're using `CMD` to execute a Python script, make sure it's executable
# RUN chmod +x your_swarm_startup_script.py
```

To build and run this Docker image:

1. Replace `requirements.txt` with your actual requirements file or `pyproject.toml` and `poetry.lock` if you're using Poetry.
2. Replace `your_swarm_startup_script.py` with the script that starts your application.
3. If your application requires an API key or other sensitive data, make sure to set these securely, perhaps using environment variables or secrets management solutions provided by your cloud provider.
4. If you have an entrypoint script, uncomment the `COPY` and `RUN` lines for `entrypoint.sh`.
5. If your application has a web interface, uncomment the `EXPOSE` line and set it to the correct port.

Now, build your Docker image:

```sh
docker build -t swarm-cloud .
```

And run it:

```sh
docker run -d --name my-swarm-app swarm-cloud
```

For deploying to the cloud, you'll need to push your Docker image to a container registry (like Docker Hub or a private registry), then pull it from your cloud environment to run it. Cloud providers often have services specifically for this purpose (like AWS ECS, GCP GKE, or Azure AKS). The deployment process will involve:

- Pushing the image to a registry.
- Configuring cloud services to run your image.
- Setting up networking, storage, and other cloud resources.
- Monitoring, logging, and potentially scaling your containers.

Remember to secure sensitive data, use tagged releases for your images, and follow best practices for operating in the cloud.


--------------------------------------------------

# File: swarms/install/env.md

# Environment Variables

## Overview

Swarms uses environment variables for configuration management and secure credential storage. This approach keeps sensitive information like API keys out of your code and allows for easy configuration changes across different environments.

## Core Environment Variables

### Framework Configuration

=== "Configuration Variables"

    | Variable | Description | Example |
    |----------|-------------|---------|
    | `SWARMS_VERBOSE_GLOBAL` | Controls global logging verbosity | `True` or `False` |
    | `WORKSPACE_DIR` | Defines the workspace directory for agent operations | `agent_workspace` |

### LLM Provider API Keys

=== "OpenAI"
    ```bash
    OPENAI_API_KEY="your-openai-key"
    ```

=== "Anthropic"
    ```bash
    ANTHROPIC_API_KEY="your-anthropic-key"
    ```

=== "Groq"
    ```bash
    GROQ_API_KEY="your-groq-key"
    ```

=== "Google"
    ```bash
    GEMINI_API_KEY="your-gemini-key"
    ```

=== "Hugging Face"
    ```bash
    HUGGINGFACE_TOKEN="your-huggingface-token"
    ```

=== "Perplexity AI"
    ```bash
    PPLX_API_KEY="your-perplexity-key"
    ```

=== "AI21"
    ```bash
    AI21_API_KEY="your-ai21-key"
    ```

=== "Cohere"
    ```bash
    COHERE_API_KEY="your-cohere-key"
    ```

=== "Mistral AI"
    ```bash
    MISTRAL_API_KEY="your-mistral-key"
    ```

=== "Together AI"
    ```bash
    TOGETHER_API_KEY="your-together-key"
    ```

### Tool Provider Keys

=== "Search Tools"
    ```bash
    BING_BROWSER_API="your-bing-key"
    BRAVESEARCH_API_KEY="your-brave-key"
    TAVILY_API_KEY="your-tavily-key"
    YOU_API_KEY="your-you-key"
    ```

=== "Analytics & Monitoring"
    ```bash
    EXA_API_KEY="your-exa-key"
    ```

=== "Browser Automation"
    ```bash
    MULTION_API_KEY="your-multion-key"
    ```

## Security Best Practices

### Environment File Management

1. Create a `.env` file in your project root
2. Never commit `.env` files to version control
3. Add `.env` to your `.gitignore`:
    ```bash
    echo ".env" >> .gitignore
    ```

### API Key Security

!!! warning "Important Security Considerations"
    - Rotate API keys regularly
    - Use different API keys for development and production
    - Never hardcode API keys in your code
    - Limit API key permissions to only what's necessary
    - Monitor API key usage for unusual patterns

### Template Configuration

Create a `.env.example` template without actual values:

```bash
# Required Configuration
OPENAI_API_KEY=""
ANTHROPIC_API_KEY=""
GROQ_API_KEY=""
WORKSPACE_DIR="agent_workspace"

# Optional Configuration
SWARMS_VERBOSE_GLOBAL="False"
```

### Loading Environment Variables

```python
from dotenv import load_dotenv
import os

# Load environment variables
load_dotenv()

# Access variables
workspace_dir = os.getenv("WORKSPACE_DIR")
openai_key = os.getenv("OPENAI_API_KEY")
```

## Environment Setup Guide

=== "1. Install Dependencies"
    ```bash
    pip install python-dotenv
    ```

=== "2. Create Environment File"
    ```bash
    cp .env.example .env
    ```

=== "3. Configure Variables"
    - Open `.env` in your text editor
    - Add your API keys and configuration
    - Save the file

=== "4. Verify Setup"
    ```python
    import os
    from dotenv import load_dotenv

    load_dotenv()
    assert os.getenv("OPENAI_API_KEY") is not None, "OpenAI API key not found"
    ```

## Environment-Specific Configuration

=== "Development"
    ```bash
    WORKSPACE_DIR="agent_workspace"
    SWARMS_VERBOSE_GLOBAL="True"
    ```

=== "Production"
    ```bash
    WORKSPACE_DIR="/var/swarms/workspace"
    SWARMS_VERBOSE_GLOBAL="False"
    ```

=== "Testing"
    ```bash
    WORKSPACE_DIR="test_workspace"
    SWARMS_VERBOSE_GLOBAL="True"
    ```

## Troubleshooting

### Common Issues

???+ note "Environment Variables Not Loading"
    - Verify `.env` file exists in project root
    - Confirm `load_dotenv()` is called before accessing variables
    - Check file permissions

???+ note "API Key Issues"
    - Verify key format is correct
    - Ensure key has not expired
    - Check for leading/trailing whitespace

???+ note "Workspace Directory Problems"
    - Confirm directory exists
    - Verify write permissions
    - Check path is absolute when required


--------------------------------------------------

# File: swarms/install/install.md

# Swarms Installation Guide

<div align="center">
  <p>
    <a align="center" href="" target="_blank">
      <img
        width="850"
        src="https://github.com/kyegomez/swarms/raw/master/images/swarmslogobanner.png"
      >
    </a>
  </p>
</div>

You can install `swarms` with pip in a
[**Python>=3.10**](https://www.python.org/) environment.

## Prerequisites

Before you begin, ensure you have the following installed:

- Python 3.10 or higher: [Download Python](https://www.python.org/)
- pip (specific version recommended): `pip >= 21.0`
- git (for cloning the repository): [Download Git](https://git-scm.com/)

## Installation Options

=== "pip (Recommended)"

    #### Simple Installation

    Simplest manner of installing swarms leverages using PIP. For faster installs and build times, we recommend using UV

    ```bash
    pip install swarms
    ```

=== "UV Installation"

    UV is a fast Python package installer and resolver written in Rust. It's significantly faster than pip and provides better dependency resolution.

    === "Basic Installation"

        ```bash
        # Install UV first
        curl -LsSf https://astral.sh/uv/install.sh | sh

        # Install swarms using UV
        uv pip install swarms
        ```

    === "Development Installation"

        ```bash
        # Clone the repository
        git clone https://github.com/kyegomez/swarms.git
        cd swarms

        # Install in editable mode
        uv pip install -e .
        ```

        For desktop installation with extras:

        ```bash
        uv pip install -e .[desktop]
        ```

=== "Poetry Installation"

    Poetry is a modern dependency management and packaging tool for Python. It provides a more robust way to manage project dependencies and virtual environments.

    === "Basic Installation"

        ```bash
        # Install Poetry first
        curl -sSL https://install.python-poetry.org | python3 -

        # Install swarms using Poetry
        poetry add swarms
        ```

    === "Development Installation"

        ```bash
        # Clone the repository
        git clone https://github.com/kyegomez/swarms.git
        cd swarms

        # Install in editable mode
        poetry install
        ```

        For desktop installation with extras:

        ```bash
        poetry install --extras "desktop"
        ```

    === "Using Poetry with existing projects"

        If you have an existing project with a `pyproject.toml` file:

        ```bash
        # Add swarms to your project dependencies
        poetry add swarms

        # Or add with specific extras
        poetry add "swarms[desktop]"
        ```

=== "Development Installation"

    === "Using virtualenv"

        1. **Clone the repository and navigate to the root directory:**

            ```bash
            git clone https://github.com/kyegomez/swarms.git
            cd swarms
            ```

        2. **Setup Python environment and activate it:**

            ```bash
            python3 -m venv venv
            source venv/bin/activate
            pip install --upgrade pip
            ```

        3. **Install Swarms:**

            - Headless install:

                ```bash
                pip install -e .
                ```

            - Desktop install:

                ```bash
                pip install -e .[desktop]
                ```

    === "Using Anaconda"

        1. **Create and activate an Anaconda environment:**

            ```bash
            conda create -n swarms python=3.10
            conda activate swarms
            ```

        2. **Clone the repository and navigate to the root directory:**

            ```bash
            git clone https://github.com/kyegomez/swarms.git
            cd swarms
            ```

        3. **Install Swarms:**

            - Headless install:

                ```bash
                pip install -e .
                ```

            - Desktop install:

                ```bash
                pip install -e .[desktop]
                ```

    === "Using Poetry"

        1. **Clone the repository and navigate to the root directory:**

            ```bash
            git clone https://github.com/kyegomez/swarms.git
            cd swarms
            ```

        2. **Setup Python environment and activate it:**

            ```bash
            poetry env use python3.10
            poetry shell
            ```

        3. **Install Swarms:**

            - Headless install:

                ```bash
                poetry install
                ```

            - Desktop install:

                ```bash
                poetry install --extras "desktop"
                ```

=== "Using Docker"

    Docker is an excellent option for creating isolated and reproducible environments, suitable for both development and production. Contact us if there are any issues with the docker setup

    1. **Pull the Docker image:**

        ```bash
        docker pull swarmscorp/swarms:tagname

        ```

    2. **Run the Docker container:**

        ```bash
        docker run -it --rm swarmscorp/swarms:tagname
        ```

    3. **Build and run a custom Docker image:**

        ```dockerfile
        # Use Python 3.11 instead of 3.13
        FROM python:3.11-slim

        # Set environment variables
        ENV PYTHONDONTWRITEBYTECODE=1 \
            PYTHONUNBUFFERED=1 \
            WORKSPACE_DIR="agent_workspace" \
            OPENAI_API_KEY="your_swarm_api_key_here"

        # Set the working directory
        WORKDIR /usr/src/swarms

        # Install system dependencies
        RUN apt-get update && apt-get install -y \
            build-essential \
            gcc \
            g++ \
            gfortran \
            && rm -rf /var/lib/apt/lists/*

        # Install swarms package
        RUN pip3 install -U swarm-models
        RUN pip3 install -U swarms

        # Copy the application
        COPY . .
        ```

=== "Using Kubernetes"

    Kubernetes provides an automated way to deploy, scale, and manage containerized applications.

    1. **Create a Deployment YAML file:**

        ```yaml
        apiVersion: apps/v1
        kind: Deployment
        metadata:
          name: swarms-deployment
        spec:
          replicas: 3
          selector:
            matchLabels:
              app: swarms
          template:
            metadata:
              labels:
                app: swarms
            spec:
              containers:
              - name: swarms
                image: kyegomez/swarms
                ports:
                - containerPort: 8080
        ```

    2. **Apply the Deployment:**

        ```bash
        kubectl apply -f deployment.yaml
        ```

    3. **Expose the Deployment:**

        ```bash
        kubectl expose deployment swarms-deployment --type=LoadBalancer --name=swarms-service
        ```

=== "CI/CD Pipelines"

    Integrating Swarms into your CI/CD pipeline ensures automated testing and deployment.

    #### Using GitHub Actions

    ```yaml
    # .github/workflows/ci.yml
    name: CI

    on:
      push:
        branches: [ main ]
      pull_request:
        branches: [ main ]

    jobs:
      build:

        runs-on: ubuntu-latest

        steps:
        - uses: actions/checkout@v2
        - name: Set up Python
          uses: actions/setup-python@v2
          with:
            python-version: 3.10
        - name: Install dependencies
          run: |
            python -m venv venv
            source venv/bin/activate
            pip install --upgrade pip
            pip install -e .
        - name: Run tests
          run: |
            source venv/bin/activate
            pytest
    ```

    #### Using Jenkins

    ```groovy
    pipeline {
        agent any

        stages {
            stage('Clone repository') {
                steps {
                    git 'https://github.com/kyegomez/swarms.git'
                }
            }
            stage('Setup Python') {
                steps {
                    sh 'python3 -m venv venv'
                    sh 'source venv/bin/activate && pip install --upgrade pip'
                }
            }
            stage('Install dependencies') {
                steps {
                    sh 'source venv/bin/activate && pip install -e .'
                }
            }
            stage('Run tests') {
                steps {
                    sh 'source venv/bin/activate && pytest'
                }
            }
        }
    }
    ```

## Rust

=== "Cargo install"

    Get started with the Rust implementation of Swarms. [Get started with the docs here](https://docs.swarms.world/en/latest/swarms_rs/overview/)

    ```bash
    cargo add swarms-rs
    ```




--------------------------------------------------

# File: swarms/install/quickstart.md

## Quickstart

**Swarms** is an enterprise-grade, production-ready multi-agent collaboration framework that enables you to orchestrate agents to work collaboratively at scale to automate real-world activities. Follow this quickstart guide to get up and running with Swarms, including setting up your environment, building an agent, and leveraging multi-agent methods.

### **Requirements**

- Python 3.10 or above
- `.env` file with API keys from your providers like `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`
- Set an environment variable for your workspace directory:
  ```bash
  WORKSPACE_DIR="agent_workspace"
  ```

### **Installation**

To install Swarms, run:
```bash
$ pip install -U swarms
```

### **Usage Example: Single Agent**

Here's a simple example of creating a financial analysis agent powered by OpenAI's GPT-4o-mini model. This agent will analyze financial queries like how to set up a ROTH IRA.

```python
from swarms.structs.agent import Agent

# Initialize the agent with GPT-4o-mini model
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="Analyze financial situations and provide advice...",
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=True,
    saved_state_path="finance_agent.json",
    model_name="gpt-4o-mini",
)

# Run your query
out = agent.run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?"
)
print(out)
```

#### **Agent Class**

- **Attributes:**
  - `agent_name`: Name of the agent.
  - `system_prompt`: System-level instruction guiding the agent's behavior.
  - `model_name`: Name of the model to use (e.g., "gpt-4o-mini").
  - `max_loops`: Max iterations for a task.
  - `autosave`: Auto-saves the state after each iteration.
  
- **Methods:**
  - `run(task: str)`: Executes the agent's task.
  - `ingest_docs(doc_path: str)`: Ingests documents into the agent's knowledge base.
  - `filtered_run(task: str)`: Runs agent with a filtered system prompt.

-----

## Creating Agents from YAML


### Step 1: Define Your Agents in a YAML File

The `create_agents_from_yaml` function works by reading agent configurations from a YAML file. Below is an example of what your YAML file (`agents_config.yaml`) should look like this. Example YAML Configuration (`agents_config.yaml`):

```yaml
agents:
  - agent_name: "Financial-Analysis-Agent"
    system_prompt: "You are a financial analysis expert. Analyze market trends and provide investment recommendations."
    model_name: "claude-3-opus-20240229"
    max_loops: 1
    autosave: false
    dashboard: false
    verbose: false
    dynamic_temperature_enabled: false
    user_name: "swarms_corp"
    retry_attempts: 1
    context_length: 200000
    return_step_meta: false
    output_type: "str"
    temperature: 0.1
    max_tokens: 2000
    task: "Analyze tech stocks for 2024 investment strategy. Provide detailed analysis and recommendations."

  - agent_name: "Risk-Analysis-Agent"
    system_prompt: "You are a risk analysis expert. Evaluate investment risks and provide mitigation strategies."
    model_name: "claude-3-opus-20240229"
    max_loops: 1
    autosave: false
    dashboard: false
    verbose: false
    dynamic_temperature_enabled: false
    user_name: "swarms_corp"
    retry_attempts: 1
    context_length: 150000
    return_step_meta: false
    output_type: "str"
    temperature: 0.1
    max_tokens: 2000
    task: "Conduct a comprehensive risk analysis of the top 5 tech companies in 2024. Include risk factors and mitigation strategies."

swarm_architecture:
  name: "Financial Analysis Swarm"
  description: "A swarm for comprehensive financial and risk analysis"
  max_loops: 1
  swarm_type: "SequentialWorkflow"
  task: "Analyze tech stocks and their associated risks for 2024 investment strategy"
  autosave: false
  return_json: true
```

### Key Configuration Fields:
- **agent_name**: Name of the agent.
- **system_prompt**: The system prompt used to guide the agent's behavior.
- **model_name**: The language model to use (e.g., claude-3-opus-20240229).
- **task**: Task for the agent to execute.
- **swarm_architecture**: (Optional) Configuration for swarm behavior.

---

### Step 2: Create the Main Script

Now, create the main Python script that will use the `create_agents_from_yaml` function.

### `main.py`:
```python
from swarms.agents.create_agents_from_yaml import create_agents_from_yaml

# Create agents and get task results
task_results = create_agents_from_yaml(
    yaml_file="agents_config.yaml",
    return_type="run_swarm"
)

print(task_results)
```

### Example Run:

```bash
python main.py
```

This will:
1. Load agent configurations from `agents_config.yaml`.
2. Create the agents specified in the YAML file.
3. Run the tasks provided for each agent.
4. Output the task results to the console.

---

### Step 3: Customize the Return Type

The `create_agents_from_yaml` function supports multiple return types. You can control what is returned by setting the `return_type` parameter to `"agents"`, `"tasks"`, or `"both"`.

1. **Return Only Agents**
To create agents but not run tasks, set `return_type="agents"`:

```python
agents = create_agents_from_yaml(yaml_file, return_type="agents")
for agent in agents:
    print(f"Agent {agent.agent_name} created.")
```

2. **Return Only Task Results**
If you only care about the task results and not the agent objects, set `return_type="tasks"`:

```python
task_results = create_agents_from_yaml(yaml_file, return_type="tasks")
for result in task_results:
    print(f"Agent {result['agent_name']} executed task '{result['task']}' with output: {result['output']}")
```

3. **Return Both Agents and Task Results**
To return both the list of created agents and task results, use `return_type="both"`:

```python
agents, task_results = create_agents_from_yaml(yaml_file, return_type="both")
# Process agents and tasks separately
```


## Step 4: YAML Structure for Multiple Agents

The YAML file can define any number of agents, each with its own unique configuration. You can scale this setup by adding more agents and tasks to the `agents` list within the YAML file.

```yaml
agents:
  - agent_name: "Agent1"
    # Agent1 config...

  - agent_name: "Agent2"
    # Agent2 config...

  - agent_name: "Agent3"
    # Agent3 config...
```

Each agent will be initialized according to its configuration, and tasks (if provided) will be executed automatically.

---

## Integrating External Agents
Integrating external agents from other agent frameworks is easy with swarms.

Steps:

1. Create a new class that inherits `Agent`
2. Create a `.run(task: str) -> str` method that runs the agent and returns the response. 
3. The new Agent must return a string of the response. But you may add additional methods to save the output to JSON.


### Griptape Example

For example, here's an example on how to create an agent from griptape.

Here's how you can create a custom **Griptape** agent that integrates with the **Swarms** framework by inheriting from the `Agent` class in **Swarms** and overriding the `run(task: str) -> str` method.


```python
from swarms import (
    Agent as SwarmsAgent,
)  # Import the base Agent class from Swarms
from griptape.structures import Agent as GriptapeAgent
from griptape.tools import (
    WebScraperTool,
    FileManagerTool,
    PromptSummaryTool,
)


# Create a custom agent class that inherits from SwarmsAgent
class GriptapeSwarmsAgent(SwarmsAgent):
    def __init__(self, *args, **kwargs):
        # Initialize the Griptape agent with its tools
        self.agent = GriptapeAgent(
            input="Load {{ args[0] }}, summarize it, and store it in a file called {{ args[1] }}.",
            tools=[
                WebScraperTool(off_prompt=True),
                PromptSummaryTool(off_prompt=True),
                FileManagerTool(),
            ],
            *args,
            **kwargs,
            # Add additional settings
        )

    # Override the run method to take a task and execute it using the Griptape agent
    def run(self, task: str) -> str:
        # Extract URL and filename from task (you can modify this parsing based on task structure)
        url, filename = task.split(
            ","
        )  # Example of splitting task string
        # Execute the Griptape agent with the task inputs
        result = self.agent.run(url.strip(), filename.strip())
        # Return the final result as a string
        return str(result)


# Example usage:
griptape_swarms_agent = GriptapeSwarmsAgent()
output = griptape_swarms_agent.run(
    "https://griptape.ai, griptape.txt"
)
print(output)
```

### Key Components:
1. **GriptapeSwarmsAgent**: A custom class that inherits from the `SwarmsAgent` class and integrates the Griptape agent.
2. **run(task: str) -> str**: A method that takes a task string, processes it (e.g., splitting into a URL and filename), and runs the Griptape agent with the provided inputs.
3. **Griptape Tools**: The tools integrated into the Griptape agent (e.g., `WebScraperTool`, `PromptSummaryTool`, `FileManagerTool`) allow for web scraping, summarization, and file management.

You can now easily plug this custom Griptape agent into the **Swarms Framework** and use it to run tasks!





## Overview of Swarm Architectures in the Swarms Framework
---

### 1. **Sequential Workflow**

**Overview**: The `SequentialWorkflow` enables tasks to be executed one after the other. Each agent processes its task and passes the output to the next agent in the sequence.

#### Mermaid Graph:

```mermaid
graph TD;
    A[Task Input] --> B[Blog Generator Agent];
    B --> C[Summarizer Agent];
    C --> D[Task Output];
```

#### Code Example:

```python
from swarms import Agent, SequentialWorkflow

# Initialize agents without importing a specific LLM class
agent1 = Agent(
    agent_name="Blog generator",
    system_prompt="Generate a blog post",
    model_name="claude-3-sonnet-20240229",
    max_loops=1
)
agent2 = Agent(
    agent_name="Summarizer",
    system_prompt="Summarize the blog post",
    model_name="claude-3-sonnet-20240229",
    max_loops=1
)

# Create Sequential workflow
workflow = SequentialWorkflow(agents=[agent1, agent2], max_loops=1)

# Run workflow
output = workflow.run("Generate a blog post on how swarms of agents can help businesses grow.")
print(output)
```

---

### 2. **Agent Rearrange**

**Overview**: `AgentRearrange` allows the orchestration of agents in both sequential and parallel configurations. The user can define a flexible flow of tasks between agents.

#### Mermaid Graph:

```mermaid
graph TD;
    A[Director Agent] --> B[Worker 1 Agent];
    A --> C[Worker 2 Agent];
    B --> D[Task Completed];
    C --> D[Task Completed];
```

#### Code Example:

```python
from swarms import Agent, AgentRearrange

# Initialize agents using model_name (no explicit LLM import)
director = Agent(
    agent_name="Director",
    system_prompt="Directs tasks",
    model_name="claude-3-sonnet-20240229",
    max_loops=1
)
worker1 = Agent(
    agent_name="Worker1",
    system_prompt="Generate a transcript",
    model_name="claude-3-sonnet-20240229",
    max_loops=1
)
worker2 = Agent(
    agent_name="Worker2",
    system_prompt="Summarize the transcript",
    model_name="claude-3-sonnet-20240229",
    max_loops=1
)

# Define the flow and create the rearranged system
flow = "Director -> Worker1 -> Worker2"
agent_system = AgentRearrange(agents=[director, worker1, worker2], flow=flow)

# Run it
output = agent_system.run("Create a YouTube transcript and summary")
print(output)
```



---

### 4. **Mixture of Agents**

**Overview**: `MixtureOfAgents` is a parallelized architecture where agents perform tasks concurrently and then feed their results back into a loop for final aggregation. This is useful for highly parallelizable tasks.

#### Mermaid Graph:

```mermaid
graph TD;
    A[Director Agent] --> B[Accountant 1];
    A --> C[Accountant 2];
    B --> D[Final Aggregation];
    C --> D[Final Aggregation];
```

#### Code Example:

```python
from swarms import Agent, OpenAIChat, MixtureOfAgents

# Initialize agents
director = Agent(agent_name="Director", system_prompt="Directs tasks", llm=OpenAIChat(), max_loops=1)
accountant1 = Agent(agent_name="Accountant1", system_prompt="Prepare financial statements", llm=OpenAIChat(), max_loops=1)
accountant2 = Agent(agent_name="Accountant2", system_prompt="Audit financial records", llm=OpenAIChat(), max_loops=1)

# Create Mixture of Agents swarm
swarm = MixtureOfAgents(name="Mixture of Accountants", agents=[director, accountant1, accountant2], layers=3, final_agent=director)

# Run the swarm
output = swarm.run("Prepare financial statements and audit financial records")
print(output)
```

---

### 5. **Spreadsheet Swarm**

**Overview**: `SpreadSheetSwarm` enables the management of thousands of agents simultaneously, where each agent operates on its own thread. It's ideal for overseeing large-scale agent outputs.

#### Mermaid Graph:

```mermaid
graph TD;
    A[Spreadsheet Swarm] --> B[Twitter Agent];
    A --> C[Instagram Agent];
    A --> D[Facebook Agent];
    A --> E[LinkedIn Agent];
    A --> F[Email Agent];
```

#### Code Example:

```python
from swarms import Agent
from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm

# Initialize agents for different marketing platforms using model_name
agents = [
    Agent(
        agent_name="Twitter Agent",
        system_prompt="Create a tweet",
        model_name="gpt-4o-mini",
        max_loops=1
    ),
    Agent(
        agent_name="Instagram Agent",
        system_prompt="Create an Instagram post",
        model_name="gpt-4o-mini",
        max_loops=1
    ),
    Agent(
        agent_name="Facebook Agent",
        system_prompt="Create a Facebook post",
        model_name="gpt-4o-mini",
        max_loops=1
    ),
    Agent(
        agent_name="LinkedIn Agent",
        system_prompt="Create a LinkedIn post",
        model_name="gpt-4o-mini",
        max_loops=1
    ),
    Agent(
        agent_name="Email Agent",
        system_prompt="Write a marketing email",
        model_name="gpt-4o-mini",
        max_loops=1
    ),
]

# Create the Spreadsheet Swarm
swarm = SpreadSheetSwarm(
    agents=agents,
    save_file_path="real_estate_marketing_spreadsheet.csv",
    run_all_agents=False,
    max_loops=2
)

# Run the swarm
swarm.run("Create posts to promote luxury properties in North Texas.")
```

---

These are the key swarm architectures available in the **Swarms Framework**. Each one is designed to solve different types of multi-agent orchestration problems, from sequential tasks to large-scale parallel processing.


### Overview of Swarm Architectures
#### **Workflow Classes**

- **SequentialWorkflow:**
  - Chains agents, where one agent's output becomes the next agent's input.
  
- **AgentRearrange:**
  - Dynamically rearranges agent tasks either in parallel or sequentially based on defined flow.

#### **Swarm Architectures**

- **Hierarchical Swarms:**
  - Implements top-down control, where a boss agent coordinates tasks among sub-agents.
  
- **Spreadsheet Swarm:**
  - A large-scale swarm architecture for managing multiple agents working concurrently.



--------------------------------------------------

# File: swarms/install/workspace_manager.md

# Swarms Framework Environment Configuration

This guide details the environment variables used in the Swarms framework for configuration and customization of your agent-based applications.

## Configuration Setup

Create a `.env` file in your project's root directory to configure the Swarms framework. This file will contain all necessary environment variables for customizing your agent's behavior, logging, and analytics.

## Environment Variables

### Core Variables

#### `WORKSPACE_DIR`
- **Purpose**: Defines the directory where all agent states and execution logs are stored
- **Type**: String (path)
- **Default**: `./workspace`
- **Example**: 
```bash
WORKSPACE_DIR=/path/to/your/workspace
```
- **Usage**:
  - Stores JSON files containing agent states
  - Maintains execution history
  - Keeps track of agent interactions
  - Preserves conversation logs

#### `SWARMS_AUTOUPDATE_ON`
- **Purpose**: Controls automatic updates of the Swarms framework
- **Type**: Boolean
- **Default**: `false`
- **Example**:
```bash
SWARMS_AUTOUPDATE_ON=true
```
- **Features**:
  - Automatically updates to the latest stable version
  - Ensures you have the newest features
  - Maintains compatibility with the latest improvements
  - Handles dependency updates
- **Considerations**:
  - Set to `false` if you need version stability
  - Recommended `true` for development environments
  - Consider system requirements for auto-updates
  - May require restart after updates

### Telemetry Configuration

#### `USE_TELEMETRY`
- **Purpose**: Controls whether telemetry data is collected
- **Type**: Boolean
- **Default**: `false`
- **Example**:
```bash
USE_TELEMETRY=true
```
- **Data Collected**:
  - Agent performance metrics
  - Execution time statistics
  - Memory usage
  - Error rates
  - System health indicators

### Analytics Integration

#### `SWARMS_API_KEY`
- **Purpose**: Authentication key for the Swarms Analytics Suite
- **Type**: String
- **Required**: Yes, for analytics features
- **Example**:
```bash
SWARMS_API_KEY=your_api_key_here
```
- **Features**:
  - Real-time agent execution tracking
  - Usage analytics
  - Performance monitoring
  - Cost tracking
  - Custom metrics

## Getting Started

1. Create a new `.env` file:
```bash
touch .env
```

2. Add your configuration:
```bash
# Basic configuration
WORKSPACE_DIR=./my_workspace

# Enable auto-updates
SWARMS_AUTOUPDATE_ON=true

# Enable telemetry
USE_TELEMETRY=true

# Add your Swarms API key
SWARMS_API_KEY=your_api_key_here
```

3. Obtain your API key:
   - Visit [swarms.ai](https://swarms.ai)
   - Create an account or log in
   - Navigate to the API section
   - Generate your unique API key

## Best Practices

1. **Security**:
   - Never commit your `.env` file to version control
   - Add `.env` to your `.gitignore` file
   - Keep your API keys secure and rotate them periodically

2. **Workspace Organization**:
   - Use descriptive workspace directory names
   - Implement regular cleanup of old logs
   - Monitor workspace size to prevent disk space issues

3. **Telemetry Management**:
   - Enable telemetry in development for debugging
   - Consider privacy implications in production
   - Review collected data periodically

4. **Auto-Update Management**:
   - Test updates in development before enabling in production
   - Keep backups before enabling auto-updates
   - Monitor system resources during updates
   - Schedule updates during low-traffic periods

## Examples

### Basic Development Setup
```bash
WORKSPACE_DIR=./dev_workspace
SWARMS_AUTOUPDATE_ON=true
USE_TELEMETRY=true
SWARMS_API_KEY=sk_test_xxxxxxxxxxxx
```

### Production Setup
```bash
WORKSPACE_DIR=/var/log/swarms/prod_workspace
SWARMS_AUTOUPDATE_ON=false
USE_TELEMETRY=true
SWARMS_API_KEY=sk_prod_xxxxxxxxxxxx
```

### Testing Environment
```bash
WORKSPACE_DIR=./test_workspace
SWARMS_AUTOUPDATE_ON=true
USE_TELEMETRY=false
SWARMS_API_KEY=sk_test_xxxxxxxxxxxx
```

## Troubleshooting

Common issues and solutions:

1. **Workspace Access Issues**:
   - Ensure proper file permissions
   - Verify the directory exists
   - Check disk space availability

2. **API Key Problems**:
   - Confirm key is properly formatted
   - Verify key hasn't expired
   - Check for proper environment variable loading

3. **Telemetry Issues**:
   - Confirm network connectivity
   - Verify firewall settings
   - Check for proper boolean values

4. **Auto-Update Issues**:
   - Check internet connectivity
   - Verify sufficient disk space
   - Ensure proper permissions for updates
   - Check system compatibility requirements

## Additional Resources

- [Swarms Framework Documentation](https://github.com/kyegomez/swarms)
- [Swarms Analytics Dashboard](https://swarms.ai)
- [API Reference](https://swarms.ai/docs/api)

--------------------------------------------------

# File: swarms/memory/diy_memory.md

# Integrating the Agent Class with Memory Systems/RAG in the Swarms Memory Framework

In this guide, we will cover how to integrate various memory systems from the Swarms Memory framework into an agent class. The Swarms Memory framework allows for the integration of different database-backed memory systems, enabling agents to retain and query long-term knowledge effectively. We'll walk through examples of integrating with Pinecone, ChromaDB, and Faiss, showcasing how to configure custom functions and embed memory functionality into an agent class.

## Installation

First, you need to install the Swarms Memory package:

```bash
$ pip install swarms swarms-memory
```


### Integrating ChromaDB with the Agent Class

ChromaDB is a simple, high-performance vector store for use with embeddings. Here's how you can integrate ChromaDB:

```python
from swarms_memory import ChromaDB
from swarms.structs.agent import Agent

# Initialize ChromaDB memory
chromadb_memory = ChromaDB(
    metric="cosine",
    output_dir="finance_agent_rag",
)

# Initialize the Financial Analysis Agent with GPT-4o-mini model
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
    model_name="gpt-4o-mini",
    long_term_memory=chromadb_memory,
)

# Run a query
response = agent.run(
    "What are the components of a startup's stock incentive equity plan?"
)
print(response)
```

### Integrating Faiss with the Agent Class

Faiss is a library for efficient similarity search and clustering of dense vectors. Here's how you can integrate Faiss:

```python
from typing import List, Dict, Any
from swarms_memory.faiss_wrapper import FAISSDB
from swarms import Agent
from swarm_models import Anthropic
from transformers import AutoTokenizer, AutoModel
import torch
import os

# Custom embedding function using a HuggingFace model
def custom_embedding_function(text: str) -> List[float]:
    tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
    model = AutoModel.from_pretrained("bert-base-uncased")
    inputs = tokenizer(
        text,
        return_tensors="pt",
        padding=True,
        truncation=True,
        max_length=512,
    )
    with torch.no_grad():
        outputs = model(**inputs)
    embeddings = (
        outputs.last_hidden_state.mean(dim=1).squeeze().tolist()
    )
    return embeddings

# Initialize the FAISS memory wrapper
faiss_memory = FAISSDB(
    dimension=768,
    index_type="Flat",
    embedding_function=custom_embedding_function,
    metric="cosine",
)

# Model
model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"))

# Initialize the agent with Faiss memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="Agent system prompt here",
    agent_description="Agent performs financial analysis.",
    llm=model,
    long_term_memory=faiss_memory,
)

# Run a query
agent.run("Explain the differences between various types of financial instruments.")
```

## Mermaid Graphs for Visualizing Integration

To help visualize the integration process, here's a Mermaid graph illustrating how an agent interacts with the memory systems:

```mermaid
graph TD;
    A[Agent] -->|Queries| B[Memory System]
    B --> C{Pinecone / ChromaDB / Faiss}
    C --> D[Embedding Function]
    D --> E[LLM Model]
    E --> F[Query Results]
    F -->|Returns| A
```

This graph shows the flow from the agent sending queries to the memory system, which processes them using the embedding function and LLM model, and finally returns the results back to the agent.

## Conclusion

Integrating various memory systems from the Swarms Memory framework into the agent class enables the creation of powerful, memory-augmented agents capable of retaining and recalling information over time. Whether you're using Pinecone, ChromaDB, or Faiss, the process involves initializing the memory system, embedding functions, and then passing this memory system to the agent class. The examples and visualizations provided should help you get started with building your own memory-augmented agents.

Happy coding!


--------------------------------------------------

# File: swarms/papers.md

# awesome-multi-agent-papers

An awesome list of multi-agent papers that show you various swarm architectures and much more. [Get started](https://github.com/kyegomez/awesome-multi-agent-papers)

--------------------------------------------------

# File: swarms/products.md

# Swarms Products

Welcome to the official documentation for **Swarms**, the first multi-agent orchestration framework enabling seamless collaboration between LLMs and other tools to automate business operations at scale. Below, you’ll find detailed descriptions of all Swarms products and services to help you get started and unlock the full potential of this groundbreaking platform.



| **Name**              | **Description**                                                                                                   | **Link**                  |
|-----------------------|-------------------------------------------------------------------------------------------------------------------|---------------------------|
| **Swarms Marketplace** | A platform to discover, share, and integrate prompts, agents, and tools.                                         | [swarms.world](https://swarms.world) |
| **Swarms Spreadsheet** | A tool for managing and scaling thousands of agent outputs, with results saved to a CSV file for easy analysis.  | [swarms.world](https://swarms.world) |
| **Drag n Drop Swarm**  | An intuitive interface to visually create and manage swarms of agents through drag-and-drop functionality.       | [swarms.world](https://swarms.world) |
| **Swarms API**         | An API enabling seamless integration of swarms of agents into your applications and workflows.                   | [swarms.world](https://swarms.world) |
| **Wallet API**         | A secure API for managing transactions and interactions within the Swarms ecosystem.                             | Coming Soon               |
| **Swarm Exchange**     | A marketplace for buying and selling prompts, agents, and tools within the Swarms ecosystem.                    | Coming Soon               |



---

## Swarms Marketplace
**Website:** [swarms.world](https://swarms.world)

The Swarms Marketplace is your one-stop destination for discovering, adding, and managing:

- **Prompts:** Access and share production-ready prompts for LLMs.

- **Agents:** Browse pre-built agents tailored for tasks in marketing, finance, 
programming, and more.
- **Tools:** Discover cutting-edge tools to enhance agent performance and expand 
capabilities.

### Key Features:
- **Rating System:** Evaluate and rate prompts, agents, and tools based on their 
effectiveness.
- **Commenting System:** Share feedback and insights with the Swarms community.

- **Coming Soon:** Buy and sell prompts, agents, and tools directly within the 
marketplace.

### How to Use:
1. Sign up at [swarms.world](https://swarms.world).
2. Explore the marketplace categories or search for specific solutions.
3. Add your chosen resources to your Swarms account and integrate them into your operations.

---

## Swarms Spreadsheet
**Website:** [swarms.world](https://swarms.world)

The Swarms Spreadsheet is a powerful tool for managing outputs from thousands of agents efficiently. Ideal for businesses needing scalable solutions, it provides:

### Key Features:
- **Batch Task Execution:** Assign tasks to multiple agents simultaneously.

- **CSV Integration:** Automatically save agent outputs to CSV files for easy analysis.

- **Customizable Agents:** Upload single or multiple agents and run repeat tasks with 
ease.
- **Metadata Capture:** Leverage built-in Pydantic schemas to record all task details 
and results.

### Use Cases:
- **Marketing:** Generate and analyze campaign ideas at scale.

- **Finance:** Process financial models and scenarios quickly.

- **Operations:** Automate repetitive tasks across multiple domains.


### How to Use:
1. Visit [swarms.world](https://swarms.world) and navigate to Swarms Spreadsheet.
2. Upload your agents or create new ones.
3. Run tasks and export results to a CSV file for further use.

---

## Drag-n-Drop Swarm
**Website:** [swarms.world](https://swarms.world)

The Drag-n-Drop Swarm enables non-technical users to create and deploy agent workflows with a simple drag-and-drop interface. It’s perfect for:

### Key Features:
- **Visual Workflow Builder:** Design agent interactions without writing code.

- **Pre-Built Templates:** Start quickly with ready-made workflows for common tasks.

- **Intuitive Interface:** Drag, drop, and connect agents to create robust automation 
pipelines.

### How to Use:
1. Access the Drag-n-Drop Swarm tool at [swarms.world](https://swarms.world).
2. Drag agents from the library into the workspace.
3. Connect and configure agents to execute your desired workflow.
4. Save and deploy your workflow instantly.

---

## Swarms API
**Website:** [swarms.world](https://swarms.world)

The Swarms API provides developers with the ability to:

### Key Features:
- **Agent Management:** Programmatically create, update, and delete agents.

- **Task Orchestration:** Dynamically assign tasks to agents and monitor their progress.

- **Custom Integration:** Seamlessly integrate Swarms functionality into existing 
applications and workflows.

### Getting Started:
1. Sign up for API access at [swarms.world](https://swarms.world).
2. Obtain your API key and authentication credentials.
3. Refer to the API documentation for endpoint details and usage examples.

---

## Wallet API
The Wallet API enables secure and efficient transactions within the Swarms ecosystem, allowing users to:

### Key Features:
- **Seamless Transactions:** Manage payments for prompts, agents, and tools.

- **Secure Wallets:** Store and transfer funds safely within the Swarms platform.

- **Transaction History:** Access detailed logs of all wallet activity.


### Getting Started:
1. Enable your wallet in your Swarms account settings.
2. Use the Wallet API to handle purchases and manage funds.

---

## Swarm Exchange (Coming Soon)
The **Swarm Exchange** will revolutionize the way agents and tools are traded in the Swarms ecosystem. It will feature:

### Key Features:
- **Decentralized Marketplace:** Trade agents and tools securely.

- **Dynamic Pricing:** Leverage demand-based pricing for assets.

- **Global Access:** Participate in the exchange from anywhere.


Stay tuned for updates on the Swarm Exchange launch.

---

## Additional Resources
- **GitHub Repository:** [Swarms Framework](https://github.com/kyegomez/swarms)

- **Documentation:** [Swarms Documentation](https://docs.swarms.world)

- **Support:** Contact us via our [Discord Community](https://discord.gg/EamjgSaEQf).

---

Experience the future of multi-agent collaboration with Swarms. Start building your agentic workflows today!



--------------------------------------------------

# File: swarms/prompts/essence.md

# **The Essence of Enterprise-Grade Prompting**

Large Language Models (LLMs) like GPT-4 have revolutionized the landscape of AI-driven automation, customer support, marketing, and more. However, extracting the highest quality output from these models requires a thoughtful approach to crafting prompts—an endeavor that goes beyond mere trial and error. In enterprise settings, where consistency, quality, and performance are paramount, enterprise-grade prompting has emerged as a structured discipline, combining art with the science of human-machine communication.

Enterprise-grade prompting involves understanding the intricate dynamics between language models, context, and the task at hand. It requires knowledge of not only the technical capabilities of LLMs but also the intricacies of how they interpret human language. Effective prompting becomes the linchpin for ensuring that AI-driven outputs are accurate, reliable, and aligned with business needs. It is this discipline that turns raw AI capabilities into tangible enterprise value.

In this essay, we will dissect the essence of enterprise-grade prompting, explore the most effective prompting strategies, explain what works and what doesn't, and conclude with the current holy grail of automated prompt engineering. We will also share concrete examples and illustrations of each technique, with a particular focus on their application in an enterprise setting.

## **1. Foundational Principles of Prompting**

The effectiveness of prompting lies in understanding both the capabilities and limitations of LLMs. A well-structured prompt helps LLMs focus on the most relevant information while avoiding ambiguities that can lead to unreliable results. In enterprise-grade contexts, prompts must be designed with the end-user's expectations in mind, ensuring quality, safety, scalability, and traceability.

- **Clarity**: Prompts should be clear and devoid of unnecessary jargon. Ambiguity can misguide the model, leading to poor-quality output. For enterprise use, clarity means avoiding misunderstandings that could affect customer relationships or lead to non-compliance with regulations.
- **Context**: Providing sufficient context ensures the model understands the nuances of the prompt. For example, specifying whether a response is aimed at a technical audience versus a general audience can lead to more accurate outputs. Context is essential in creating responses that are not only accurate but also relevant to the target audience.
- **Instruction Granularity**: The level of detail in the instruction significantly impacts the quality of the output. Broad instructions might lead to vagueness, whereas overly detailed instructions could overwhelm the model. Finding the right balance is key to generating useful responses.

Example: Instead of prompting "Explain what a blockchain is," an enterprise-grade prompt might be "Explain the concept of blockchain, focusing on how distributed ledgers help increase transparency in supply chain management. Keep the explanation under 200 words for a general audience." This prompt provides clear, relevant, and concise instructions tailored to specific needs.

## **2. Best Prompting Strategies**

The field of enterprise-grade prompting employs numerous strategies to maximize the quality of LLM output. Here are some of the most effective ones:

### **2.1. Instruction-Based Prompting**

Instruction-based prompting provides explicit instructions for the LLM to follow. This approach is valuable in enterprise applications where responses must adhere to a specific tone, structure, or depth of analysis.

**Example**:

- "Summarize the following press release in 3 bullet points suitable for a marketing team meeting."

This prompt is highly effective because it instructs the model on what format (bullet points), audience (marketing team), and depth (summary) to produce, minimizing the risk of irrelevant details.

**Why It Works**: LLMs excel when they have a clear set of rules to follow. Enterprises benefit from this structured approach, as it ensures consistency across multiple use cases, be it marketing, HR, or customer service. Clear instructions also make it easier to validate outputs against defined expectations, which is crucial for maintaining quality.

### **2.2. Multi-Shot Prompting**

Multi-shot prompting provides several examples before asking the model to complete a task. This helps set expectations by showing the model the desired style and type of output.

**Example**:

- "Here are some example customer support responses:
  1. Customer: 'I can't access my account.'
     Response: 'We're sorry you're having trouble accessing your account. Please try resetting your password using the link provided.'
  2. Customer: 'I received a damaged item.'
     Response: 'We apologize for the damaged item. Please provide us with your order number so we can send a replacement.'

- Customer: 'The app keeps crashing on my phone.'
  Response:"

**Why It Works**: Multi-shot prompting is highly effective in enterprise-grade applications where consistency is critical. Showing multiple examples helps the model learn patterns without needing extensive fine-tuning, saving both time and cost. Enterprises can leverage this technique to ensure that responses remain aligned with brand standards and customer expectations across different departments.

### **2.3. Chain of Thought Prompting**

Chain of Thought (CoT) prompting helps LLMs generate reasoning steps explicitly before arriving at an answer. This method is useful for complex problem-solving tasks or when transparency in decision-making is important.

**Example**:

- "A logistics company wants to minimize fuel costs across multiple delivery routes. Here are the conditions: Each truck has a fuel capacity of 100 gallons, and the price of fuel fluctuates per state. Think through the most cost-effective approach for planning delivery, step by step."

**Why It Works**: CoT prompting allows the model to work through the process iteratively, providing more explainable results. In enterprise applications where complex decision-making is involved, this strategy ensures stakeholders understand why a particular output was generated. This transparency is crucial in high-stakes areas like finance, healthcare, and logistics, where understanding the reasoning behind an output is as important as the output itself.

### **2.4. Iterative Feedback and Adaptive Prompting**

Iterative prompting involves providing multiple prompts or rounds of feedback to refine the output. Adaptive prompts take prior responses and adjust based on context, ensuring the final output meets the required standard.

**Example**:

- First Prompt: "Generate a mission statement for our AI-driven logistics company."
  - Model Response: "We use artificial intelligence to enhance logistics."
  - Follow-up Prompt: "Can you make the statement more specific by mentioning how AI improves efficiency and sustainability?"

**Why It Works**: Enterprises require output that is precise and tailored to brand identity. Iterative feedback provides an effective means to adjust and refine outputs until the desired quality is achieved. By breaking down the task into multiple feedback loops, enterprises can ensure the final output is aligned with their core values and objectives.

### **2.5. Contextual Expansion for Enhanced Relevance**

A lesser-known but powerful strategy is contextual expansion. This involves expanding the prompt to include broader information about the context, thereby allowing the model to generate richer, more relevant responses.

**Example**:

- Original Prompt: "Write a response to a customer asking for a refund."
  - Contextually Expanded Prompt: "Write a response to a customer asking for a refund on a recently purchased product. The customer expressed dissatisfaction with the quality and mentioned they want the process to be quick. Ensure the response is empathetic and explains the refund process clearly, while also offering alternative solutions like an exchange if possible."

**Why It Works**: By including more context, the prompt allows the model to generate a response that feels more tailored to the customer's situation, enhancing both satisfaction and trust. Enterprises benefit from this approach by increasing the quality of customer service interactions.

## **3. What Doesn't Work in Prompting**

While the above methods are effective, prompting can often fall short in certain scenarios:

### **3.1. Overly Vague Prompts**

An insufficiently detailed prompt results in vague outputs. For example, simply asking "What are some strategies to grow a business?" can lead to generic responses that lack actionable insight. Vague prompts are particularly problematic in enterprise settings where specificity is crucial to drive action.

### **3.2. Excessive Length**

Overloading a prompt with details often causes the LLM to become confused, producing incomplete or inaccurate responses. For example, "Explain blockchain, focusing on cryptographic methods, network nodes, ledger distribution, proof of work, mining processes, hash functions, transaction validation, etc." attempts to include too many subjects for a concise response. Enterprise-grade prompts should focus on a specific area to avoid overwhelming the model and degrading the output quality.

### **3.3. Ambiguity in Expected Output**

Ambiguity arises when prompts don't clearly specify the desired output format, tone, or length. For example, asking "Describe our new product" without specifying whether it should be a single-line summary, a paragraph, or a technical overview can lead to an unpredictable response. Enterprises must clearly define expectations to ensure consistent and high-quality outputs.

## **4. The Holy Grail: Automated Prompt Engineering**

In an enterprise setting, scaling prompt engineering for consistency and high performance remains a key challenge. Automated Prompt Engineering (APE) offers a potential solution for bridging the gap between individual craftsmanship and enterprise-wide implementation.

**4.1. AI-Augmented Prompt Design**

Automated Prompt Engineering tools can evaluate the outputs generated by various prompts, selecting the one with the highest quality metrics. These tools can be trained to understand what constitutes an ideal response for specific enterprise contexts.

**Example**:

- An APE system takes multiple variations of a prompt for generating email responses to customer complaints. After evaluating the sentiment, tone, and accuracy of each response, it selects the prompt that yields the most favorable output for business goals.

**Why It Works**: AI-Augmented Prompt Design reduces the need for manual intervention and standardizes the quality of responses across the organization. This approach helps enterprises maintain consistency while saving valuable time that would otherwise be spent on trial-and-error prompting.

**4.2. Reinforcement Learning for Prompts (RLP)**

Using Reinforcement Learning for Prompts involves training models to automatically iterate on prompts to improve the quality of the final output. The model is rewarded for generating responses that align with predefined criteria, such as clarity, completeness, or relevance.

**Example**:

- An enterprise uses RLP to refine prompts used in internal compliance checks. The model iteratively generates summaries of compliance reports, refining the prompt until it consistently generates clear, concise, and accurate summaries aligned with internal guidelines.

**Why It Works**: RLP can significantly improve the quality of complex outputs over time. Enterprises that require a high level of precision, such as in legal or compliance-related applications, benefit from RLP by ensuring outputs meet stringent standards.

**4.3. Dynamic Contextual Adaptation**

Another aspect of automated prompt engineering involves adapting prompts in real time based on user context. For example, if a user interacting with a customer support bot seems frustrated (as detected by sentiment analysis), an adaptive prompt may be used to generate a more empathetic response.

**Example**:

- User: "I'm really annoyed that my order hasn't arrived yet."
  - Prompt (adapted): "I'm truly sorry for the inconvenience you're experiencing. Please let me help you resolve this as quickly as possible. Could you provide your order number so I can check its status right away?"

**Why It Works**: In dynamic enterprise environments, where every user experience matters, adapting prompts to the immediate context can significantly improve customer satisfaction. Real-time adaptation allows the model to be more responsive and attuned to customer needs, thereby fostering loyalty and trust.

**4.4. Collaborative Prompt Refinement**

Automated prompt engineering can also involve collaboration between AI models and human experts. Collaborative Prompt Refinement (CPR) allows human operators to provide iterative guidance, which the model then uses to enhance its understanding and improve future outputs.

**Example**:

- A financial analyst uses a prompt to generate an investment report. The model provides an initial draft, and the analyst refines it with comments. The model learns from these comments and applies similar refinements to future reports, reducing the analyst’s workload over time.

**Why It Works**: CPR bridges the gap between human expertise and machine efficiency, ensuring that outputs are not only technically accurate but also aligned with expert expectations. This iterative learning loop enhances the model’s ability to autonomously generate high-quality content.

## **5. The Future of Enterprise-Grade Prompting**

The future of enterprise-grade prompting is in leveraging automation, context-awareness, and reinforcement learning. By moving from static prompts to dynamic, learning-enabled systems, enterprises can ensure consistent and optimized communication across their AI systems.

Automated systems such as APE and RLP are in their early stages, but they represent the potential to deliver highly scalable prompting solutions that automatically evolve based on user feedback and performance metrics. As more sophisticated models and methods become available, enterprise-grade prompting will likely involve:

- **Fully Adaptive Models**: Models that can detect and adjust to the tone, intent, and needs of users in real time. This means less manual intervention and greater responsiveness to user context.
- **Cross-Domain Learning**: Prompting systems that leverage insights across multiple domains to improve response quality. For example, lessons learned from customer service prompts could be applied to internal HR prompts to enhance employee communications.
- **Human-in-the-Loop Systems**: Combining automated prompt generation with human validation to ensure compliance, accuracy, and brand consistency. Human-in-the-loop systems allow enterprises to leverage the efficiency of automation while maintaining a high level of quality control.

The rise of self-improving prompting systems marks a significant shift in how enterprises leverage AI for communication and decision-making. As more sophisticated models emerge, we anticipate a greater emphasis on adaptability, real-time learning, and seamless integration with existing business processes.

**Conclusion**

Enterprise-grade prompting transcends the art of crafting effective prompts into a well-defined process, merging structure with creativity and guided refinement. By understanding the foundational principles, leveraging strategies like instruction-based and chain-of-thought prompting, and adopting automation, enterprises can consistently extract high-quality results from LLMs.

The evolution towards automated prompt engineering is transforming enterprise AI use from reactive problem-solving to proactive, intelligent decision-making. As the enterprise AI ecosystem matures, prompting will continue to be the linchpin that aligns the capabilities of LLMs with real-world business needs, ensuring optimal outcomes at scale.

Whether it's customer support, compliance, marketing, or operational analytics, the strategies outlined in this essay—paired with advancements in automated prompt engineering—hold the key to effective, scalable, and enterprise-grade utilization of AI models. Enterprises that invest in these methodologies today are likely to maintain a competitive edge in an increasingly automated business landscape.

**Next Steps**

This essay is a stepping stone towards understanding enterprise-grade prompting. We encourage AI teams to start experimenting with these prompting techniques in sandbox environments, identify what works best for their needs, and gradually iterate. Automation is the future, and investing in automated prompt engineering today will yield highly optimized, scalable solutions that consistently deliver value.

Ready to take the next step? Let’s explore how to design adaptive prompting frameworks tailored to your enterprise’s unique requirements.

--------------------------------------------------

# File: swarms/prompts/main.md

# Managing Prompts in Production

The `Prompt` class provides a comprehensive solution for managing prompts, including advanced features like version control, autosaving, and logging. This guide will walk you through how to effectively use this class in a production environment, focusing on its core features, use cases, and best practices.

## Table of Contents

1. **Getting Started**
    - Installation and Setup
    - Creating a New Prompt
2. **Managing Prompt Content**
    - Editing Prompts
    - Retrieving Prompt Content
3. **Version Control**
    - Tracking Edits and History
    - Rolling Back to Previous Versions
4. **Autosaving Prompts**
    - Enabling and Configuring Autosave
    - Manually Triggering Autosave
5. **Logging and Telemetry**
6. **Handling Errors**
7. **Extending the Prompt Class**
    - Customizing the Save Mechanism
    - Integrating with Databases

---

## 1. Getting Started

### Installation and Setup

Before diving into how to use the `Prompt` class, ensure that you have the required dependencies installed:

```bash
pip3 install -U swarms
```


### Creating a New Prompt

To create a new instance of a `Prompt`, simply initialize it with the required attributes such as `content`:

```python
from swarms import Prompt

prompt = Prompt(
    content="This is my first prompt!",
    name="My First Prompt",
    description="A simple example prompt."
)

print(prompt)
```

This creates a new prompt with the current timestamp and a unique identifier.

---

## 2. Managing Prompt Content

### Editing Prompts

Once you have initialized a prompt, you can edit its content using the `edit_prompt` method. Each time the content is edited, a new version is stored in the `edit_history`, and the `last_modified_at` timestamp is updated.

```python
new_content = "This is an updated version of my prompt."
prompt.edit_prompt(new_content)
```

**Note**: If the new content is identical to the current content, an error will be raised to prevent unnecessary edits:

```python
try:
    prompt.edit_prompt("This is my first prompt!")  # Same as initial content
except ValueError as e:
    print(e)  # Output: New content must be different from the current content.
```

### Retrieving Prompt Content

You can retrieve the current prompt content using the `get_prompt` method:

```python
current_content = prompt.get_prompt()
print(current_content)  # Output: This is an updated version of my prompt.
```

This method also logs telemetry data, which includes both system information and prompt metadata.

---

## 3. Version Control

### Tracking Edits and History

The `Prompt` class automatically tracks every change made to the prompt. This is stored in the `edit_history` attribute as a list of previous versions.

```python
print(prompt.edit_history)  # Output: ['This is my first prompt!', 'This is an updated version of my prompt.']
```

The number of edits is also tracked using the `edit_count` attribute:

```python
print(prompt.edit_count)  # Output: 2
```

### Rolling Back to Previous Versions

If you want to revert a prompt to a previous version, you can use the `rollback` method, passing the version index you want to revert to:

```python
prompt.rollback(0)
print(prompt.get_prompt())  # Output: This is my first prompt!
```

The rollback operation is thread-safe, and any rollback also triggers a telemetry log.

---

## 4. Autosaving Prompts

### Enabling and Configuring Autosave

To automatically save prompts to storage after every change, you can enable the `autosave` feature when initializing the prompt:

```python
prompt = Prompt(
    content="This is my first prompt!",
    autosave=True,
    autosave_folder="my_prompts"  # Specify the folder within WORKSPACE_DIR
)
```

This will ensure that every edit or rollback action triggers an autosave to the specified folder.

### Manually Triggering Autosave

You can also manually trigger an autosave by calling the `_autosave` method (which is a private method typically used internally):

```python
prompt._autosave()  # Manually triggers autosaving
```

Autosaves are stored as JSON files in the folder specified by `autosave_folder` under the workspace directory (`WORKSPACE_DIR` environment variable).

---

## 5. Logging and Telemetry

The `Prompt` class integrates with the `loguru` logging library to provide detailed logs for every major action, such as editing, rolling back, and saving. The `log_telemetry` method captures and logs system data, including prompt metadata, for each operation.

Here's an example of a log when editing a prompt:

```bash
2024-10-10 10:12:34.567 | INFO  | Editing prompt a7b8f9. Current content: 'This is my first prompt!'
2024-10-10 10:12:34.789 | DEBUG | Prompt a7b8f9 updated. Edit count: 1. New content: 'This is an updated version of my prompt.'
```

You can extend logging by integrating the `log_telemetry` method with your own telemetry systems or databases:

```python
prompt.log_telemetry()
```

---

## 6. Handling Errors

Error handling in the `Prompt` class is robust and prevents common mistakes, such as editing with identical content or rolling back to an invalid version. Here's a common scenario:

### Editing with Identical Content

```python
try:
    prompt.edit_prompt("This is an updated version of my prompt.")
except ValueError as e:
    print(e)  # Output: New content must be different from the current content.
```

### Invalid Rollback Version

```python
try:
    prompt.rollback(10)  # Invalid version index
except IndexError as e:
    print(e)  # Output: Invalid version number for rollback.
```

Always ensure that version numbers passed to `rollback` are within the valid range of existing versions.

---

## 7. Extending the Prompt Class

### Customizing the Save Mechanism

The `Prompt` class currently includes a placeholder for saving and loading prompts from persistent storage. You can override the `save_to_storage` and `load_from_storage` methods to integrate with databases, cloud storage, or other persistent layers.

Here's how you can implement the save functionality:

```python
def save_to_storage(self):
    # Example of saving to a database or cloud storage
    data = self.model_dump()
    save_to_database(data)  # Custom function to save data
```

Similarly, you can implement a `load_from_storage` function to load the prompt from a storage location using its unique identifier (`id`).


## Full Example code with all methods

```python
from swarms.prompts.prompt import Prompt

# Example 1: Initializing a Financial Report Prompt
financial_prompt = Prompt(
    content="Q1 2024 Earnings Report: Initial Draft", autosave=True
)

# Output the initial state of the prompt
print("\n--- Example 1: Initializing Prompt ---")
print(f"Prompt ID: {financial_prompt.id}")
print(f"Content: {financial_prompt.content}")
print(f"Created At: {financial_prompt.created_at}")
print(f"Edit Count: {financial_prompt.edit_count}")
print(f"History: {financial_prompt.edit_history}")


# Example 2: Editing a Financial Report Prompt
financial_prompt.edit_prompt(
    "Q1 2024 Earnings Report: Updated Revenue Figures"
)

# Output the updated state of the prompt
print("\n--- Example 2: Editing Prompt ---")
print(f"Content after edit: {financial_prompt.content}")
print(f"Edit Count: {financial_prompt.edit_count}")
print(f"History: {financial_prompt.edit_history}")


# Example 3: Rolling Back to a Previous Version
financial_prompt.edit_prompt("Q1 2024 Earnings Report: Final Version")
financial_prompt.rollback(
    1
)  # Roll back to the second version (index 1)

# Output the state after rollback
print("\n--- Example 3: Rolling Back ---")
print(f"Content after rollback: {financial_prompt.content}")
print(f"Edit Count: {financial_prompt.edit_count}")
print(f"History: {financial_prompt.edit_history}")


# Example 4: Handling Invalid Rollback
print("\n--- Example 4: Invalid Rollback ---")
try:
    financial_prompt.rollback(
        5
    )  # Attempt an invalid rollback (out of bounds)
except IndexError as e:
    print(f"Error: {e}")


# Example 5: Preventing Duplicate Edits
print("\n--- Example 5: Preventing Duplicate Edits ---")
try:
    financial_prompt.edit_prompt(
        "Q1 2024 Earnings Report: Updated Revenue Figures"
    )  # Duplicate content
except ValueError as e:
    print(f"Error: {e}")


# Example 6: Retrieving the Prompt Content as a String
print("\n--- Example 6: Retrieving Prompt as String ---")
current_content = financial_prompt.get_prompt()
print(f"Current Prompt Content: {current_content}")


# Example 7: Simulating Financial Report Changes Over Time
print("\n--- Example 7: Simulating Changes Over Time ---")
# Initialize a new prompt representing an initial financial report draft
financial_prompt = Prompt(
    content="Q2 2024 Earnings Report: Initial Draft"
)

# Simulate several updates over time
financial_prompt.edit_prompt(
    "Q2 2024 Earnings Report: Updated Forecasts"
)
financial_prompt.edit_prompt(
    "Q2 2024 Earnings Report: Revenue Adjustments"
)
financial_prompt.edit_prompt("Q2 2024 Earnings Report: Final Review")

# Display full history
print(f"Final Content: {financial_prompt.content}")
print(f"Edit Count: {financial_prompt.edit_count}")
print(f"Edit History: {financial_prompt.edit_history}")



```

---

## 8. Conclusion

This guide covered how to effectively use the `Prompt` class in production environments, including core features like editing, version control, autosaving, and logging. By following the best practices outlined here, you can ensure that your prompts are managed efficiently, with minimal overhead and maximum flexibility.

The `Prompt` class is designed with scalability and robustness in mind, making it a great choice for managing prompt content in multi-agent architectures or any application where dynamic prompt management is required. Feel free to extend the functionality to suit your needs, whether it's integrating with persistent storage or enhancing logging mechanisms.

By using this architecture, you'll be able to scale your system effortlessly while maintaining detailed version control and history of every interaction with your prompts.

--------------------------------------------------

# File: swarms/structs/BoardOfDirectors.md

# Board of Directors - Multi-Agent Architecture

The Board of Directors is a sophisticated multi-agent architecture that implements collective decision-making through democratic processes, voting mechanisms, and role-based leadership. This architecture provides an alternative to single-director patterns by enabling collaborative intelligence through structured governance.

##  Overview

The Board of Directors architecture follows a democratic workflow pattern:

1. **Task Reception**: User provides a task to the swarm
2. **Board Meeting**: Board of Directors convenes to discuss and create a plan
3. **Voting & Consensus**: Board members vote and reach consensus on task distribution
4. **Order Distribution**: Board distributes orders to specialized worker agents
5. **Execution**: Individual agents execute their assigned tasks
6. **Feedback Loop**: Board evaluates results and issues new orders if needed (up to `max_loops`)
7. **Context Preservation**: All conversation history and context is maintained throughout the process

##  Architecture Components

### Core Components

| Component | Description | Purpose |
|-----------|-------------|---------|
| **BoardOfDirectorsSwarm** | Main orchestration class | Manages the entire board workflow and agent coordination |
| **Board Member Roles** | Role definitions and hierarchy | Defines responsibilities and voting weights for each board member |
| **Decision Making Process** | Voting and consensus mechanisms | Implements democratic decision-making with weighted voting |
| **Workflow Management** | Process orchestration | Manages the complete lifecycle from task reception to final delivery |

### Board Member Interaction Flow

```mermaid
sequenceDiagram
    participant User
    participant Chairman
    participant ViceChair
    participant Secretary
    participant Treasurer
    participant ExecDir
    participant Agents

    User->>Chairman: Submit Task
    Chairman->>ViceChair: Notify Board Meeting
    Chairman->>Secretary: Request Meeting Setup
    Chairman->>Treasurer: Resource Assessment
    Chairman->>ExecDir: Strategic Planning
    
    Note over Chairman,ExecDir: Board Discussion Phase
    
    Chairman->>ViceChair: Lead Discussion
    ViceChair->>Secretary: Document Decisions
    Secretary->>Treasurer: Budget Considerations
    Treasurer->>ExecDir: Resource Allocation
    ExecDir->>Chairman: Strategic Recommendations
    
    Note over Chairman,ExecDir: Voting & Consensus
    
    Chairman->>ViceChair: Call for Vote
    ViceChair->>Secretary: Record Votes
    Secretary->>Treasurer: Financial Approval
    Treasurer->>ExecDir: Resource Approval
    ExecDir->>Chairman: Final Decision
    
    Note over Chairman,Agents: Execution Phase
    
    Chairman->>Agents: Distribute Orders
    Agents->>Chairman: Execute Tasks
    Agents->>ViceChair: Progress Reports
    Agents->>Secretary: Documentation
    Agents->>Treasurer: Resource Usage
    Agents->>ExecDir: Strategic Updates
    
    Note over Chairman,ExecDir: Review & Feedback
    
    Chairman->>User: Deliver Results
```

##  Board Member Roles

The Board of Directors supports various roles with different responsibilities and voting weights:

| Role | Description | Voting Weight | Responsibilities |
|------|-------------|---------------|------------------|
| `CHAIRMAN` | Primary leader responsible for board meetings and final decisions | 1.5 | Leading meetings, facilitating consensus, making final decisions |
| `VICE_CHAIRMAN` | Secondary leader who supports the chairman | 1.2 | Supporting chairman, coordinating operations |
| `SECRETARY` | Responsible for documentation and meeting minutes | 1.0 | Documenting meetings, maintaining records |
| `TREASURER` | Manages financial aspects and resource allocation | 1.0 | Financial oversight, resource management |
| `EXECUTIVE_DIRECTOR` | Executive-level board member with operational authority | 1.5 | Strategic planning, operational oversight |
| `MEMBER` | General board member with specific expertise | 1.0 | Contributing expertise, participating in decisions |

### Role Hierarchy and Authority

```python
# Example: Role hierarchy implementation
class BoardRoleHierarchy:
    def __init__(self):
        self.roles = {
            "CHAIRMAN": {
                "voting_weight": 1.5,
                "authority_level": "FINAL",
                "supervises": ["VICE_CHAIRMAN", "EXECUTIVE_DIRECTOR", "SECRETARY", "TREASURER", "MEMBER"],
                "responsibilities": ["leadership", "final_decision", "consensus_facilitation"],
                "override_capability": True
            },
            "VICE_CHAIRMAN": {
                "voting_weight": 1.2,
                "authority_level": "SENIOR",
                "supervises": ["MEMBER"],
                "responsibilities": ["operational_support", "coordination", "implementation"],
                "backup_for": "CHAIRMAN"
            },
            "EXECUTIVE_DIRECTOR": {
                "voting_weight": 1.5,
                "authority_level": "SENIOR",
                "supervises": ["MEMBER"],
                "responsibilities": ["strategic_planning", "execution_oversight", "performance_management"],
                "strategic_authority": True
            },
            "SECRETARY": {
                "voting_weight": 1.0,
                "authority_level": "STANDARD",
                "supervises": [],
                "responsibilities": ["documentation", "record_keeping", "communication"],
                "administrative_authority": True
            },
            "TREASURER": {
                "voting_weight": 1.0,
                "authority_level": "STANDARD",
                "supervises": [],
                "responsibilities": ["financial_oversight", "resource_management", "budget_control"],
                "financial_authority": True
            },
            "MEMBER": {
                "voting_weight": 1.0,
                "authority_level": "STANDARD",
                "supervises": [],
                "responsibilities": ["expertise_contribution", "analysis", "voting"],
                "specialized_expertise": True
            }
        }
```

##  Quick Start

### Basic Setup

```python
from swarms import Agent
from swarms.structs.board_of_directors_swarm import (
    BoardOfDirectorsSwarm,
    BoardMember,
    BoardMemberRole
)
from swarms.config.board_config import enable_board_feature

# Enable the Board of Directors feature
enable_board_feature()

# Create board members with specific roles
chairman = Agent(
    agent_name="Chairman",
    agent_description="Chairman of the Board responsible for leading meetings",
    model_name="gpt-4o-mini",
    system_prompt="You are the Chairman of the Board..."
)

vice_chairman = Agent(
    agent_name="Vice-Chairman",
    agent_description="Vice Chairman who supports the Chairman",
    model_name="gpt-4o-mini",
    system_prompt="You are the Vice Chairman..."
)

# Create BoardMember objects with roles and expertise
board_members = [
    BoardMember(chairman, BoardMemberRole.CHAIRMAN, 1.5, ["leadership", "strategy"]),
    BoardMember(vice_chairman, BoardMemberRole.VICE_CHAIRMAN, 1.2, ["operations", "coordination"]),
]

# Create worker agents
research_agent = Agent(
    agent_name="Research-Specialist",
    agent_description="Expert in market research and analysis",
    model_name="gpt-4o",
)

financial_agent = Agent(
    agent_name="Financial-Analyst",
    agent_description="Specialist in financial analysis and valuation",
    model_name="gpt-4o",
)

# Initialize the Board of Directors swarm
board_swarm = BoardOfDirectorsSwarm(
    name="Executive_Board_Swarm",
    description="Executive board with specialized roles for strategic decision-making",
    board_members=board_members,
    agents=[research_agent, financial_agent],
    max_loops=2,
    verbose=True,
    decision_threshold=0.6,
    enable_voting=True,
    enable_consensus=True,
)

# Execute a complex task with democratic decision-making
result = board_swarm.run(task="Analyze the market potential for Tesla (TSLA) stock")
print(result)
```

##  Comprehensive Examples

### 1. Strategic Investment Analysis

```python
# Create specialized agents for investment analysis
market_research_agent = Agent(
    agent_name="Market-Research-Specialist",
    agent_description="Expert in market research, competitive analysis, and industry trends",
    model_name="gpt-4o",
    system_prompt="""You are a Market Research Specialist. Your responsibilities include:
1. Conducting comprehensive market research and analysis
2. Identifying market trends, opportunities, and risks
3. Analyzing competitive landscape and positioning
4. Providing market size and growth projections
5. Supporting strategic decision-making with research findings

You should be thorough, analytical, and objective in your research."""
)

financial_analyst_agent = Agent(
    agent_name="Financial-Analyst",
    agent_description="Specialist in financial analysis, valuation, and investment assessment",
    model_name="gpt-4o",
    system_prompt="""You are a Financial Analyst. Your responsibilities include:
1. Conducting financial analysis and valuation
2. Assessing investment opportunities and risks
3. Analyzing financial performance and metrics
4. Providing financial insights and recommendations
5. Supporting financial decision-making

You should be financially astute, analytical, and focused on value creation."""
)

technical_assessor_agent = Agent(
    agent_name="Technical-Assessor",
    agent_description="Expert in technical feasibility and implementation assessment",
    model_name="gpt-4o",
    system_prompt="""You are a Technical Assessor. Your responsibilities include:
1. Evaluating technical feasibility and requirements
2. Assessing implementation challenges and risks
3. Analyzing technology stack and architecture
4. Providing technical insights and recommendations
5. Supporting technical decision-making

You should be technically proficient, practical, and solution-oriented."""
)

# Create comprehensive board members
board_members = [
    BoardMember(
        chairman, 
        BoardMemberRole.CHAIRMAN, 
        1.5, 
        ["leadership", "strategy", "governance", "decision_making"]
    ),
    BoardMember(
        vice_chairman, 
        BoardMemberRole.VICE_CHAIRMAN, 
        1.2, 
        ["operations", "coordination", "communication", "implementation"]
    ),
    BoardMember(
        secretary, 
        BoardMemberRole.SECRETARY, 
        1.0, 
        ["documentation", "compliance", "record_keeping", "communication"]
    ),
    BoardMember(
        treasurer, 
        BoardMemberRole.TREASURER, 
        1.0, 
        ["finance", "budgeting", "risk_management", "resource_allocation"]
    ),
    BoardMember(
        executive_director, 
        BoardMemberRole.EXECUTIVE_DIRECTOR, 
        1.5, 
        ["strategy", "operations", "innovation", "performance_management"]
    )
]

# Initialize the investment analysis board
investment_board = BoardOfDirectorsSwarm(
    name="Investment_Analysis_Board",
    description="Specialized board for investment analysis and decision-making",
    board_members=board_members,
    agents=[market_research_agent, financial_analyst_agent, technical_assessor_agent],
    max_loops=3,
    verbose=True,
    decision_threshold=0.75,  # Higher threshold for investment decisions
    enable_voting=True,
    enable_consensus=True,
    max_workers=3,
    output_type="dict"
)

# Execute investment analysis
investment_task = """
Analyze the strategic investment opportunity for a $50M Series B funding round in a 
fintech startup. Consider market conditions, competitive landscape, financial projections, 
technical feasibility, and strategic fit. Provide comprehensive recommendations including:
1. Investment recommendation (proceed/hold/decline)
2. Valuation analysis and suggested terms
3. Risk assessment and mitigation strategies
4. Strategic value and synergies
5. Implementation timeline and milestones
"""

result = investment_board.run(task=investment_task)
print("Investment Analysis Results:")
print(json.dumps(result, indent=2))
```

### 2. Technology Strategy Development

```python
# Create technology-focused agents
tech_strategy_agent = Agent(
    agent_name="Tech-Strategy-Specialist",
    agent_description="Expert in technology strategy and digital transformation",
    model_name="gpt-4o",
    system_prompt="""You are a Technology Strategy Specialist. Your responsibilities include:
1. Developing technology roadmaps and strategies
2. Assessing digital transformation opportunities
3. Evaluating emerging technologies and trends
4. Planning technology investments and priorities
5. Supporting technology decision-making

You should be strategic, forward-thinking, and technology-savvy."""
)

implementation_planner_agent = Agent(
    agent_name="Implementation-Planner",
    agent_description="Expert in implementation planning and project management",
    model_name="gpt-4o",
    system_prompt="""You are an Implementation Planner. Your responsibilities include:
1. Creating detailed implementation plans
2. Assessing resource requirements and timelines
3. Identifying implementation risks and challenges
4. Planning change management strategies
5. Supporting implementation decision-making

You should be practical, organized, and execution-focused."""
)

# Technology strategy board configuration
tech_board = BoardOfDirectorsSwarm(
    name="Technology_Strategy_Board",
    description="Specialized board for technology strategy and digital transformation",
    board_members=board_members,
    agents=[tech_strategy_agent, implementation_planner_agent, technical_assessor_agent],
    max_loops=4,  # More loops for complex technology planning
    verbose=True,
    decision_threshold=0.7,
    enable_voting=True,
    enable_consensus=True,
    max_workers=3,
    output_type="dict"
)

# Execute technology strategy development
tech_strategy_task = """
Develop a comprehensive technology strategy for a mid-size manufacturing company 
looking to digitize operations and implement Industry 4.0 technologies. Consider:
1. Current technology assessment and gaps
2. Technology roadmap and implementation plan
3. Investment requirements and ROI analysis
4. Risk assessment and mitigation strategies
5. Change management and training requirements
6. Competitive positioning and market advantages
"""

result = tech_board.run(task=tech_strategy_task)
print("Technology Strategy Results:")
print(json.dumps(result, indent=2))
```

### 3. Crisis Management and Response

```python
# Create crisis management agents
crisis_coordinator_agent = Agent(
    agent_name="Crisis-Coordinator",
    agent_description="Expert in crisis management and emergency response",
    model_name="gpt-4o",
    system_prompt="""You are a Crisis Coordinator. Your responsibilities include:
1. Coordinating crisis response efforts
2. Assessing crisis severity and impact
3. Developing immediate response plans
4. Managing stakeholder communications
5. Supporting crisis decision-making

You should be calm, decisive, and action-oriented."""
)

communications_specialist_agent = Agent(
    agent_name="Communications-Specialist",
    agent_description="Expert in crisis communications and stakeholder management",
    model_name="gpt-4o",
    system_prompt="""You are a Communications Specialist. Your responsibilities include:
1. Developing crisis communication strategies
2. Managing stakeholder communications
3. Coordinating public relations efforts
4. Ensuring message consistency and accuracy
5. Supporting communication decision-making

You should be clear, empathetic, and strategic in communications."""
)

# Crisis management board configuration
crisis_board = BoardOfDirectorsSwarm(
    name="Crisis_Management_Board",
    description="Specialized board for crisis management and emergency response",
    board_members=board_members,
    agents=[crisis_coordinator_agent, communications_specialist_agent, financial_analyst_agent],
    max_loops=2,  # Faster response needed
    verbose=True,
    decision_threshold=0.6,  # Lower threshold for urgent decisions
    enable_voting=True,
    enable_consensus=True,
    max_workers=3,
    output_type="dict"
)

# Execute crisis management
crisis_task = """
Our company is facing a major data breach. Develop an immediate response plan.
Include:
1. Immediate containment and mitigation steps
2. Communication strategy for stakeholders
3. Legal and regulatory compliance requirements
4. Financial impact assessment
5. Long-term recovery and prevention measures
6. Timeline and resource allocation
"""

result = crisis_board.run(task=crisis_task)
print("Crisis Management Results:")
print(json.dumps(result, indent=2))
```

##  Configuration and Parameters

### BoardOfDirectorsSwarm Parameters

```python
# Complete parameter reference
board_swarm = BoardOfDirectorsSwarm(
    # Basic Configuration
    name="Board_Name",                    # Name of the board
    description="Board description",      # Description of the board's purpose
    
    # Board Members and Agents
    board_members=board_members,          # List of BoardMember objects
    agents=worker_agents,                 # List of worker Agent objects
    
    # Execution Control
    max_loops=3,                         # Maximum number of refinement loops
    max_workers=4,                       # Maximum parallel workers
    
    # Decision Making
    decision_threshold=0.7,              # Consensus threshold (0.0-1.0)
    enable_voting=True,                  # Enable voting mechanisms
    enable_consensus=True,               # Enable consensus building
    
    # Advanced Features
    auto_assign_roles=True,              # Auto-assign roles based on expertise
    role_mapping={                       # Custom role mapping
        "financial_analysis": ["Treasurer", "Financial_Member"],
        "strategic_planning": ["Chairman", "Executive_Director"]
    },
    
    # Consensus Configuration
    consensus_timeout=300,               # Consensus timeout in seconds
    min_participation_rate=0.8,          # Minimum participation rate
    auto_fallback_to_chairman=True,      # Chairman can make final decisions
    consensus_rounds=3,                  # Maximum consensus building rounds
    
    # Output Configuration
    output_type="dict",                  # Output format: "dict", "str", "list"
    verbose=True,                        # Enable detailed logging
    
    # Quality Control
    quality_threshold=0.8,               # Quality threshold for outputs
    enable_quality_gates=True,           # Enable quality checkpoints
    enable_peer_review=True,             # Enable peer review mechanisms
    
    # Performance Optimization
    parallel_execution=True,             # Enable parallel execution
    enable_agent_pooling=True,           # Enable agent pooling
    timeout_per_agent=300,               # Timeout per agent in seconds
    
    # Monitoring and Logging
    enable_logging=True,                 # Enable detailed logging
    log_level="INFO",                    # Logging level
    enable_metrics=True,                 # Enable performance metrics
    enable_tracing=True                  # Enable request tracing
)
```

### Voting Configuration

```python
# Voting system configuration
voting_config = {
    "method": "weighted_majority",        # Voting method
    "threshold": 0.75,                   # Consensus threshold
    "weights": {                         # Role-based voting weights
        "CHAIRMAN": 1.5,
        "VICE_CHAIRMAN": 1.2,
        "SECRETARY": 1.0,
        "TREASURER": 1.0,
        "EXECUTIVE_DIRECTOR": 1.5
    },
    "tie_breaker": "CHAIRMAN",           # Tie breaker role
    "allow_abstention": True,            # Allow board members to abstain
    "secret_ballot": False,              # Use secret ballot voting
    "transparent_process": True          # Transparent voting process
}
```

### Quality Control Configuration

```python
# Quality control configuration
quality_config = {
    "quality_gates": True,               # Enable quality checkpoints
    "quality_threshold": 0.8,            # Quality threshold
    "enable_peer_review": True,          # Enable peer review
    "review_required": True,             # Require peer review
    "output_validation": True,           # Validate outputs
    "enable_metrics_tracking": True,     # Track quality metrics
    
    # Quality metrics
    "quality_metrics": {
        "completeness": {"weight": 0.2, "threshold": 0.8},
        "accuracy": {"weight": 0.25, "threshold": 0.85},
        "feasibility": {"weight": 0.2, "threshold": 0.8},
        "risk": {"weight": 0.15, "threshold": 0.7},
        "impact": {"weight": 0.2, "threshold": 0.8}
    }
}
```

##  Performance Monitoring and Analytics

### Board Performance Metrics

```python
# Get comprehensive board performance metrics
board_summary = board_swarm.get_board_summary()
print("Board Summary:")
print(f"Board Name: {board_summary['board_name']}")
print(f"Total Board Members: {board_summary['total_members']}")
print(f"Total Worker Agents: {board_summary['total_agents']}")
print(f"Decision Threshold: {board_summary['decision_threshold']}")
print(f"Max Loops: {board_summary['max_loops']}")

# Display board member details
print("\nBoard Members:")
for member in board_summary['members']:
    print(f"- {member['name']} (Role: {member['role']}, Weight: {member['voting_weight']})")
    print(f"  Expertise: {', '.join(member['expertise_areas'])}")

# Display worker agent details
print("\nWorker Agents:")
for agent in board_summary['agents']:
    print(f"- {agent['name']}: {agent['description']}")
```

### Decision Analysis

```python
# Analyze decision-making patterns
if hasattr(result, 'get') and callable(result.get):
    conversation_history = result.get('conversation_history', [])
    
    print(f"\nDecision Analysis:")
    print(f"Total Messages: {len(conversation_history)}")
    
    # Count board member contributions
    board_contributions = {}
    for msg in conversation_history:
        if 'Board' in msg.get('role', ''):
            member_name = msg.get('agent_name', 'Unknown')
            board_contributions[member_name] = board_contributions.get(member_name, 0) + 1
    
    print(f"Board Member Contributions:")
    for member, count in board_contributions.items():
        print(f"- {member}: {count} contributions")
    
    # Count agent executions
    agent_executions = {}
    for msg in conversation_history:
        if any(agent.agent_name in msg.get('role', '') for agent in worker_agents):
            agent_name = msg.get('agent_name', 'Unknown')
            agent_executions[agent_name] = agent_executions.get(agent_name, 0) + 1
    
    print(f"\nAgent Executions:")
    for agent, count in agent_executions.items():
        print(f"- {agent}: {count} executions")
```

### Performance Monitoring System

```python
# Performance monitoring system
class PerformanceMonitor:
    def __init__(self):
        self.metrics = {
            "execution_times": [],
            "quality_scores": [],
            "consensus_rounds": [],
            "error_rates": []
        }
    
    def track_execution_time(self, phase, duration):
        """Track execution time for different phases"""
        self.metrics["execution_times"].append({
            "phase": phase,
            "duration": duration,
            "timestamp": datetime.now().isoformat()
        })
    
    def track_quality_score(self, score):
        """Track quality scores"""
        self.metrics["quality_scores"].append({
            "score": score,
            "timestamp": datetime.now().isoformat()
        })
    
    def generate_performance_report(self):
        """Generate comprehensive performance report"""
        return {
            "average_execution_time": self.calculate_average_execution_time(),
            "quality_trends": self.analyze_quality_trends(),
            "consensus_efficiency": self.analyze_consensus_efficiency(),
            "error_analysis": self.analyze_errors(),
            "recommendations": self.generate_recommendations()
        }

# Usage example
monitor = PerformanceMonitor()
# ... track metrics during execution ...
report = monitor.generate_performance_report()
print("Performance Report:")
print(json.dumps(report, indent=2))
```

##  Advanced Features and Customization

### Custom Board Templates

```python
from swarms.config.board_config import get_default_board_template

# Get pre-configured board templates
financial_board = get_default_board_template("financial_analysis")
strategic_board = get_default_board_template("strategic_planning")
tech_board = get_default_board_template("technology_assessment")
crisis_board = get_default_board_template("crisis_management")

# Custom board template
custom_template = {
    "name": "Custom_Board",
    "description": "Custom board for specific use case",
    "board_members": [
        {"role": "CHAIRMAN", "expertise": ["leadership", "strategy"]},
        {"role": "VICE_CHAIRMAN", "expertise": ["operations", "coordination"]},
        {"role": "SECRETARY", "expertise": ["documentation", "communication"]},
        {"role": "TREASURER", "expertise": ["finance", "budgeting"]},
        {"role": "EXECUTIVE_DIRECTOR", "expertise": ["strategy", "operations"]}
    ],
    "agents": [
        {"name": "Research_Agent", "expertise": ["research", "analysis"]},
        {"name": "Technical_Agent", "expertise": ["technical", "implementation"]}
    ],
    "config": {
        "max_loops": 3,
        "decision_threshold": 0.7,
        "enable_voting": True,
        "enable_consensus": True
    }
}
```

### Dynamic Role Assignment

```python
# Automatically assign roles based on task requirements
board_swarm = BoardOfDirectorsSwarm(
    board_members=board_members,
    agents=agents,
    auto_assign_roles=True,
    role_mapping={
        "financial_analysis": ["Treasurer", "Financial_Member"],
        "strategic_planning": ["Chairman", "Executive_Director"],
        "technical_assessment": ["Technical_Member", "Executive_Director"],
        "research_analysis": ["Research_Member", "Secretary"],
        "crisis_management": ["Chairman", "Vice_Chairman", "Communications_Member"]
    }
)
```

### Consensus Optimization

```python
# Advanced consensus-building mechanisms
board_swarm = BoardOfDirectorsSwarm(
    board_members=board_members,
    agents=agents,
    enable_consensus=True,
    consensus_timeout=300,  # 5 minutes timeout
    min_participation_rate=0.8,  # 80% minimum participation
    auto_fallback_to_chairman=True,  # Chairman can make final decisions
    consensus_rounds=3,  # Maximum consensus building rounds
    consensus_method="weighted_majority",  # Consensus method
    enable_mediation=True,  # Enable mediation for conflicts
    mediation_timeout=120  # Mediation timeout in seconds
)
```

##  Troubleshooting and Debugging

### Common Issues and Solutions

1. **Consensus Failures**
   - **Issue**: Board cannot reach consensus within loop limit
   - **Solution**: Lower voting threshold, increase max_loops, or adjust voting weights
   ```python
   board_swarm = BoardOfDirectorsSwarm(
       decision_threshold=0.6,  # Lower threshold
       max_loops=5,            # More loops
       consensus_timeout=600   # Longer timeout
   )
   ```

2. **Agent Timeout**
   - **Issue**: Individual agents take too long to respond
   - **Solution**: Increase timeout settings or optimize agent prompts
   ```python
   board_swarm = BoardOfDirectorsSwarm(
       timeout_per_agent=600,  # 10 minutes per agent
       enable_agent_pooling=True  # Use agent pooling
   )
   ```

3. **Poor Quality Output**
   - **Issue**: Final output doesn't meet quality standards
   - **Solution**: Enable quality gates, increase max_loops, or improve agent prompts
   ```python
   board_swarm = BoardOfDirectorsSwarm(
       enable_quality_gates=True,
       quality_threshold=0.8,
       enable_peer_review=True,
       max_loops=4
   )
   ```

4. **Resource Exhaustion**
   - **Issue**: System runs out of resources during execution
   - **Solution**: Implement resource limits, use agent pooling, or optimize parallel execution
   ```python
   board_swarm = BoardOfDirectorsSwarm(
       max_workers=2,  # Limit parallel workers
       enable_agent_pooling=True,
       parallel_execution=False  # Disable parallel execution
   )
   ```

### Debugging Techniques

```python
# Debugging configuration
debug_config = BoardConfig(
    max_loops=1,  # Limit loops for debugging
    enable_logging=True,
    log_level="DEBUG",
    enable_tracing=True,
    debug_mode=True
)

# Create debug swarm
debug_swarm = BoardOfDirectorsSwarm(
    agents=agents,
    config=debug_config
)

# Execute with debugging
try:
    result = debug_swarm.run(task)
except Exception as e:
    print(f"Error: {e}")
    print(f"Debug info: {debug_swarm.get_debug_info()}")

# Enable detailed logging
import logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Create swarm with logging enabled
logging_swarm = BoardOfDirectorsSwarm(
    agents=agents,
    config=BoardConfig(
        enable_logging=True,
        log_level="DEBUG",
        enable_metrics=True,
        enable_tracing=True
    )
)
```

##  Use Cases

### Corporate Governance
- **Strategic Planning**: Long-term business strategy development
- **Risk Management**: Comprehensive risk assessment and mitigation
- **Resource Allocation**: Optimal distribution of company resources
- **Performance Oversight**: Monitoring and evaluating organizational performance

### Financial Analysis
- **Portfolio Management**: Investment portfolio optimization and rebalancing
- **Market Analysis**: Comprehensive market research and trend analysis
- **Risk Assessment**: Financial risk evaluation and management
- **Compliance Monitoring**: Regulatory compliance and audit preparation

### Research & Development
- **Technology Assessment**: Evaluation of emerging technologies
- **Product Development**: Strategic product planning and development
- **Innovation Management**: Managing innovation pipelines and initiatives
- **Quality Assurance**: Ensuring high standards across development processes

### Project Management
- **Complex Project Planning**: Multi-faceted project strategy development
- **Resource Optimization**: Efficient allocation of project resources
- **Stakeholder Management**: Coordinating diverse stakeholder interests
- **Risk Mitigation**: Identifying and addressing project risks

### Crisis Management
- **Emergency Response**: Rapid response to critical situations
- **Stakeholder Communication**: Managing communications during crises
- **Recovery Planning**: Developing recovery and prevention strategies
- **Legal Compliance**: Ensuring compliance during crisis situations

##  Success Criteria

A successful Board of Directors implementation should demonstrate:

-  **Democratic Decision Making**: All board members contribute to decisions
-  **Consensus Achievement**: Decisions reached through collaborative processes
-  **Role Effectiveness**: Each board member fulfills their responsibilities
-  **Agent Coordination**: Worker agents execute tasks efficiently
-  **Quality Output**: High-quality results through collective intelligence
-  **Process Transparency**: Clear visibility into decision-making processes
-  **Performance Optimization**: Efficient resource utilization and execution
-  **Continuous Improvement**: Learning from each execution cycle

##  Best Practices

### 1. Role Definition
- Clearly define responsibilities for each board member
- Ensure expertise areas align with organizational needs
- Balance voting weights based on role importance
- Document role interactions and communication protocols

### 2. Task Formulation
- Provide clear, specific task descriptions
- Include relevant context and constraints
- Specify expected outputs and deliverables
- Define quality criteria and success metrics

### 3. Consensus Building
- Allow adequate time for discussion and consensus
- Encourage diverse perspectives and viewpoints
- Use structured decision-making processes
- Implement conflict resolution mechanisms

### 4. Performance Monitoring
- Track decision quality and outcomes
- Monitor board member participation
- Analyze agent utilization and effectiveness
- Implement continuous improvement processes

### 5. Resource Management
- Optimize agent allocation and utilization
- Implement parallel execution where appropriate
- Monitor resource usage and performance
- Scale resources based on task complexity

---

The Board of Directors architecture represents a sophisticated approach to multi-agent collaboration, enabling organizations to leverage collective intelligence through structured governance and democratic decision-making processes. This comprehensive implementation provides the tools and frameworks needed to build effective, scalable, and intelligent decision-making systems. 


--------------------------------------------------

# File: swarms/structs/abstractswarm.md

# `BaseSwarm` Documentation

## Table of Contents

1. [Introduction](#introduction)
2. [Class Definition](#class-definition)
3. [Methods](#methods)
    - [communicate()](#communicate)
    - [run()](#run)
    - [arun()](#arun)
    - [add_worker(worker)](#add_worker)
    - [remove_worker(worker)](#remove_worker)
    - [broadcast(message, sender)](#broadcast)
    - [reset()](#reset)
    - [plan(task)](#plan)
    - [direct_message(message, sender, recipient)](#direct_message)
    - [autoscaler(num_workers, worker)](#autoscaler)
    - [get_worker_by_id(id)](#get_worker_by_id)
    - [get_worker_by_name(name)](#get_worker_by_name)
    - [assign_task(worker, task)](#assign_task)
    - [get_all_tasks(worker, task)](#get_all_tasks)
    - [get_finished_tasks()](#get_finished_tasks)
    - [get_pending_tasks()](#get_pending_tasks)
    - [pause_worker(worker, worker_id)](#pause_worker)
    - [resume_worker(worker, worker_id)](#resume_worker)
    - [stop_worker(worker, worker_id)](#stop_worker)
    - [restart_worker(worker)](#restart_worker)
    - [scale_up(num_worker)](#scale_up)
    - [scale_down(num_worker)](#scale_down)
    - [scale_to(num_worker)](#scale_to)
    - [get_all_workers()](#get_all_workers)
    - [get_swarm_size()](#get_swarm_size)
    - [get_swarm_status()](#get_swarm_status)
    - [save_swarm_state()](#save_swarm_state)

---

## 1. Introduction <a name="introduction"></a>

The Swarms library is designed to provide a framework for swarm simulation architectures. Swarms are collections of autonomous agents or workers that collaborate to perform tasks and achieve common goals. This documentation will guide you through the functionality and usage of the Swarms library, explaining the purpose and implementation details of the provided classes and methods.

## 2. Class Definition <a name="class-definition"></a>

### `BaseSwarm` Class

The `BaseSwarm` class is an abstract base class that serves as the foundation for swarm simulation architectures. It defines the core functionality and methods required to manage and interact with a swarm of workers.

```python
from abc import ABC, abstractmethod
from typing import List

from swarms.swarms.base import AbstractWorker


class BaseSwarm(ABC):
    """
    Abstract class for swarm simulation architectures

    Methods:
    ---------
    ...
    """

    # The class definition and constructor are provided here.

    @abstractmethod
    def __init__(self, workers: List["AbstractWorker"]):
        """Initialize the swarm with workers"""

    # Other abstract methods are listed here.
```

## 3. Methods <a name="methods"></a>

### `communicate()` <a name="communicate"></a>

The `communicate()` method allows the swarm to exchange information through the orchestrator, protocols, and the universal communication layer.

**Usage Example 1:**

```python
swarm = YourSwarmClass(workers)
swarm.communicate()
```

**Usage Example 2:**

```python
# Another example of using the communicate method
swarm = YourSwarmClass(workers)
swarm.communicate()
```

### `run()` <a name="run"></a>

The `run()` method executes the swarm, initiating its activities.

**Usage Example 1:**

```python
swarm = YourSwarmClass(workers)
swarm.run()
```

**Usage Example 2:**

```python
# Another example of running the swarm
swarm = YourSwarmClass(workers)
swarm.run()
```

### `arun()` <a name="arun"></a>

The `arun()` method runs the swarm asynchronously, allowing for parallel execution of tasks.

**Usage Example 1:**

```python
swarm = YourSwarmClass(workers)
swarm.arun()
```

**Usage Example 2:**

```python
# Another example of running the swarm asynchronously
swarm = YourSwarmClass(workers)
swarm.arun()
```

### `add_worker(worker: "AbstractWorker")` <a name="add_worker"></a>

The `add_worker()` method adds a worker to the swarm.

**Parameters:**
- `worker` (AbstractWorker): The worker to be added to the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass([])
worker = YourWorkerClass()
swarm.add_worker(worker)
```

### `remove_worker(worker: "AbstractWorker")` <a name="remove_worker"></a>

The `remove_worker()` method removes a worker from the swarm.

**Parameters:**
- `worker` (AbstractWorker): The worker to be removed from the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_id("worker_id")
swarm.remove_worker(worker)
```

### `broadcast(message: str, sender: Optional["AbstractWorker"] = None)` <a name="broadcast"></a>

The `broadcast()` method sends a message to all workers in the swarm.

**Parameters:**
- `message` (str): The message to be broadcasted.
- `sender` (Optional[AbstractWorker]): The sender of the message (optional).

**Usage Example 1:**

```python
swarm = YourSwarmClass(workers)
message = "Hello, everyone!"
swarm.broadcast(message)
```

**Usage Example 2:**

```python
# Another example of broadcasting a message
swarm = YourSwarmClass(workers)
message = "Important announcement!"
sender = swarm.get_worker_by_name("Supervisor")
swarm.broadcast(message, sender)
```

### `reset()` <a name="reset"></a>

The `reset()` method resets the swarm to its initial state.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm.reset()
```

### `plan(task: str)` <a name="plan"></a>

The `plan()` method instructs workers to individually plan using a workflow or pipeline for a specified task.

**Parameters:**
- `task` (str): The task for which workers should plan.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
task = "Perform data analysis"
swarm.plan(task)
```

### `direct_message(message: str, sender: "AbstractWorker", recipient: "AbstractWorker")` <a name="direct_message"></a>

The `direct_message()` method sends a direct message from one worker to another.

**Parameters:**
- `message` (str): The message to be sent.
- `sender` (AbstractWorker): The sender of the message.
- `recipient` (AbstractWorker): The recipient of the message.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
sender = swarm.get_worker_by_name("Worker1")
recipient = swarm.get_worker_by_name("Worker2")
message = "Hello

, Worker2!"
swarm.direct_message(message, sender, recipient)
```

### `autoscaler(num_workers: int, worker: List["AbstractWorker"])` <a name="autoscaler"></a>

The `autoscaler()` method acts as an autoscaler, dynamically adjusting the number of workers based on system load or other criteria.

**Parameters:**
- `num_workers` (int): The desired number of workers.
- `worker` (List[AbstractWorker]): A list of workers to be managed by the autoscaler.

**Usage Example:**

```python
swarm = YourSwarmClass([])
workers = [YourWorkerClass() for _ in range(10)]
swarm.autoscaler(5, workers)
```

### `get_worker_by_id(id: str) -> "AbstractWorker"` <a name="get_worker_by_id"></a>

The `get_worker_by_id()` method locates a worker in the swarm by their ID.

**Parameters:**
- `id` (str): The ID of the worker to locate.

**Returns:**
- `AbstractWorker`: The worker with the specified ID.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker_id = "worker_123"
worker = swarm.get_worker_by_id(worker_id)
```

### `get_worker_by_name(name: str) -> "AbstractWorker"` <a name="get_worker_by_name"></a>

The `get_worker_by_name()` method locates a worker in the swarm by their name.

**Parameters:**
- `name` (str): The name of the worker to locate.

**Returns:**
- `AbstractWorker`: The worker with the specified name.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker_name = "Alice"
worker = swarm.get_worker_by_name(worker_name)
```

### `assign_task(worker: "AbstractWorker", task: Any) -> Dict` <a name="assign_task"></a>

The `assign_task()` method assigns a task to a specific worker.

**Parameters:**
- `worker` (AbstractWorker): The worker to whom the task should be assigned.
- `task` (Any): The task to be assigned.

**Returns:**
- `Dict`: A dictionary indicating the status of the task assignment.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_name("Worker1")
task = "Perform data analysis"
result = swarm.assign_task(worker, task)
```

### `get_all_tasks(worker: "AbstractWorker", task: Any)` <a name="get_all_tasks"></a>

The `get_all_tasks()` method retrieves all tasks assigned to a specific worker.

**Parameters:**
- `worker` (AbstractWorker): The worker for whom tasks should be retrieved.
- `task` (Any): The task to be retrieved.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_name("Worker1")
tasks = swarm.get_all_tasks(worker, "data analysis")
```

### `get_finished_tasks() -> List[Dict]` <a name="get_finished_tasks"></a>

The `get_finished_tasks()` method retrieves all tasks that have been completed by the workers in the swarm.

**Returns:**
- `List[Dict]`: A list of dictionaries representing finished tasks.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
finished_tasks = swarm.get_finished_tasks()
```

### `get_pending_tasks() -> List[Dict]` <a name="get_pending_tasks"></a>

The `get_pending_tasks()` method retrieves all tasks that are pending or yet to be completed by the workers in the swarm.

**Returns:**
- `List[Dict]`: A list of dictionaries representing pending tasks.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
pending_tasks = swarm.get_pending_tasks()
```

### `pause_worker(worker: "AbstractWorker", worker_id: str)` <a name="pause_worker"></a>

The `pause_worker()` method pauses a specific worker, temporarily suspending their activities.

**Parameters:**
- `worker` (AbstractWorker): The worker to be paused.
- `worker_id` (str): The ID of the worker to be paused.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_name("Worker1")
worker_id = "worker_123"
swarm.pause_worker(worker, worker_id)
```

### `resume_worker(worker: "AbstractWorker", worker_id: str)` <a name="resume_worker"></a>

The `resume_worker()` method resumes a paused worker, allowing them to continue their activities.

**Parameters:**
- `worker` (AbstractWorker): The worker to be resumed.
- `worker_id` (str): The ID of the worker to be resumed.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_name("Worker1")
worker_id = "worker_123"
swarm.resume_worker(worker, worker_id)
```

### `stop_worker(worker: "AbstractWorker", worker_id: str)` <a name="stop_worker"></a>

The `stop_worker()` method stops a specific worker, terminating their activities.

**Parameters:**
- `worker` (AbstractWorker): The worker to be stopped.
- `worker_id` (str): The ID of the worker to be stopped.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_name("Worker1")
worker_id = "worker_123"
swarm.stop_worker(worker, worker_id)
```

### `restart_worker(worker: "AbstractWorker")` <a name="restart_worker"></a>

The `restart_worker()` method restarts a worker, resetting them to their initial state.

**Parameters:**
- `worker` (AbstractWorker): The worker to be restarted.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
worker = swarm.get_worker_by_name("Worker1")
swarm.restart_worker(worker)
```

### `scale_up(num_worker: int)` <a name="scale_up"></a>

The `scale_up()` method increases the number of workers in the swarm.

**Parameters:**
- `num_worker` (int): The number of workers to add to the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm.scale_up(5)
```

### `scale_down(num_worker: int)` <a name="scale_down"></a>

The `scale_down()` method decreases the number of workers in the swarm.

**Parameters:**
- `num_worker` (int): The number of workers to remove from the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm.scale_down(3)
```

### `scale_to(num_worker: int)` <a name="scale_to"></a>

The `scale_to()` method scales the swarm to a specific number of workers.

**Parameters:**
- `num_worker` (int): The desired number of workers.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm.scale_to(10)
```

### `get

_all_workers() -> List["AbstractWorker"]` <a name="get_all_workers"></a>

The `get_all_workers()` method retrieves a list of all workers in the swarm.

**Returns:**
- `List[AbstractWorker]`: A list of all workers in the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
all_workers = swarm.get_all_workers()
```

### `get_swarm_size() -> int` <a name="get_swarm_size"></a>

The `get_swarm_size()` method returns the size of the swarm, which is the total number of workers.

**Returns:**
- `int`: The size of the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm_size = swarm.get_swarm_size()
```

### `get_swarm_status() -> Dict` <a name="get_swarm_status"></a>

The `get_swarm_status()` method provides information about the current status of the swarm.

**Returns:**
- `Dict`: A dictionary containing various status indicators for the swarm.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm_status = swarm.get_swarm_status()
```

### `save_swarm_state()` <a name="save_swarm_state"></a>

The `save_swarm_state()` method allows you to save the current state of the swarm, including worker configurations and task assignments.

**Usage Example:**

```python
swarm = YourSwarmClass(workers)
swarm.save_swarm_state()
```

---

This comprehensive documentation covers the Swarms library, including the `BaseSwarm` class and its methods. You can use this documentation as a guide to understanding and effectively utilizing the Swarms framework for swarm simulation architectures. Feel free to explore further and adapt the library to your specific use cases.

--------------------------------------------------

# File: swarms/structs/agent.md

# `Agent` Structure Reference Documentation

```mermaid
graph TD
    A[Task Initiation] -->|Receives Task| B[Initial LLM Processing]
    B -->|Interprets Task| C[Tool Usage]
    C -->|Calls Tools| D[Function 1]
    C -->|Calls Tools| E[Function 2]
    D -->|Returns Data| C
    E -->|Returns Data| C
    C -->|Provides Data| F[Memory Interaction]
    F -->|Stores and Retrieves Data| G[RAG System]
    G -->|ChromaDB/Pinecone| H[Enhanced Data]
    F -->|Provides Enhanced Data| I[Final LLM Processing]
    I -->|Generates Final Response| J[Output]
    C -->|No Tools Available| K[Skip Tool Usage]
    K -->|Proceeds to Memory Interaction| F
    F -->|No Memory Available| L[Skip Memory Interaction]
    L -->|Proceeds to Final LLM Processing| I
```

The `Agent` class is the core component of the Swarm Agent framework. It serves as an autonomous agent that bridges Language Models (LLMs) with external tools and long-term memory systems. The class is designed to handle a variety of document types—including PDFs, text files, Markdown, and JSON—enabling robust document ingestion and processing. By integrating these capabilities, the `Agent` class empowers LLMs to perform complex tasks, utilize external resources, and manage information efficiently, making it a versatile solution for advanced autonomous workflows.


## Features
The `Agent` class establishes a conversational loop with a language model, allowing for interactive task execution, feedback collection, and dynamic response generation. It includes features such as:

| Feature                                 | Description                                                                                      |
|------------------------------------------|--------------------------------------------------------------------------------------------------|
| **Conversational Loop**                  | Enables back-and-forth interaction with the model.                                               |
| **Feedback Collection**                  | Allows users to provide feedback on generated responses.                                         |
| **Stoppable Conversation**               | Supports custom stopping conditions for the conversation.                                        |
| **Retry Mechanism**                      | Implements a retry system for handling issues in response generation.                            |
| **Tool Integration**                     | Supports the integration of various tools for enhanced capabilities.                             |
| **Long-term Memory Management**          | Incorporates vector databases for efficient information retrieval.                               |
| **Document Ingestion**                   | Processes various document types for information extraction.                                     |
| **Interactive Mode**                     | Allows real-time communication with the agent.                                                   |
| **Sentiment Analysis**                   | Evaluates the sentiment of generated responses.                                                  |
| **Output Filtering and Cleaning**        | Ensures generated responses meet specific criteria.                                              |
| **Asynchronous and Concurrent Execution**| Supports efficient parallelization of tasks.                                                     |
| **Planning and Reasoning**               | Implements techniques like algorithm of thoughts for enhanced decision-making.                   |





## `Agent` Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `id` | `Optional[str]` | Unique identifier for the agent instance. |
| `llm` | `Optional[Any]` | Language model instance used by the agent. |
| `template` | `Optional[str]` | Template used for formatting responses. |
| `max_loops` | `Optional[Union[int, str]]` | Maximum number of loops the agent can run. |
| `stopping_condition` | `Optional[Callable[[str], bool]]` | Callable function determining when to stop looping. |
| `loop_interval` | `Optional[int]` | Interval (in seconds) between loops. |
| `retry_attempts` | `Optional[int]` | Number of retry attempts for failed LLM calls. |
| `retry_interval` | `Optional[int]` | Interval (in seconds) between retry attempts. |
| `return_history` | `Optional[bool]` | Boolean indicating whether to return conversation history. |
| `stopping_token` | `Optional[str]` | Token that stops the agent from looping when present in the response. |
| `dynamic_loops` | `Optional[bool]` | Boolean indicating whether to dynamically determine the number of loops. |
| `interactive` | `Optional[bool]` | Boolean indicating whether to run in interactive mode. |
| `dashboard` | `Optional[bool]` | Boolean indicating whether to display a dashboard. |
| `agent_name` | `Optional[str]` | Name of the agent instance. |
| `agent_description` | `Optional[str]` | Description of the agent instance. |
| `system_prompt` | `Optional[str]` | System prompt used to initialize the conversation. |
| `tools` | `List[Callable]` | List of callable functions representing tools the agent can use. |
| `dynamic_temperature_enabled` | `Optional[bool]` | Boolean indicating whether to dynamically adjust the LLM's temperature. |
| `sop` | `Optional[str]` | Standard operating procedure for the agent. |
| `sop_list` | `Optional[List[str]]` | List of strings representing the standard operating procedure. |
| `saved_state_path` | `Optional[str]` | File path for saving and loading the agent's state. |
| `autosave` | `Optional[bool]` | Boolean indicating whether to automatically save the agent's state. |
| `context_length` | `Optional[int]` | Maximum length of the context window (in tokens) for the LLM. |
| `user_name` | `Optional[str]` | Name used to represent the user in the conversation. |
| `self_healing_enabled` | `Optional[bool]` | Boolean indicating whether to attempt self-healing in case of errors. |
| `code_interpreter` | `Optional[bool]` | Boolean indicating whether to interpret and execute code snippets. |
| `multi_modal` | `Optional[bool]` | Boolean indicating whether to support multimodal inputs. |
| `pdf_path` | `Optional[str]` | File path of a PDF document to be ingested. |
| `list_of_pdf` | `Optional[str]` | List of file paths for PDF documents to be ingested. |
| `tokenizer` | `Optional[Any]` | Instance of a tokenizer used for token counting and management. |
| `long_term_memory` | `Optional[Union[Callable, Any]]` | Instance of a `BaseVectorDatabase` implementation for long-term memory management. |
| `preset_stopping_token` | `Optional[bool]` | Boolean indicating whether to use a preset stopping token. |
| `traceback` | `Optional[Any]` | Object used for traceback handling. |
| `traceback_handlers` | `Optional[Any]` | List of traceback handlers. |
| `streaming_on` | `Optional[bool]` | Boolean indicating whether to stream responses. |
| `docs` | `List[str]` | List of document paths or contents to be ingested. |
| `docs_folder` | `Optional[str]` | Path to a folder containing documents to be ingested. |
| `verbose` | `Optional[bool]` | Boolean indicating whether to print verbose output. |
| `parser` | `Optional[Callable]` | Callable function used for parsing input data. |
| `best_of_n` | `Optional[int]` | Integer indicating the number of best responses to generate. |
| `callback` | `Optional[Callable]` | Callable function to be called after each agent loop. |
| `metadata` | `Optional[Dict[str, Any]]` | Dictionary containing metadata for the agent. |
| `callbacks` | `Optional[List[Callable]]` | List of callable functions to be called during execution. |
| `search_algorithm` | `Optional[Callable]` | Callable function for long-term memory retrieval. |
| `logs_to_filename` | `Optional[str]` | File path for logging agent activities. |
| `evaluator` | `Optional[Callable]` | Callable function for evaluating the agent's responses. |
| `stopping_func` | `Optional[Callable]` | Callable function used as a stopping condition. |
| `custom_loop_condition` | `Optional[Callable]` | Callable function used as a custom loop condition. |
| `sentiment_threshold` | `Optional[float]` | Float value representing the sentiment threshold for evaluating responses. |
| `custom_exit_command` | `Optional[str]` | String representing a custom command for exiting the agent's loop. |
| `sentiment_analyzer` | `Optional[Callable]` | Callable function for sentiment analysis on outputs. |
| `limit_tokens_from_string` | `Optional[Callable]` | Callable function for limiting the number of tokens in a string. |
| `custom_tools_prompt` | `Optional[Callable]` | Callable function for generating a custom prompt for tool usage. |
| `tool_schema` | `ToolUsageType` | Data structure representing the schema for the agent's tools. |
| `output_type` | `OutputType` | Type representing the expected output type of responses. |
| `function_calling_type` | `str` | String representing the type of function calling. |
| `output_cleaner` | `Optional[Callable]` | Callable function for cleaning the agent's output. |
| `function_calling_format_type` | `Optional[str]` | String representing the format type for function calling. |
| `list_base_models` | `Optional[List[BaseModel]]` | List of base models used for generating tool schemas. |
| `metadata_output_type` | `str` | String representing the output type for metadata. |
| `state_save_file_type` | `str` | String representing the file type for saving the agent's state. |
| `chain_of_thoughts` | `bool` | Boolean indicating whether to use the chain of thoughts technique. |
| `algorithm_of_thoughts` | `bool` | Boolean indicating whether to use the algorithm of thoughts technique. |
| `tree_of_thoughts` | `bool` | Boolean indicating whether to use the tree of thoughts technique. |
| `tool_choice` | `str` | String representing the method for tool selection. |
| `execute_tool` | `bool` | Boolean indicating whether to execute tools. |
| `rules` | `str` | String representing the rules for the agent's behavior. |
| `planning` | `Optional[str]` | Boolean indicating whether to perform planning. |
| `planning_prompt` | `Optional[str]` | String representing the prompt for planning. |
| `device` | `str` | String representing the device on which the agent should run. |
| `custom_planning_prompt` | `str` | String representing a custom prompt for planning. |
| `memory_chunk_size` | `int` | Integer representing the maximum size of memory chunks for long-term memory retrieval. |
| `agent_ops_on` | `bool` | Boolean indicating whether agent operations should be enabled. |
| `return_step_meta` | `Optional[bool]` | Boolean indicating whether to return JSON of all steps and additional metadata. |
| `time_created` | `Optional[str]` | Float representing the time the agent was created. |
| `tags` | `Optional[List[str]]` | Optional list of strings for tagging the agent. |
| `use_cases` | `Optional[List[Dict[str, str]]]` | Optional list of dictionaries describing use cases for the agent. |
| `step_pool` | `List[Step]` | List of Step objects representing the agent's execution steps. |
| `print_every_step` | `Optional[bool]` | Boolean indicating whether to print every step of execution. |
| `agent_output` | `ManySteps` | ManySteps object containing the agent's output and metadata. |
| `data_memory` | `Optional[Callable]` | Optional callable for data memory operations. |
| `load_yaml_path` | `str` | String representing the path to a YAML file for loading configurations. |
| `auto_generate_prompt` | `bool` | Boolean indicating whether to automatically generate prompts. |
| `rag_every_loop` | `bool` | Boolean indicating whether to query RAG database for context on every loop |
| `plan_enabled` | `bool` | Boolean indicating whether planning functionality is enabled |
| `artifacts_on` | `bool` | Boolean indicating whether to save artifacts from agent execution |
| `artifacts_output_path` | `str` | File path where artifacts should be saved |
| `artifacts_file_extension` | `str` | File extension to use for saved artifacts |
| `all_cores` | `bool` | Boolean indicating whether to use all CPU cores |
| `device_id` | `int` | ID of the GPU device to use if running on GPU |
| `scheduled_run_date` | `Optional[datetime]` | Optional datetime for scheduling future agent runs |
| `do_not_use_cluster_ops` | `bool` | Boolean indicating whether to avoid cluster operations |
| `all_gpus` | `bool` | Boolean indicating whether to use all available GPUs |
| `model_name` | `str` | String representing the name of the model to use |
| `llm_args` | `dict` | Dictionary containing additional arguments for the LLM |
| `load_state_path` | `str` | String representing the path to load state from |
| `role` | `agent_roles` | String representing the role of the agent (e.g., "worker") |
| `print_on` | `bool` | Boolean indicating whether to print output |
| `tools_list_dictionary` | `Optional[List[Dict[str, Any]]]` | List of dictionaries representing tool schemas |
| `mcp_url` | `Optional[Union[str, MCPConnection]]` | String or MCPConnection representing the MCP server URL |
| `mcp_urls` | `List[str]` | List of strings representing multiple MCP server URLs |
| `react_on` | `bool` | Boolean indicating whether to enable ReAct reasoning |
| `safety_prompt_on` | `bool` | Boolean indicating whether to enable safety prompts |
| `random_models_on` | `bool` | Boolean indicating whether to randomly select models |
| `mcp_config` | `Optional[MCPConnection]` | MCPConnection object containing MCP configuration |
| `top_p` | `Optional[float]` | Float representing the top-p sampling parameter |
| `conversation_schema` | `Optional[ConversationSchema]` | ConversationSchema object for conversation formatting |
| `llm_base_url` | `Optional[str]` | String representing the base URL for the LLM API |
| `llm_api_key` | `Optional[str]` | String representing the API key for the LLM |
| `tool_call_summary` | `bool` | Boolean indicating whether to summarize tool calls |
| `output_raw_json_from_tool_call` | `bool` | Boolean indicating whether to output raw JSON from tool calls |
| `summarize_multiple_images` | `bool` | Boolean indicating whether to summarize multiple image outputs |
| `tool_retry_attempts` | `int` | Integer representing the number of retry attempts for tool execution |
| `reasoning_prompt_on` | `bool` | Boolean indicating whether to enable reasoning prompts |
| `dynamic_context_window` | `bool` | Boolean indicating whether to dynamically adjust context window |
| `show_tool_execution_output` | `bool` | Boolean indicating whether to show tool execution output |
| `created_at` | `float` | Float representing the timestamp when the agent was created |
| `workspace_dir` | `str` | String representing the workspace directory for the agent |
| `timeout` | `Optional[int]` | Integer representing the timeout for operations in seconds |
| `temperature` | `float` | Float representing the temperature for the LLM |
| `max_tokens` | `int` | Integer representing the maximum number of tokens |
| `frequency_penalty` | `float` | Float representing the frequency penalty |
| `presence_penalty` | `float` | Float representing the presence penalty |
| `tool_system_prompt` | `str` | String representing the system prompt for tools |
| `log_directory` | `str` | String representing the directory for logs |

## `Agent` Methods

| Method | Description | Inputs | Usage Example |
|--------|-------------|--------|----------------|
| `run(task, img=None, imgs=None, correct_answer=None, streaming_callback=None, *args, **kwargs)` | Runs the autonomous agent loop to complete the given task with enhanced parameters. | `task` (str): The task to be performed.<br>`img` (str, optional): Path to a single image file.<br>`imgs` (List[str], optional): List of image paths for batch processing.<br>`correct_answer` (str, optional): Expected correct answer for validation with automatic retries.<br>`streaming_callback` (Callable, optional): Callback function for real-time token streaming.<br>`*args`, `**kwargs`: Additional arguments. | `response = agent.run("Generate a report on financial performance.")` |
| `run_batched(tasks, imgs=None, *args, **kwargs)` | Runs multiple tasks concurrently in batch mode. | `tasks` (List[str]): List of tasks to run.<br>`imgs` (List[str], optional): List of images to process.<br>`*args`, `**kwargs`: Additional arguments. | `responses = agent.run_batched(["Task 1", "Task 2"])` |
| `run_multiple_images(task, imgs, *args, **kwargs)` | Runs the agent with multiple images using concurrent processing. | `task` (str): The task to perform on each image.<br>`imgs` (List[str]): List of image paths or URLs.<br>`*args`, `**kwargs`: Additional arguments. | `outputs = agent.run_multiple_images("Describe image", ["img1.jpg", "img2.png"])` |
| `continuous_run_with_answer(task, img=None, correct_answer=None, max_attempts=10)` | Runs the agent until the correct answer is provided. | `task` (str): The task to perform.<br>`img` (str, optional): Image to process.<br>`correct_answer` (str): Expected answer.<br>`max_attempts` (int): Maximum attempts. | `response = agent.continuous_run_with_answer("Math problem", correct_answer="42")` |
| `tool_execution_retry(response, loop_count)` | Executes tools with retry logic for handling failures. | `response` (any): Response containing tool calls.<br>`loop_count` (int): Current loop number. | `agent.tool_execution_retry(response, 1)` |
| `__call__(task, img=None, *args, **kwargs)` | Alternative way to call the `run` method. | Same as `run`. | `response = agent("Generate a report on financial performance.")` |
| `parse_and_execute_tools(response, *args, **kwargs)` | Parses the agent's response and executes any tools mentioned in it. | `response` (str): The agent's response to be parsed.<br>`*args`, `**kwargs`: Additional arguments. | `agent.parse_and_execute_tools(response)` |
| `add_memory(message)` | Adds a message to the agent's memory. | `message` (str): The message to add. | `agent.add_memory("Important information")` |
| `plan(task, *args, **kwargs)` | Plans the execution of a task. | `task` (str): The task to plan.<br>`*args`, `**kwargs`: Additional arguments. | `agent.plan("Analyze market trends")` |
| `run_concurrent(task, *args, **kwargs)` | Runs a task concurrently. | `task` (str): The task to run.<br>`*args`, `**kwargs`: Additional arguments. | `response = await agent.run_concurrent("Concurrent task")` |
| `run_concurrent_tasks(tasks, *args, **kwargs)` | Runs multiple tasks concurrently. | `tasks` (List[str]): List of tasks to run.<br>`*args`, `**kwargs`: Additional arguments. | `responses = agent.run_concurrent_tasks(["Task 1", "Task 2"])` |
| `bulk_run(inputs)` | Generates responses for multiple input sets. | `inputs` (List[Dict[str, Any]]): List of input dictionaries. | `responses = agent.bulk_run([{"task": "Task 1"}, {"task": "Task 2"}])` |
| `run_multiple_images(task, imgs, *args, **kwargs)` | Runs the agent with multiple images using concurrent processing. | `task` (str): The task to perform on each image.<br>`imgs` (List[str]): List of image paths or URLs.<br>`*args`, `**kwargs`: Additional arguments. | `outputs = agent.run_multiple_images("Describe image", ["img1.jpg", "img2.png"])` |
| `continuous_run_with_answer(task, img=None, correct_answer=None, max_attempts=10)` | Runs the agent until the correct answer is provided. | `task` (str): The task to perform.<br>`img` (str, optional): Image to process.<br>`correct_answer` (str): Expected answer.<br>`max_attempts` (int): Maximum attempts. | `response = agent.continuous_run_with_answer("Math problem", correct_answer="42")` |
| `save()` | Saves the agent's history to a file. | None | `agent.save()` |
| `load(file_path)` | Loads the agent's history from a file. | `file_path` (str): Path to the file. | `agent.load("agent_history.json")` |
| `graceful_shutdown()` | Gracefully shuts down the system, saving the state. | None | `agent.graceful_shutdown()` |
| `analyze_feedback()` | Analyzes the feedback for issues. | None | `agent.analyze_feedback()` |
| `undo_last()` | Undoes the last response and returns the previous state. | None | `previous_state, message = agent.undo_last()` |
| `add_response_filter(filter_word)` | Adds a response filter to filter out certain words. | `filter_word` (str): Word to filter. | `agent.add_response_filter("sensitive")` |
| `apply_response_filters(response)` | Applies response filters to the given response. | `response` (str): Response to filter. | `filtered_response = agent.apply_response_filters(response)` |
| `filtered_run(task)` | Runs a task with response filtering applied. | `task` (str): Task to run. | `response = agent.filtered_run("Generate a report")` |
| `save_to_yaml(file_path)` | Saves the agent to a YAML file. | `file_path` (str): Path to save the YAML file. | `agent.save_to_yaml("agent_config.yaml")` |
| `get_llm_parameters()` | Returns the parameters of the language model. | None | `llm_params = agent.get_llm_parameters()` |
| `save_state(file_path, *args, **kwargs)` | Saves the current state of the agent to a JSON file. | `file_path` (str): Path to save the JSON file.<br>`*args`, `**kwargs`: Additional arguments. | `agent.save_state("agent_state.json")` |
| `update_system_prompt(system_prompt)` | Updates the system prompt. | `system_prompt` (str): New system prompt. | `agent.update_system_prompt("New system instructions")` |
| `update_max_loops(max_loops)` | Updates the maximum number of loops. | `max_loops` (int): New maximum number of loops. | `agent.update_max_loops(5)` |
| `update_loop_interval(loop_interval)` | Updates the loop interval. | `loop_interval` (int): New loop interval. | `agent.update_loop_interval(2)` |
| `update_retry_attempts(retry_attempts)` | Updates the number of retry attempts. | `retry_attempts` (int): New number of retry attempts. | `agent.update_retry_attempts(3)` |
| `update_retry_interval(retry_interval)` | Updates the retry interval. | `retry_interval` (int): New retry interval. | `agent.update_retry_interval(5)` |
| `reset()` | Resets the agent's memory. | None | `agent.reset()` |
| `ingest_docs(docs, *args, **kwargs)` | Ingests documents into the agent's memory. | `docs` (List[str]): List of document paths.<br>`*args`, `**kwargs`: Additional arguments. | `agent.ingest_docs(["doc1.pdf", "doc2.txt"])` |
| `ingest_pdf(pdf)` | Ingests a PDF document into the agent's memory. | `pdf` (str): Path to the PDF file. | `agent.ingest_pdf("document.pdf")` |
| `receive_message(name, message)` | Receives a message and adds it to the agent's memory. | `name` (str): Name of the sender.<br>`message` (str): Content of the message. | `agent.receive_message("User", "Hello, agent!")` |
| `send_agent_message(agent_name, message, *args, **kwargs)` | Sends a message from the agent to a user. | `agent_name` (str): Name of the agent.<br>`message` (str): Message to send.<br>`*args`, `**kwargs`: Additional arguments. | `response = agent.send_agent_message("AgentX", "Task completed")` |
| `add_tool(tool)` | Adds a tool to the agent's toolset. | `tool` (Callable): Tool to add. | `agent.add_tool(my_custom_tool)` |
| `add_tools(tools)` | Adds multiple tools to the agent's toolset. | `tools` (List[Callable]): List of tools to add. | `agent.add_tools([tool1, tool2])` |
| `remove_tool(tool)` | Removes a tool from the agent's toolset. | `tool` (Callable): Tool to remove. | `agent.remove_tool(my_custom_tool)` |
| `remove_tools(tools)` | Removes multiple tools from the agent's toolset. | `tools` (List[Callable]): List of tools to remove. | `agent.remove_tools([tool1, tool2])` |
| `get_docs_from_doc_folders()` | Retrieves and processes documents from the specified folder. | None | `agent.get_docs_from_doc_folders()` |
| `memory_query(task, *args, **kwargs)` | Queries the long-term memory for relevant information. | `task` (str): The task or query.<br>`*args`, `**kwargs`: Additional arguments. | `result = agent.memory_query("Find information about X")` |
| `sentiment_analysis_handler(response)` | Performs sentiment analysis on the given response. | `response` (str): The response to analyze. | `agent.sentiment_analysis_handler("Great job!")` |
| `count_and_shorten_context_window(history, *args, **kwargs)` | Counts tokens and shortens the context window if necessary. | `history` (str): The conversation history.<br>`*args`, `**kwargs`: Additional arguments. | `shortened_history = agent.count_and_shorten_context_window(history)` |
| `output_cleaner_and_output_type(response, *args, **kwargs)` | Cleans and formats the output based on specified type. | `response` (str): The response to clean and format.<br>`*args`, `**kwargs`: Additional arguments. | `cleaned_response = agent.output_cleaner_and_output_type(response)` |
| `stream_response(response, delay=0.001)` | Streams the response token by token. | `response` (str): The response to stream.<br>`delay` (float): Delay between tokens. | `agent.stream_response("This is a streamed response")` |
| `dynamic_context_window()` | Dynamically adjusts the context window. | None | `agent.dynamic_context_window()` |
| `check_available_tokens()` | Checks and returns the number of available tokens. | None | `available_tokens = agent.check_available_tokens()` |
| `tokens_checks()` | Performs token checks and returns available tokens. | None | `token_info = agent.tokens_checks()` |
| `truncate_string_by_tokens(input_string, limit)` | Truncates a string to fit within a token limit. | `input_string` (str): String to truncate.<br>`limit` (int): Token limit. | `truncated_string = agent.truncate_string_by_tokens("Long string", 100)` |
| `tokens_operations(input_string)` | Performs various token-related operations on the input string. | `input_string` (str): String to process. | `processed_string = agent.tokens_operations("Input string")` |
| `parse_function_call_and_execute(response)` | Parses a function call from the response and executes it. | `response` (str): Response containing the function call. | `result = agent.parse_function_call_and_execute(response)` |
| `llm_output_parser(response)` | Parses the output from the language model. | `response` (Any): Response from the LLM. | `parsed_response = agent.llm_output_parser(llm_output)` |
| `log_step_metadata(loop, task, response)` | Logs metadata for each step of the agent's execution. | `loop` (int): Current loop number.<br>`task` (str): Current task.<br>`response` (str): Agent's response. | `agent.log_step_metadata(1, "Analyze data", "Analysis complete")` |
| `to_dict()` | Converts the agent's attributes to a dictionary. | None | `agent_dict = agent.to_dict()` |
| `to_json(indent=4, *args, **kwargs)` | Converts the agent's attributes to a JSON string. | `indent` (int): Indentation for JSON.<br>`*args`, `**kwargs`: Additional arguments. | `agent_json = agent.to_json()` |
| `to_yaml(indent=4, *args, **kwargs)` | Converts the agent's attributes to a YAML string. | `indent` (int): Indentation for YAML.<br>`*args`, `**kwargs`: Additional arguments. | `agent_yaml = agent.to_yaml()` |
| `to_toml(*args, **kwargs)` | Converts the agent's attributes to a TOML string. | `*args`, `**kwargs`: Additional arguments. | `agent_toml = agent.to_toml()` |
| `model_dump_json()` | Saves the agent model to a JSON file in the workspace directory. | None | `agent.model_dump_json()` |
| `model_dump_yaml()` | Saves the agent model to a YAML file in the workspace directory. | None | `agent.model_dump_yaml()` |
| `log_agent_data()` | Logs the agent's data to an external API. | None | `agent.log_agent_data()` |
| `handle_tool_schema_ops()` | Handles operations related to tool schemas. | None | `agent.handle_tool_schema_ops()` |
| `call_llm(task, *args, **kwargs)` | Calls the appropriate method on the language model. | `task` (str): Task for the LLM.<br>`*args`, `**kwargs`: Additional arguments. | `response = agent.call_llm("Generate text")` |
| `handle_sop_ops()` | Handles operations related to standard operating procedures. | None | `agent.handle_sop_ops()` |
| `agent_output_type(responses)` | Processes and returns the agent's output based on the specified output type. | `responses` (list): List of responses. | `formatted_output = agent.agent_output_type(responses)` |
| `check_if_no_prompt_then_autogenerate(task)` | Checks if a system prompt is not set and auto-generates one if needed. | `task` (str): The task to use for generating a prompt. | `agent.check_if_no_prompt_then_autogenerate("Analyze data")` |
| `handle_artifacts(response, output_path, extension)` | Handles saving artifacts from agent execution | `response` (str): Agent response<br>`output_path` (str): Output path<br>`extension` (str): File extension | `agent.handle_artifacts(response, "outputs/", ".txt")` |
| `showcase_config()` | Displays the agent's configuration in a formatted table. | None | `agent.showcase_config()` |
| `talk_to(agent, task, img=None, *args, **kwargs)` | Initiates a conversation with another agent. | `agent` (Any): Target agent.<br>`task` (str): Task to discuss.<br>`img` (str, optional): Image to share.<br>`*args`, `**kwargs`: Additional arguments. | `response = agent.talk_to(other_agent, "Let's collaborate")` |
| `talk_to_multiple_agents(agents, task, *args, **kwargs)` | Talks to multiple agents concurrently. | `agents` (List[Any]): List of target agents.<br>`task` (str): Task to discuss.<br>`*args`, `**kwargs`: Additional arguments. | `responses = agent.talk_to_multiple_agents([agent1, agent2], "Group discussion")` |
| `get_agent_role()` | Returns the role of the agent. | None | `role = agent.get_agent_role()` |
| `pretty_print(response, loop_count)` | Prints the response in a formatted panel. | `response` (str): Response to print.<br>`loop_count` (int): Current loop number. | `agent.pretty_print("Analysis complete", 1)` |
| `parse_llm_output(response)` | Parses and standardizes the output from the LLM. | `response` (Any): Response from the LLM. | `parsed_response = agent.parse_llm_output(llm_output)` |
| `sentiment_and_evaluator(response)` | Performs sentiment analysis and evaluation on the response. | `response` (str): Response to analyze. | `agent.sentiment_and_evaluator("Great response!")` |
| `output_cleaner_op(response)` | Applies output cleaning operations to the response. | `response` (str): Response to clean. | `cleaned_response = agent.output_cleaner_op(response)` |
| `mcp_tool_handling(response, current_loop)` | Handles MCP tool execution and responses. | `response` (Any): Response containing tool calls.<br>`current_loop` (int): Current loop number. | `agent.mcp_tool_handling(response, 1)` |
| `temp_llm_instance_for_tool_summary()` | Creates a temporary LLM instance for tool summaries. | None | `temp_llm = agent.temp_llm_instance_for_tool_summary()` |
| `execute_tools(response, loop_count)` | Executes tools based on the LLM response. | `response` (Any): Response containing tool calls.<br>`loop_count` (int): Current loop number. | `agent.execute_tools(response, 1)` |
| `list_output_types()` | Returns available output types. | None | `types = agent.list_output_types()` |
| `tool_execution_retry(response, loop_count)` | Executes tools with retry logic for handling failures. | `response` (Any): Response containing tool calls.<br>`loop_count` (int): Current loop number. | `agent.tool_execution_retry(response, 1)` |



## `Agent.run(*args, **kwargs)`

The `run` method has been significantly enhanced with new parameters for advanced functionality:

### Method Signature
```python
def run(
    self,
    task: Optional[Union[str, Any]] = None,
    img: Optional[str] = None,
    imgs: Optional[List[str]] = None,
    correct_answer: Optional[str] = None,
    streaming_callback: Optional[Callable[[str], None]] = None,
    *args,
    **kwargs,
) -> Any:
```

### Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `task` | `Optional[Union[str, Any]]` | The task to be executed | `None` |
| `img` | `Optional[str]` | Path to a single image file | `None` |
| `imgs` | `Optional[List[str]]` | List of image paths for batch processing | `None` |
| `correct_answer` | `Optional[str]` | Expected correct answer for validation with automatic retries | `None` |
| `streaming_callback` | `Optional[Callable[[str], None]]` | Callback function to receive streaming tokens in real-time | `None` |
| `*args` | `Any` | Additional positional arguments | - |
| `**kwargs` | `Any` | Additional keyword arguments | - |

### Examples


```python
# --- Enhanced Run Method Examples ---

# Basic Usage
# Simple task execution
response = agent.run("Generate a report on financial performance.")

# Single Image Processing
# Process a single image
response = agent.run(
    task="Analyze this image and describe what you see",
    img="path/to/image.jpg"
)

# Multiple Image Processing
# Process multiple images concurrently
response = agent.run(
    task="Analyze these images and identify common patterns",
    imgs=["image1.jpg", "image2.png", "image3.jpeg"]
)

# Answer Validation with Retries
# Run until correct answer is found
response = agent.run(
    task="What is the capital of France?",
    correct_answer="Paris"
)

# Real-time Streaming
def streaming_callback(token: str):
    print(token, end="", flush=True)

response = agent.run(
    task="Tell me a long story about space exploration",
    streaming_callback=streaming_callback
)

# Combined Parameters
# Complex task with multiple features
response = agent.run(
    task="Analyze these financial charts and provide insights",
    imgs=["chart1.png", "chart2.png", "chart3.png"],
    correct_answer="market volatility",
    streaming_callback=my_callback
)
```

### Return Types

The `run` method returns different types based on the input parameters:

| Scenario              | Return Type                                   | Description                                             |
|-----------------------|-----------------------------------------------|---------------------------------------------------------|
| Single task           | `str`                                         | Returns the agent's response                            |
| Multiple images       | `List[Any]`                                   | Returns a list of results, one for each image           |
| Answer validation     | `str`                                         | Returns the correct answer as a string                  |
| Streaming             | `str`                                         | Returns the complete response after streaming completes |



## Advanced Capabilities

### Tool Integration

The `Agent` class allows seamless integration of external tools by accepting a list of Python functions via the `tools` parameter during initialization. Each tool function must include type annotations and a docstring. The `Agent` class automatically converts these functions into an OpenAI-compatible function calling schema, making them accessible for use during task execution.

Learn more about tools [here](https://docs.swarms.world/en/latest/swarms/tools/tools_examples/)

## Requirements for a tool

| Requirement         | Description                                                      |
|---------------------|------------------------------------------------------------------|
| Function            | The tool must be a Python function.                              |
| With types          | The function must have type annotations for its parameters.      |
| With doc strings    | The function must include a docstring describing its behavior.   |
| Must return a string| The function must return a string value.                         |

```python
from swarms import Agent
import subprocess

def terminal(code: str):
    """
    Run code in the terminal.

    Args:
        code (str): The code to run in the terminal.

    Returns:
        str: The output of the code.
    """
    out = subprocess.run(code, shell=True, capture_output=True, text=True).stdout
    return str(out)

# Initialize the agent with a tool
agent = Agent(
    agent_name="Terminal-Agent",
    model_name="claude-sonnet-4-20250514",
    tools=[terminal],
    system_prompt="You are an agent that can execute terminal commands. Use the tools provided to assist the user.",
)

# Run the agent
response = agent.run("List the contents of the current directory")
print(response)
```

### Long-term Memory Management

The Swarm Agent supports integration with vector databases for long-term memory management. Here's an example using ChromaDB:

```python
from swarms import Agent
from swarms_memory import ChromaDB

# Initialize ChromaDB
chromadb = ChromaDB(
    metric="cosine",
    output_dir="finance_agent_rag",
)

# Initialize the agent with long-term memory
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="claude-sonnet-4-20250514",
    long_term_memory=chromadb,
    system_prompt="You are a financial analysis agent with access to long-term memory.",
)

# Run the agent
response = agent.run("What are the components of a startup's stock incentive equity plan?")
print(response)
```

### Interactive Mode

To enable interactive mode, set the `interactive` parameter to `True` when initializing the `Agent`:

```python
agent = Agent(
    agent_name="Interactive-Agent",
    model_name="claude-sonnet-4-20250514",
    interactive=True,
    system_prompt="You are an interactive agent. Engage in a conversation with the user.",
)

# Run the agent in interactive mode
agent.run("Let's start a conversation")
```

### Undo Functionality

```python
# Feature 2: Undo functionality
response = agent.run("Another task")
print(f"Response: {response}")
previous_state, message = agent.undo_last()
print(message)
```

### Response Filtering

```python
# Feature 3: Response filtering
agent.add_response_filter("report")
response = agent.filtered_run("Generate a report on finance")
print(response)
```

### Saving and Loading State

```python
# Save the agent state
agent.save_state('saved_flow.json')

# Load the agent state
agent = Agent(llm=llm_instance, max_loops=5)
agent.load('saved_flow.json')
agent.run("Continue with the task")
```

### Async and Concurrent Execution

```python
# Run a task concurrently
response = await agent.run_concurrent("Concurrent task")
print(response)

# Run multiple tasks concurrently
tasks = [
    {"task": "Task 1"},
    {"task": "Task 2", "img": "path/to/image.jpg"},
    {"task": "Task 3", "custom_param": 42}
]
responses = agent.bulk_run(tasks)
print(responses)

# Run multiple tasks in batch mode (new method)
task_list = ["Analyze data", "Generate report", "Create summary"]
batch_responses = agent.run_batched(task_list)
print(f"Completed {len(batch_responses)} tasks in batch mode")
```


### Batch Processing with `run_batched`

The new `run_batched` method allows you to process multiple tasks efficiently:

#### Method Signature

```python
def run_batched(
    self,
    tasks: List[str],
    imgs: List[str] = None,
    *args,
    **kwargs,
) -> List[Any]:
```

#### Parameters

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `tasks` | `List[str]` | List of tasks to run concurrently | Required |
| `imgs` | `List[str]` | List of images to process with each task | `None` |
| `*args` | `Any` | Additional positional arguments | - |
| `**kwargs` | `Any` | Additional keyword arguments | - |

#### Usage Examples

```python
# Process multiple tasks in batch
tasks = [
    "Analyze the financial data for Q1",
    "Generate a summary report for stakeholders", 
    "Create recommendations for Q2 planning"
]

# Run all tasks concurrently
batch_results = agent.run_batched(tasks)

# Process results
for i, (task, result) in enumerate(zip(tasks, batch_results)):
    print(f"Task {i+1}: {task}")
    print(f"Result: {result}\n")
```

#### Batch Processing with Images

```python
# Process multiple tasks with multiple images
tasks = [
    "Analyze this chart for trends",
    "Identify patterns in this data visualization",
    "Summarize the key insights from this graph"
]

images = ["chart1.png", "chart2.png", "chart3.png"]

# Each task will process all images
batch_results = agent.run_batched(tasks, imgs=images)
```

#### Return Type

- **Returns**: `List[Any]` - List of results from each task execution
- **Order**: Results are returned in the same order as the input tasks

### Various other settings

```python
# # Convert the agent object to a dictionary
print(agent.to_dict())
print(agent.to_toml())
print(agent.model_dump_json())
print(agent.model_dump_yaml())

# Ingest documents into the agent's knowledge base
agent.ingest_docs("your_pdf_path.pdf")

# Receive a message from a user and process it
agent.receive_message(name="agent_name", message="message")

# Send a message from the agent to a user
agent.send_agent_message(agent_name="agent_name", message="message")

# Ingest multiple documents into the agent's knowledge base
agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv")

# Run the agent with a filtered system prompt
agent.filtered_run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?"
)

# Run the agent with multiple system prompts
agent.bulk_run(
    [
        "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?",
        "Another system prompt",
    ]
)

# Add a memory to the agent
agent.add_memory("Add a memory to the agent")

# Check the number of available tokens for the agent
agent.check_available_tokens()

# Perform token checks for the agent
agent.tokens_checks()

# Print the dashboard of the agent
agent.print_dashboard()


# Fetch all the documents from the doc folders
agent.get_docs_from_doc_folders()

# Dump the model to a JSON file
agent.model_dump_json()
print(agent.to_toml())
```


## Examples

### Auto Generate Prompt + CPU Execution


```python

import os
from swarms import Agent

from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize the agent with automated prompt engineering enabled
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=None,  # System prompt is dynamically generated
    model_name="gpt-4.1",
    agent_description=None,
    llm=model,
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=False,
    dynamic_temperature_enabled=True,
    saved_state_path="finance_agent.json",
    user_name="Human:",
    return_step_meta=False,
    output_type="string",
    streaming_on=False,
    auto_generate_prompt=True,  # Enable automated prompt engineering
)

# Run the agent with a task description and specify the device
agent.run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria",
)

# Print the dynamically generated system prompt
print(agent.system_prompt)

```

## Agent Structured Outputs

- Create a structured output schema for the agent [List[Dict]]

- Input in the `tools_list_dictionary` parameter

- Output is a dictionary

- Use the `str_to_dict` function to convert the output to a dictionary

```python

from dotenv import load_dotenv

from swarms import Agent
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)
from swarms.utils.str_to_dict import str_to_dict

load_dotenv()

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "Retrieve the current stock price and related information for a specified company.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "The stock ticker symbol of the company, e.g. AAPL for Apple Inc.",
                    },
                    "include_history": {
                        "type": "boolean",
                        "description": "Indicates whether to include historical price data along with the current price.",
                    },
                    "time": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Optional parameter to specify the time for which the stock data is requested, in ISO 8601 format.",
                    },
                },
                "required": [
                    "ticker",
                    "include_history",
                    "time",
                ],
            },
        },
    }
]


# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    agent_description="Personal finance advisor agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    max_loops=1,
    tools_list_dictionary=tools,
)

out = agent.run(
    "What is the current stock price for Apple Inc. (AAPL)? Include historical price data.",
)

print(out)

print(type(out))

print(str_to_dict(out))

print(type(str_to_dict(out)))


```

## Comprehensive Agent Configuration Examples

### Advanced Agent with All New Features

```python
from swarms import Agent
from swarms_memory import ChromaDB
from datetime import datetime, timedelta

# Initialize advanced agent with comprehensive configuration
agent = Agent(
    # Basic Configuration
    agent_name="Advanced-Analysis-Agent",
    agent_description="Multi-modal analysis agent with advanced capabilities",
    system_prompt="You are an advanced analysis agent capable of processing multiple data types.",
    
    # Enhanced Run Parameters
    max_loops=3,
    dynamic_loops=True,
    interactive=False,
    dashboard=True,
    
    # Device and Resource Management
    device="gpu",
    device_id=0,
    all_cores=True,
    all_gpus=False,
    do_not_use_cluster_ops=True,
    
    # Memory and Context Management
    context_length=100000,
    memory_chunk_size=3000,
    dynamic_context_window=True,
    rag_every_loop=True,
    
    # Advanced Features
    auto_generate_prompt=True,
    plan_enabled=True,
    react_on=True,
    safety_prompt_on=True,
    reasoning_prompt_on=True,
    
    # Tool Management
    tool_retry_attempts=5,
    tool_call_summary=True,
    show_tool_execution_output=True,
    function_calling_format_type="OpenAI",
    
    # Artifacts and Output
    artifacts_on=True,
    artifacts_output_path="./outputs",
    artifacts_file_extension=".md",
    output_type="json",
    
    # LLM Configuration
    model_name="gpt-4o",
    temperature=0.3,
    max_tokens=8000,
    top_p=0.95,
    frequency_penalty=0.1,
    presence_penalty=0.1,
    
    # MCP Integration
    mcp_url="http://localhost:8000",
    mcp_config=None,
    
    # Performance Settings
    timeout=300,
    retry_attempts=3,
    retry_interval=2,
    
    # Scheduling
    scheduled_run_date=datetime.now() + timedelta(hours=1),
    
    # Metadata and Organization
    tags=["analysis", "multi-modal", "advanced"],
    use_cases=[{"name": "Data Analysis", "description": "Process and analyze complex datasets"}],
    
    # Verbosity and Logging
    verbose=True,
    print_on=True,
    print_every_step=True,
    log_directory="./logs"
)

# Run with multiple images and streaming
def streaming_callback(token: str):
    print(token, end="", flush=True)

response = agent.run(
    task="Analyze these financial charts and provide comprehensive insights",
    imgs=["chart1.png", "chart2.png", "chart3.png"],
    streaming_callback=streaming_callback
)

# Run batch processing
tasks = [
    "Analyze Q1 financial performance",
    "Generate Q2 projections",
    "Create executive summary"
]

batch_results = agent.run_batched(tasks)

# Run with answer validation
validated_response = agent.run(
    task="What is the current market trend?",
    correct_answer="bullish",
    max_attempts=5
)
```

### MCP-Enabled Agent Example

```python
from swarms import Agent
from swarms.schemas.mcp_schemas import MCPConnection

# Configure MCP connection
mcp_config = MCPConnection(
    server_path="http://localhost:8000",
    server_name="my_mcp_server",
    capabilities=["tools", "filesystem"]
)

# Initialize agent with MCP integration
mcp_agent = Agent(
    agent_name="MCP-Enabled-Agent",
    system_prompt="You are an agent with access to external tools via MCP.",
    mcp_config=mcp_config,
    mcp_urls=["http://localhost:8000", "http://localhost:8001"],
    tool_call_summary=True,
    output_raw_json_from_tool_call=True
)

# Run with MCP tools
response = mcp_agent.run("Use the available tools to analyze the current system status")
```

### Multi-Image Processing Agent

```python
# Initialize agent optimized for image processing
image_agent = Agent(
    agent_name="Image-Analysis-Agent",
    system_prompt="You are an expert at analyzing images and extracting insights.",
    multi_modal=True,
    summarize_multiple_images=True,
    artifacts_on=True,
    artifacts_output_path="./image_analysis",
    artifacts_file_extension=".txt"
)

# Process multiple images with summarization
images = ["product1.jpg", "product2.jpg", "product3.jpg"]
analysis = image_agent.run(
    task="Analyze these product images and identify design patterns",
    imgs=images
)

# The agent will automatically summarize results if summarize_multiple_images=True
print(f"Analysis complete: {len(analysis)} images processed")
```

## New Features and Parameters

### Enhanced Run Method Parameters

The `run` method now supports several new parameters for advanced functionality:

- **`imgs`**: Process multiple images simultaneously instead of just one
- **`correct_answer`**: Validate responses against expected answers with automatic retries
- **`streaming_callback`**: Real-time token streaming for interactive applications

### MCP (Model Context Protocol) Integration

| Parameter      | Description                                         |
|----------------|-----------------------------------------------------|
| `mcp_url`      | Connect to a single MCP server                      |
| `mcp_urls`     | Connect to multiple MCP servers                     |
| `mcp_config`   | Advanced MCP configuration options                  |

### Advanced Reasoning and Safety

| Parameter            | Description                                                        |
|----------------------|--------------------------------------------------------------------|
| `react_on`           | Enable ReAct reasoning for complex problem-solving                 |
| `safety_prompt_on`   | Add safety constraints to agent responses                          |
| `reasoning_prompt_on`| Enable multi-loop reasoning for complex tasks                      |

### Performance and Resource Management

| Parameter                | Description                                                              |
|--------------------------|--------------------------------------------------------------------------|
| `dynamic_context_window` | Automatically adjust context window based on available tokens             |
| `tool_retry_attempts`    | Configure retry behavior for tool execution                              |
| `summarize_multiple_images` | Automatically summarize results from multiple image processing         |

### Device and Resource Management

| Parameter                | Description                                                              |
|--------------------------|--------------------------------------------------------------------------|
| `device`                 | Specify CPU or GPU execution (`"cpu"` or `"gpu"`)                      |
| `device_id`              | Specify which GPU device to use                                          |
| `all_cores`              | Enable use of all available CPU cores                                    |
| `all_gpus`               | Enable use of all available GPUs                                         |
| `do_not_use_cluster_ops` | Control cluster operation usage                                          |

### Advanced Memory and Context

| Parameter                | Description                                                              |
|--------------------------|--------------------------------------------------------------------------|
| `rag_every_loop`         | Query RAG database on every loop iteration                              |
| `memory_chunk_size`      | Control memory chunk size for long-term memory                          |
| `auto_generate_prompt`   | Automatically generate system prompts based on tasks                    |
| `plan_enabled`           | Enable planning functionality for complex tasks                          |

### Artifacts and Output Management

| Parameter                | Description                                                              |
|--------------------------|--------------------------------------------------------------------------|
| `artifacts_on`           | Enable saving artifacts from agent execution                             |
| `artifacts_output_path`  | Specify where to save artifacts                                          |
| `artifacts_file_extension` | Control artifact file format                                            |
| `output_raw_json_from_tool_call` | Control tool call output format                                    |

### Enhanced Tool Management

| Parameter                | Description                                                              |
|--------------------------|--------------------------------------------------------------------------|
| `tools_list_dictionary`  | Provide tool schemas in dictionary format                               |
| `tool_call_summary`      | Enable automatic summarization of tool calls                            |
| `show_tool_execution_output` | Control visibility of tool execution details                        |
| `function_calling_format_type` | Specify function calling format (OpenAI, etc.)                     |

### Advanced LLM Configuration

| Parameter                | Description                                                              |
|--------------------------|--------------------------------------------------------------------------|
| `llm_args`               | Pass additional arguments to the LLM                                     |
| `llm_base_url`           | Specify custom LLM API endpoint                                          |
| `llm_api_key`            | Provide LLM API key directly                                             |
| `top_p`                  | Control top-p sampling parameter                                         |
| `frequency_penalty`      | Control frequency penalty                                                 |
| `presence_penalty`       | Control presence penalty                                                  |




## Best Practices

| Best Practice / Feature                                 | Description                                                                                      |
|---------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| `system_prompt`                                         | Always provide a clear and concise system prompt to guide the agent's behavior.                  |
| `tools`                                                 | Use tools to extend the agent's capabilities for specific tasks.                                 |
| `retry_attempts` & error handling                       | Implement error handling and utilize the retry_attempts feature for robust execution.            |
| `long_term_memory`                                      | Leverage long_term_memory for tasks that require persistent information.                         |
| `interactive` & `dashboard`                             | Use interactive mode for real-time conversations and dashboard for monitoring.                   |
| `sentiment_analysis`                                    | Implement sentiment_analysis for applications requiring tone management.                         |
| `autosave`, `save`/`load`                               | Utilize autosave and save/load methods for continuity across sessions.                           |
| `dynamic_context_window` & `tokens_checks`              | Optimize token usage with dynamic_context_window and tokens_checks methods.                      |
| `concurrent` & `async` methods                          | Use concurrent and async methods for performance-critical applications.                          |
| `analyze_feedback`                                      | Regularly review and analyze feedback using the analyze_feedback method.                         |
| `artifacts_on`                                          | Use artifacts_on to save important outputs from agent execution.                                 |
| `device` & `device_id`                                  | Configure device and device_id appropriately for optimal performance.                            |
| `rag_every_loop`                                        | Enable rag_every_loop when continuous context from long-term memory is needed.                   |
| `scheduled_run_date`                                    | Use scheduled_run_date for automated task scheduling.                                            |
| `run_batched`                                           | Leverage run_batched for efficient processing of multiple related tasks.                         |
| `mcp_url` or `mcp_urls`                                 | Use mcp_url or mcp_urls to extend agent capabilities with external tools.                        |
| `react_on`                                              | Enable react_on for complex reasoning tasks requiring step-by-step analysis.                     |
| `tool_retry_attempts`                                   | Configure tool_retry_attempts for robust tool execution in production environments.              |

By following these guidelines and leveraging the Swarm Agent's extensive features, you can create powerful, flexible, and efficient autonomous agents for a wide range of applications.

--------------------------------------------------

# File: swarms/structs/agent_docs_v1.md

# `Agent` Documentation

Swarm Agent is a powerful autonomous agent framework designed to connect Language Models (LLMs) with various tools and long-term memory. This class provides the ability to ingest and process various types of documents such as PDFs, text files, Markdown files, JSON files, and more. The Agent structure offers a wide range of features to enhance the capabilities of LLMs and facilitate efficient task execution.

1. **Conversational Loop**: It establishes a conversational loop with a language model. This means it allows you to interact with the model in a back-and-forth manner, taking turns in the conversation.

2. **Feedback Collection**: The class allows users to provide feedback on the responses generated by the model. This feedback can be valuable for training and improving the model's responses over time.

3. **Stoppable Conversation**: You can define custom stopping conditions for the conversation, allowing you to stop the interaction based on specific criteria. For example, you can stop the conversation if a certain keyword is detected in the responses.

4. **Retry Mechanism**: The class includes a retry mechanism that can be helpful if there are issues generating responses from the model. It attempts to generate a response multiple times before raising an error.

## Architecture

```mermaid
graph TD
    A[Task Initiation] -->|Receives Task| B[Initial LLM Processing]
    B -->|Interprets Task| C[Tool Usage]
    C -->|Calls Tools| D[Function 1]
    C -->|Calls Tools| E[Function 2]
    D -->|Returns Data| C
    E -->|Returns Data| C
    C -->|Provides Data| F[Memory Interaction]
    F -->|Stores and Retrieves Data| G[RAG System]
    G -->|ChromaDB/Pinecone| H[Enhanced Data]
    F -->|Provides Enhanced Data| I[Final LLM Processing]
    I -->|Generates Final Response| J[Output]
    C -->|No Tools Available| K[Skip Tool Usage]
    K -->|Proceeds to Memory Interaction| F
    F -->|No Memory Available| L[Skip Memory Interaction]
    L -->|Proceeds to Final LLM Processing| I
```

### `Agent` Attributes

| Attribute | Description |
|------------|-------------|
| `id` | A unique identifier for the agent instance. |
| `llm` | The language model instance used by the agent. |
| `template` | The template used for formatting responses. |
| `max_loops` | The maximum number of loops the agent can run. |
| `stopping_condition` | A callable function that determines when the agent should stop looping. |
| `loop_interval` | The interval (in seconds) between loops. |
| `retry_attempts` | The number of retry attempts for failed LLM calls. |
| `retry_interval` | The interval (in seconds) between retry attempts. |
| `return_history` | A boolean indicating whether the agent should return the conversation history. |
| `stopping_token` | A token that, when present in the response, stops the agent from looping. |
| `dynamic_loops` | A boolean indicating whether the agent should dynamically determine the number of loops. |
| `interactive` | A boolean indicating whether the agent should run in interactive mode. |
| `dashboard` | A boolean indicating whether the agent should display a dashboard. |
| `agent_name` | The name of the agent instance. |
| `agent_description` | A description of the agent instance. |
| `system_prompt` | The system prompt used to initialize the conversation. |
| `tools` | A list of callable functions representing tools the agent can use. |
| `dynamic_temperature_enabled` | A boolean indicating whether the agent should dynamically adjust the temperature of the LLM. |
| `sop` | The standard operating procedure for the agent. |
| `sop_list` | A list of strings representing the standard operating procedure. |
| `saved_state_path` | The file path for saving and loading the agent's state. |
| `autosave` | A boolean indicating whether the agent should automatically save its state. |
| `context_length` | The maximum length of the context window (in tokens) for the LLM. |
| `user_name` | The name used to represent the user in the conversation. |
| `self_healing_enabled` | A boolean indicating whether the agent should attempt to self-heal in case of errors. |
| `code_interpreter` | A boolean indicating whether the agent should interpret and execute code snippets. |
| `multi_modal` | A boolean indicating whether the agent should support multimodal inputs (e.g., text and images). |
| `pdf_path` | The file path of a PDF document to be ingested. |
| `list_of_pdf` | A list of file paths for PDF documents to be ingested. |
| `tokenizer` | An instance of a tokenizer used for token counting and management. |
| `long_term_memory` | An instance of a `BaseVectorDatabase` implementation for long-term memory management. |
| `preset_stopping_token` | A boolean indicating whether the agent should use a preset stopping token. |
| `traceback` | An object used for traceback handling. |
| `traceback_handlers` | A list of traceback handlers. |
| `streaming_on` | A boolean indicating whether the agent should stream its responses. |
| `docs` | A list of document paths or contents to be ingested. |
| `docs_folder` | The path to a folder containing documents to be ingested. |
| `verbose` | A boolean indicating whether the agent should print verbose output. |
| `parser` | A callable function used for parsing input data. |
| `best_of_n` | An integer indicating the number of best responses to generate (for sampling). |
| `callback` | A callable function to be called after each agent loop. |
| `metadata` | A dictionary containing metadata for the agent. |
| `callbacks` | A list of callable functions to be called during the agent's execution. |
| `logger_handler` | A handler for logging messages. |
| `search_algorithm` | A callable function representing the search algorithm for long-term memory retrieval. |
| `logs_to_filename` | The file path for logging agent activities. |
| `evaluator` | A callable function used for evaluating the agent's responses. |
| `output_json` | A boolean indicating whether the agent's output should be in JSON format. |
| `stopping_func` | A callable function used as a stopping condition for the agent. |
| `custom_loop_condition` | A callable function used as a custom loop condition for the agent. |
| `sentiment_threshold` | A float value representing the sentiment threshold for evaluating responses. |
| `custom_exit_command` | A string representing a custom command for exiting the agent's loop. |
| `sentiment_analyzer` | A callable function used for sentiment analysis on the agent's outputs. |
| `limit_tokens_from_string` | A callable function used for limiting the number of tokens in a string. |
| `custom_tools_prompt` | A callable function used for generating a custom prompt for tool usage. |
| `tool_schema` | A data structure representing the schema for the agent's tools. |
| `output_type` | A type representing the expected output type of the agent's responses. |
| `function_calling_type` | A string representing the type of function calling (e.g., "json"). |
| `output_cleaner` | A callable function used for cleaning the agent's output. |
| `function_calling_format_type` | A string representing the format type for function calling (e.g., "OpenAI"). |
| `list_base_models` | A list of base models used for generating tool schemas. |
| `metadata_output_type` | A string representing the output type for metadata. |
| `state_save_file_type` | A string representing the file type for saving the agent's state (e.g., "json", "yaml"). |
| `chain_of_thoughts` | A boolean indicating whether the agent should use the chain of thoughts technique. |
| `algorithm_of_thoughts` | A boolean indicating whether the agent should use the algorithm of thoughts technique. |
| `tree_of_thoughts` | A boolean indicating whether the agent should use the tree of thoughts technique. |
| `tool_choice` | A string representing the method for tool selection (e.g., "auto"). |
| `execute_tool` | A boolean indicating whether the agent should execute tools. |
| `rules` | A string representing the rules for the agent's behavior. |
| `planning` | A boolean indicating whether the agent should perform planning. |
| `planning_prompt` | A string representing the prompt for planning. |
| `device` | A string representing the device on which the agent should run. |
| `custom_planning_prompt` | A string representing a custom prompt for planning. |
| `memory_chunk_size` | An integer representing the maximum size of memory chunks for long-term memory retrieval. |
| `agent_ops_on` | A boolean indicating whether agent operations should be enabled. |
| `return_step_meta` | A boolean indicating whether or not to return JSON of all the steps and additional metadata |
| `output_type` | A Literal type indicating whether to output "string", "str", "list", "json", "dict", "yaml" |



### `Agent` Methods

| Method | Description | Inputs | Usage Example |
|--------|-------------|--------|----------------|
| `run(task, img=None, *args, **kwargs)` | Runs the autonomous agent loop to complete the given task. | `task` (str): The task to be performed.<br>`img` (str, optional): Path to an image file, if the task involves image processing.<br>`*args`, `**kwargs`: Additional arguments to pass to the language model. | `response = agent.run("Generate a report on financial performance.")` |
| `__call__(task, img=None, *args, **kwargs)` | An alternative way to call the `run` method. | Same as `run`. | `response = agent("Generate a report on financial performance.")` |
| `parse_and_execute_tools(response, *args, **kwargs)` | Parses the agent's response and executes any tools mentioned in it. | `response` (str): The agent's response to be parsed.<br>`*args`, `**kwargs`: Additional arguments to pass to the tool execution. | `agent.parse_and_execute_tools(response)` |
| `long_term_memory_prompt(query, *args, **kwargs)` | Generates a prompt for querying the agent's long-term memory. | `query` (str): The query to search for in long-term memory.<br>`*args`, `**kwargs`: Additional arguments to pass to the long-term memory retrieval. | `memory_retrieval = agent.long_term_memory_prompt("financial performance")` |
| `add_memory(message)` | Adds a message to the agent's memory. | `message` (str): The message




## Features

- **Language Model Integration**: The Swarm Agent allows seamless integration with different language models, enabling users to leverage the power of state-of-the-art models.
- **Tool Integration**: The framework supports the integration of various tools, enabling the agent to perform a wide range of tasks, from code execution to data analysis and beyond.
- **Long-term Memory Management**: The Swarm Agent incorporates long-term memory management capabilities, allowing it to store and retrieve relevant information for effective decision-making and task execution.
- **Document Ingestion**: The agent can ingest and process various types of documents, including PDFs, text files, Markdown files, JSON files, and more, enabling it to extract relevant information for task completion.
- **Interactive Mode**: Users can interact with the agent in an interactive mode, enabling real-time communication and task execution.
- **Dashboard**: The framework provides a visual dashboard for monitoring the agent's performance and activities.
- **Dynamic Temperature Control**: The Swarm Agent supports dynamic temperature control, allowing for adjustments to the model's output diversity during task execution.
- **Autosave and State Management**: The agent can save its state automatically, enabling seamless resumption of tasks after interruptions or system restarts.
- **Self-Healing and Error Handling**: The framework incorporates self-healing and error-handling mechanisms to ensure robust and reliable operation.
- **Code Interpretation**: The agent can interpret and execute code snippets, expanding its capabilities for tasks involving programming or scripting.
- **Multimodal Support**: The framework supports multimodal inputs, enabling the agent to process and reason about various data types, such as text, images, and audio.
- **Tokenization and Token Management**: The Swarm Agent provides tokenization capabilities, enabling efficient management of token usage and context window truncation.
- **Sentiment Analysis**: The agent can perform sentiment analysis on its generated outputs, allowing for evaluation and adjustment of responses based on sentiment thresholds.
- **Output Filtering and Cleaning**: The framework supports output filtering and cleaning, ensuring that generated responses adhere to specific criteria or guidelines.
- **Asynchronous and Concurrent Execution**: The Swarm Agent supports asynchronous and concurrent task execution, enabling efficient parallelization and scaling of operations.
- **Planning and Reasoning**: The agent can engage in planning and reasoning processes, leveraging techniques such as algorithm of thoughts and chain of thoughts to enhance decision-making and task execution.
- **Agent Operations and Monitoring**: The framework provides integration with agent operations and monitoring tools, enabling real-time monitoring and management of the agent's activities.

## Getting Started

First run the following:

```bash
pip3 install -U swarms
```

And, then now you can get started with the following:

```python
import os
from swarms import Agent
from swarm_models import OpenAIChat
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)

# Get the OpenAI API key from the environment variable
api_key = os.getenv("OPENAI_API_KEY")

# Create an instance of the OpenAIChat class
model = OpenAIChat(
    api_key=api_key, model_name="gpt-4o-mini", temperature=0.1
)

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent_sas_chicken_eej",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    llm=model,
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=True,
    dynamic_temperature_enabled=True,
    saved_state_path="finance_agent.json",
    user_name="swarms_corp",
    retry_attempts=1,
    context_length=200000,
    return_step_meta=False,
    output_type="str",
)


agent.run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria"
)
print(out)

```

This example initializes an instance of the `Agent` class with an OpenAI language model and a maximum of 3 loops. The `run()` method is then called with a task to generate a report on financial performance, and the agent's response is printed.

## Advanced Usage

The Swarm Agent provides numerous advanced features and customization options. Here are a few examples of how to leverage these features:

### Tool Integration

To integrate tools with the Swarm Agent, you can pass a list of callable functions with types and doc strings to the `tools` parameter when initializing the `Agent` instance. The agent will automatically convert these functions into an OpenAI function calling schema and make them available for use during task execution.

## Requirements for a tool
- Function
  - With types
  - with doc strings

```python
from swarms import Agent
from swarm_models import OpenAIChat
from swarms_memory import ChromaDB
import subprocess
import os

# Making an instance of the ChromaDB class
memory = ChromaDB(
    metric="cosine",
    n_results=3,
    output_dir="results",
    docs_folder="docs",
)

# Model
model = OpenAIChat(
    api_key=os.getenv("OPENAI_API_KEY"),
    model_name="gpt-4o-mini",
    temperature=0.1,
)


# Tools in swarms are simple python functions and docstrings
def terminal(
    code: str,
):
    """
    Run code in the terminal.

    Args:
        code (str): The code to run in the terminal.

    Returns:
        str: The output of the code.
    """
    out = subprocess.run(
        code, shell=True, capture_output=True, text=True
    ).stdout
    return str(out)


def browser(query: str):
    """
    Search the query in the browser with the `browser` tool.

    Args:
        query (str): The query to search in the browser.

    Returns:
        str: The search results.
    """
    import webbrowser

    url = f"https://www.google.com/search?q={query}"
    webbrowser.open(url)
    return f"Searching for {query} in the browser."


def create_file(file_path: str, content: str):
    """
    Create a file using the file editor tool.

    Args:
        file_path (str): The path to the file.
        content (str): The content to write to the file.

    Returns:
        str: The result of the file creation operation.
    """
    with open(file_path, "w") as file:
        file.write(content)
    return f"File {file_path} created successfully."


def file_editor(file_path: str, mode: str, content: str):
    """
    Edit a file using the file editor tool.

    Args:
        file_path (str): The path to the file.
        mode (str): The mode to open the file in.
        content (str): The content to write to the file.

    Returns:
        str: The result of the file editing operation.
    """
    with open(file_path, mode) as file:
        file.write(content)
    return f"File {file_path} edited successfully."


# Agent
agent = Agent(
    agent_name="Devin",
    system_prompt=(
        "Autonomous agent that can interact with humans and other"
        " agents. Be Helpful and Kind. Use the tools provided to"
        " assist the user. Return all code in markdown format."
    ),
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    interactive=True,
    tools=[terminal, browser, file_editor, create_file],
    streaming=True,
    long_term_memory=memory,
)

# Run the agent
out = agent(
    "Create a CSV file with the latest tax rates for C corporations in the following ten states and the District of Columbia: Alabama, California, Florida, Georgia, Illinois, New York, North Carolina, Ohio, Texas, and Washington."
)
print(out)

```

### Long-term Memory Management

The Swarm Agent supports integration with various vector databases for long-term memory management. You can pass an instance of a `BaseVectorDatabase` implementation to the `long_term_memory` parameter when initializing the `Agent`.

```python
import os

from swarms_memory import ChromaDB

from swarms import Agent
from swarm_models import Anthropic
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)

# Initilaize the chromadb client
chromadb = ChromaDB(
    metric="cosine",
    output_dir="fiance_agent_rag",
    # docs_folder="artifacts", # Folder of your documents
)

# Model
model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"))


# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
    agent_description="Agent creates ",
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    dynamic_temperature_enabled=True,
    saved_state_path="finance_agent.json",
    user_name="swarms_corp",
    retry_attempts=3,
    context_length=200000,
    long_term_memory=chromadb,
)


agent.run(
    "What are the components of a startups stock incentive equity plan"
)

```

### Document Ingestion

The Swarm Agent can ingest various types of documents, such as PDFs, text files, Markdown files, and JSON files. You can pass a list of document paths or contents to the `docs` parameter when initializing the `Agent`.

```python
from swarms.structs import Agent

# Initialize the agent with documents
agent = Agent(llm=llm, max_loops=3, docs=["path/to/doc1.pdf", "path/to/doc2.txt"])
```

### Interactive Mode

The Swarm Agent supports an interactive mode, where users can engage in real-time communication with the agent. To enable interactive mode, set the `interactive` parameter to `True` when initializing the `Agent`.

```python
from swarms.structs import Agent

# Initialize the agent in interactive mode
agent = Agent(llm=llm, max_loops=3, interactive=True)

# Run the agent in interactive mode
agent.interactive_run()
```

### Sentiment Analysis

The Swarm Agent can perform sentiment analysis on its generated outputs using a sentiment analyzer function. You can pass a callable function to the `sentiment_analyzer` parameter when initializing the `Agent`.

```python
from swarms.structs import Agent
from my_sentiment_analyzer import sentiment_analyzer_function

# Initialize the agent with a sentiment analyzer
agent = Agent(
    agent_name = "sentiment-analyzer-agent-01", system_prompt="..."
    llm=llm, max_loops=3, sentiment_analyzer=sentiment_analyzer_function)
```


### Undo Functionality

```python
# Feature 2: Undo functionality
response = agent.run("Another task")
print(f"Response: {response}")
previous_state, message = agent.undo_last()
print(message)
```

### Response Filtering

```python
# Feature 3: Response filtering
agent.add_response_filter("report")
response = agent.filtered_run("Generate a report on finance")
print(response)
```

### Saving and Loading State

```python
# Save the agent state
agent.save_state('saved_flow.json')

# Load the agent state
agent = Agent(llm=llm_instance, max_loops=5)
agent.load('saved_flow.json')
agent.run("Continue with the task")
```

### Async and Concurrent Execution

```python
# Run a task concurrently
response = await agent.run_concurrent("Concurrent task")
print(response)

# Run multiple tasks concurrently
tasks = [
    {"task": "Task 1"},
    {"task": "Task 2", "img": "path/to/image.jpg"},
    {"task": "Task 3", "custom_param": 42}
]
responses = agent.bulk_run(tasks)
print(responses)
```


### Various other settings

```python
# # Convert the agent object to a dictionary
print(agent.to_dict())
print(agent.to_toml())
print(agent.model_dump_json())
print(agent.model_dump_yaml())

# Ingest documents into the agent's knowledge base
agent.ingest_docs("your_pdf_path.pdf")

# Receive a message from a user and process it
agent.receive_message(name="agent_name", message="message")

# Send a message from the agent to a user
agent.send_agent_message(agent_name="agent_name", message="message")

# Ingest multiple documents into the agent's knowledge base
agent.ingest_docs("your_pdf_path.pdf", "your_csv_path.csv")

# Run the agent with a filtered system prompt
agent.filtered_run(
    "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?"
)

# Run the agent with multiple system prompts
agent.bulk_run(
    [
        "How can I establish a ROTH IRA to buy stocks and get a tax break? What are the criteria?",
        "Another system prompt",
    ]
)

# Add a memory to the agent
agent.add_memory("Add a memory to the agent")

# Check the number of available tokens for the agent
agent.check_available_tokens()

# Perform token checks for the agent
agent.tokens_checks()

# Print the dashboard of the agent
agent.print_dashboard()


# Fetch all the documents from the doc folders
agent.get_docs_from_doc_folders()

# Activate agent ops

# Dump the model to a JSON file
agent.model_dump_json()
print(agent.to_toml())
```

--------------------------------------------------

# File: swarms/structs/agent_mcp.md

# Agent MCP Integration Guide

<div class="grid cards" markdown>

-   :material-connection: **Direct MCP Server Connection**

    ---

    Connect agents to MCP servers via URL for seamless integration

    [:octicons-arrow-right-24: Quick Start](#quick-start)

-   :material-tools: **Dynamic Tool Discovery**

    ---

    Automatically fetch and utilize tools from MCP servers

    [:octicons-arrow-right-24: Tool Discovery](#integration-flow)

-   :material-chart-line: **Real-time Communication**

    ---

    Server-sent Events (SSE) for live data streaming

    [:octicons-arrow-right-24: Configuration](#configuration-options)

-   :material-code-json: **Structured Output**

    ---

    Process and format responses with multiple output types

    [:octicons-arrow-right-24: Examples](#example-implementations)

</div>

## Overview

The **Model Context Protocol (MCP)** integration enables Swarms agents to dynamically connect to external tools and services through a standardized protocol. This powerful feature expands agent capabilities by providing access to APIs, databases, and specialized services.

!!! info "What is MCP?"
    The Model Context Protocol is a standardized way for AI agents to interact with external tools and services, providing a consistent interface for tool discovery and execution.

---

## :material-check-circle: Features Matrix

=== "✅ Current Capabilities"

    | Feature | Status | Description |
    |---------|--------|-------------|
    | **Direct MCP Connection** | ✅ Ready | Connect via URL to MCP servers |
    | **Tool Discovery** | ✅ Ready | Auto-fetch available tools |
    | **SSE Communication** | ✅ Ready | Real-time server communication |
    | **Multiple Tool Execution** | ✅ Ready | Execute multiple tools per session |
    | **Structured Output** | ✅ Ready | Format responses in multiple types |

=== "🚧 In Development"

    | Feature | Status | Expected |
    |---------|--------|----------|
    | **MCPConnection Model** | 🚧 Development | Q1 2024 |
    | **Multiple Server Support** | 🚧 Planned | Q2 2024 |
    | **Parallel Function Calling** | 🚧 Research | Q2 2024 |
    | **Auto-discovery** | 🚧 Planned | Q3 2024 |

---

## :material-rocket: Quick Start

!!! tip "Prerequisites"
    === "System Requirements"
        - Python 3.8+
        - Swarms framework
        - Running MCP server
        
    === "Installation"
        ```bash
        pip install swarms
        ```

### Step 1: Basic Agent Setup

!!! example "Simple MCP Agent"

    ```python
    from swarms import Agent

    # Initialize agent with MCP integration
    agent = Agent(
        agent_name="Financial-Analysis-Agent",
        agent_description="AI-powered financial advisor",
        max_loops=1,
        mcp_url="http://localhost:8000/sse",  # Your MCP server
        output_type="all",
    )

    # Execute task using MCP tools
    result = agent.run(
        "Get current Bitcoin price and analyze market trends"
    )
    print(result)
    ```

### Step 2: Advanced Configuration

!!! example "Production-Ready Setup"

    ```python
    from swarms import Agent
    from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT

    agent = Agent(
        agent_name="Advanced-Financial-Agent",
        agent_description="Comprehensive market analysis agent",
        system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
        max_loops=3,
        mcp_url="http://production-server:8000/sse",
        output_type="json",
        # Additional parameters for production
        temperature=0.1,
        verbose=True,
    )
    ```

---

## Integration Flow

The following diagram illustrates the complete MCP integration workflow:

```mermaid
graph TD
    A[🚀 Agent Receives Task] --> B[🔗 Connect to MCP Server]
    B --> C[🔍 Discover Available Tools]
    C --> D[🧠 Analyze Task Requirements]
    D --> E[📝 Generate Tool Request]
    E --> F[📤 Send to MCP Server]
    F --> G[⚙️ Server Processes Request]
    G --> H[📥 Receive Response]
    H --> I[🔄 Process & Validate]
    I --> J[📊 Summarize Results]
    J --> K[✅ Return Final Output]
    
    class A,K startEnd
    class D,I,J process
    class F,G,H communication
```

### Detailed Process Breakdown

!!! abstract "Process Steps"

    === "1-3: Initialization"
        
        **Task Initiation** - Agent receives user query
        
        **Server Connection** - Establish MCP server link
        
        **Tool Discovery** - Fetch available tool schemas

    === "4-6: Execution"
        
        **Task Analysis** - Determine required tools
        
        **Request Generation** - Create structured API calls
        
        **Server Communication** - Send requests via SSE

    === "7-9: Processing"
        
        **Server Processing** - MCP server executes tools
        
        **Response Handling** - Receive and validate data
        
        **Result Processing** - Parse and structure output

    === "10-11: Completion"
        
        **Summarization** - Generate user-friendly summary
        
        **Final Output** - Return complete response

---

## :material-cog: Configuration Options

### Agent Parameters

!!! note "Configuration Reference"

    | Parameter | Type | Description | Default | Example |
    |-----------|------|-------------|---------|---------|
    | `mcp_url` | `str` | MCP server endpoint | `None` | `"http://localhost:8000/sse"` |
    | `output_type` | `str` | Response format | `"str"` | `"json"`, `"all"`, `"dict"` |
    | `max_loops` | `int` | Execution iterations | `1` | `3` |
    | `temperature` | `float` | Response creativity | `0.1` | `0.1-1.0` |
    | `verbose` | `bool` | Debug logging | `False` | `True` |

---

## :material-code-tags: Example Implementations

### Cryptocurrency Trading Agent

!!! example "Crypto Price Monitor"

    ```python
    from swarms import Agent

    crypto_agent = Agent(
        agent_name="Crypto-Trading-Agent",
        agent_description="Real-time cryptocurrency market analyzer",
        max_loops=2,
        mcp_url="http://crypto-server:8000/sse",
        output_type="json",
        temperature=0.1,
    )

    # Multi-exchange price comparison
    result = crypto_agent.run(
        """
        Compare Bitcoin and Ethereum prices across OKX and HTX exchanges.
        Calculate arbitrage opportunities and provide trading recommendations.
        """
    )
    ```

### Financial Analysis Suite

!!! example "Advanced Financial Agent"

    ```python
    from swarms import Agent
    from swarms.prompts.finance_agent_sys_prompt import FINANCIAL_AGENT_SYS_PROMPT

    financial_agent = Agent(
        agent_name="Financial-Analysis-Suite",
        agent_description="Comprehensive financial market analyst",
        system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
        max_loops=4,
        mcp_url="http://finance-api:8000/sse",
        output_type="all",
        temperature=0.2,
    )

    # Complex market analysis
    analysis = financial_agent.run(
        """
        Perform a comprehensive analysis of Tesla (TSLA) stock:
        1. Current price and technical indicators
        2. Recent news sentiment analysis
        3. Competitor comparison (GM, Ford)
        4. Investment recommendation with risk assessment
        """
    )
    ```

### Custom Industry Agent

!!! example "Healthcare Data Agent"

    ```python
    from swarms import Agent

    healthcare_agent = Agent(
        agent_name="Healthcare-Data-Agent",
        agent_description="Medical data analysis and research assistant",
        max_loops=3,
        mcp_url="http://medical-api:8000/sse",
        output_type="dict",
        system_prompt="""
        You are a healthcare data analyst. Use available medical databases
        and research tools to provide accurate, evidence-based information.
        Always cite sources and include confidence levels.
        """,
    )

    research = healthcare_agent.run(
        "Research latest treatments for Type 2 diabetes and their efficacy rates"
    )
    ```

---

## :material-server: MCP Server Development

### FastMCP Server Example

!!! example "Building a Custom MCP Server"

    ```python
    from mcp.server.fastmcp import FastMCP
    import requests
    from typing import Optional
    import asyncio

    # Initialize MCP server
    mcp = FastMCP("crypto_analysis_server")

    @mcp.tool(
        name="get_crypto_price",
        description="Fetch current cryptocurrency price with market data",
    )
    def get_crypto_price(
        symbol: str, 
        currency: str = "USD",
        include_24h_change: bool = True
    ) -> dict:
        """
        Get real-time cryptocurrency price and market data.
        
        Args:
            symbol: Cryptocurrency symbol (e.g., BTC, ETH)
            currency: Target currency for price (default: USD)
            include_24h_change: Include 24-hour price change data
        """
        try:
            url = f"https://api.coingecko.com/api/v3/simple/price"
            params = {
                "ids": symbol.lower(),
                "vs_currencies": currency.lower(),
                "include_24hr_change": include_24h_change
            }
            
            response = requests.get(url, params=params, timeout=10)
            response.raise_for_status()
            
            data = response.json()
            return {
                "symbol": symbol.upper(),
                "price": data[symbol.lower()][currency.lower()],
                "currency": currency.upper(),
                "change_24h": data[symbol.lower()].get("24h_change", 0),
                "timestamp": "2024-01-15T10:30:00Z"
            }
            
        except Exception as e:
            return {"error": f"Failed to fetch price: {str(e)}"}

    @mcp.tool(
        name="analyze_market_sentiment",
        description="Analyze cryptocurrency market sentiment from social media",
    )
    def analyze_market_sentiment(symbol: str, timeframe: str = "24h") -> dict:
        """Analyze market sentiment for a cryptocurrency."""
        # Implement sentiment analysis logic
        return {
            "symbol": symbol,
            "sentiment_score": 0.75,
            "sentiment": "Bullish",
            "confidence": 0.85,
            "timeframe": timeframe
        }

    if __name__ == "__main__":
        mcp.run(transport="sse")
    ```

### Server Best Practices

!!! tip "Server Development Guidelines"

    === "🏗️ Architecture"
        - **Modular Design**: Separate tools into logical modules
        - **Error Handling**: Implement comprehensive error responses
        - **Async Support**: Use async/await for better performance
        - **Type Hints**: Include proper type annotations

    === "🔒 Security"
        - **Input Validation**: Sanitize all user inputs
        - **Rate Limiting**: Implement request throttling
        - **Authentication**: Add API key validation
        - **Logging**: Log all requests and responses

    === "⚡ Performance"
        - **Caching**: Cache frequently requested data
        - **Connection Pooling**: Reuse database connections
        - **Timeouts**: Set appropriate request timeouts
        - **Load Testing**: Test under realistic load

---

## :material-alert: Current Limitations

!!! warning "Important Limitations"

    ### 🚧 MCPConnection Model
    
    The enhanced connection model is under development:
    
    ```python
    # ❌ Not available yet
    from swarms.schemas.mcp_schemas import MCPConnection
    
    mcp_config = MCPConnection(
        url="http://server:8000/sse",
        headers={"Authorization": "Bearer token"},
        timeout=30,
        retry_attempts=3
    )
    
    # ✅ Use direct URL instead
    mcp_url = "http://server:8000/sse"
    ```

    ### 🚧 Single Server Limitation
    
    Currently supports one server per agent:
    
    ```python
    # ❌ Multiple servers not supported
    mcp_servers = [
        "http://server1:8000/sse",
        "http://server2:8000/sse"
    ]
    
    # ✅ Single server only
    mcp_url = "http://primary-server:8000/sse"
    ```

    ### 🚧 Sequential Execution
    
    Tools execute sequentially, not in parallel:
    
    ```python
    # Current: tool1() → tool2() → tool3()
    # Future: tool1() | tool2() | tool3() (parallel)
    ```

---

## :material-wrench: Troubleshooting

### Common Issues & Solutions

!!! bug "Connection Problems"

    === "Server Unreachable"
        **Symptoms**: Connection timeout or refused
        
        **Solutions**:
        ```bash
        # Check server status
        curl -I http://localhost:8000/sse
        
        # Verify port is open
        netstat -tulpn | grep :8000
        
        # Test network connectivity
        ping your-server-host
        ```

    === "Authentication Errors"
        **Symptoms**: 401/403 HTTP errors
        
        **Solutions**:
        ```python
        # Verify API credentials
        headers = {"Authorization": "Bearer your-token"}
        
        # Check token expiration
        # Validate permissions
        ```

    === "SSL/TLS Issues"
        **Symptoms**: Certificate errors
        
        **Solutions**:
        ```python
        # For development only
        import ssl
        ssl._create_default_https_context = ssl._create_unverified_context
        ```

!!! bug "Tool Discovery Failures"

    === "Empty Tool List"
        **Symptoms**: No tools found from server
        
        **Debugging**:
        ```python
        # Check server tool registration
        @mcp.tool(name="tool_name", description="...")
        def your_tool():
            pass
        
        # Verify server startup logs
        # Check tool endpoint responses
        ```

    === "Schema Validation Errors"
        **Symptoms**: Invalid tool parameters
        
        **Solutions**:
        ```python
        # Ensure proper type hints
        def tool(param: str, optional: int = 0) -> dict:
            return {"result": "success"}
        
        # Validate parameter types
        # Check required vs optional parameters
        ```

!!! bug "Performance Issues"

    === "Slow Response Times"
        **Symptoms**: Long wait times for responses
        
        **Optimization**:
        ```python
        # Increase timeout
        agent = Agent(
            mcp_url="http://server:8000/sse",
            timeout=60,  # seconds
        )
        
        # Optimize server performance
        # Use connection pooling
        # Implement caching
        ```

    === "Memory Usage"
        **Symptoms**: High memory consumption
        
        **Solutions**:
        ```python
        # Limit max_loops
        agent = Agent(max_loops=2)
        
        # Use streaming for large responses
        # Implement garbage collection
        ```

### Debugging Tools

!!! tip "Debug Configuration"

    ```python
    import logging
    
    # Enable debug logging
    logging.basicConfig(level=logging.DEBUG)
    
    agent = Agent(
        agent_name="Debug-Agent",
        mcp_url="http://localhost:8000/sse",
        verbose=True,  # Enable verbose output
        output_type="all",  # Get full execution trace
    )
    
    # Monitor network traffic
    # Check server logs
    # Use profiling tools
    ```

---

## :material-security: Security Best Practices

### Authentication & Authorization

!!! shield "Security Checklist"

    === "🔑 Authentication"
        - **API Keys**: Use strong, unique API keys
        - **Token Rotation**: Implement automatic token refresh
        - **Encryption**: Use HTTPS for all communications
        - **Storage**: Secure credential storage (environment variables)

    === "🛡️ Authorization"
        - **Role-Based Access**: Implement user role restrictions
        - **Tool Permissions**: Limit tool access per user/agent
        - **Rate Limiting**: Prevent abuse with request limits
        - **Audit Logging**: Log all tool executions

    === "🔒 Data Protection"
        - **Input Sanitization**: Validate all user inputs
        - **Output Filtering**: Sanitize sensitive data in responses
        - **Encryption**: Encrypt sensitive data in transit/rest
        - **Compliance**: Follow industry standards (GDPR, HIPAA)

### Secure Configuration

!!! example "Production Security Setup"

    ```python
    import os
    from swarms import Agent

    # Secure configuration
    agent = Agent(
        agent_name="Production-Agent",
        mcp_url=os.getenv("MCP_SERVER_URL"),  # From environment
        # Additional security headers would go here when MCPConnection is available
        verbose=False,  # Disable verbose logging in production
        output_type="json",  # Structured output only
    )

    # Environment variables (.env file)
    """
    MCP_SERVER_URL=https://secure-server.company.com/sse
    MCP_API_KEY=your-secure-api-key
    MCP_TIMEOUT=30
    """
    ```

---

## :material-chart-line: Performance Optimization

### Agent Optimization

!!! rocket "Performance Tips"

    === "⚡ Configuration"
        ```python
        # Optimized agent settings
        agent = Agent(
            max_loops=2,  # Limit iterations
            temperature=0.1,  # Reduce randomness
            output_type="json",  # Structured output
            # Future: connection_pool_size=10
        )
        ```

    === "🔄 Caching"
        ```python
        # Implement response caching
        from functools import lru_cache
        
        @lru_cache(maxsize=100)
        def cached_mcp_call(query):
            return agent.run(query)
        ```

    === "📊 Monitoring"
        ```python
        import time
        
        start_time = time.time()
        result = agent.run("query")
        execution_time = time.time() - start_time
        
        print(f"Execution time: {execution_time:.2f}s")
        ```

### Server Optimization

!!! rocket "Server Performance"

    ```python
    from mcp.server.fastmcp import FastMCP
    import asyncio
    from concurrent.futures import ThreadPoolExecutor

    mcp = FastMCP("optimized_server")

    # Async tool with thread pool
    @mcp.tool(name="async_heavy_task")
    async def heavy_computation(data: str) -> dict:
        loop = asyncio.get_event_loop()
        with ThreadPoolExecutor() as executor:
            result = await loop.run_in_executor(
                executor, process_heavy_task, data
            )
        return result

    def process_heavy_task(data):
        # CPU-intensive processing
        return {"processed": data}
    ```

---

## :material-timeline: Future Roadmap

### Upcoming Features

!!! rocket "Development Timeline"

    === "1 Week"
        - **MCPConnection Model** - Enhanced configuration
        - **Authentication Support** - Built-in auth mechanisms
        - **Error Recovery** - Automatic retry logic
        - **Connection Pooling** - Improved performance

    === "2 Week"
        - **Multiple Server Support** - Connect to multiple MCPs
        - **Parallel Execution** - Concurrent tool calling
        - **Load Balancing** - Distribute requests across servers
        - **Advanced Monitoring** - Real-time metrics

    === "3 Week"
        - **Auto-discovery** - Automatic server detection
        - **Workflow Engine** - Complex task orchestration
        - **Plugin System** - Custom MCP extensions
        - **Cloud Integration** - Native cloud provider support

### Contributing

!!! heart "Get Involved"

    We welcome contributions to improve MCP integration:

    - **Bug Reports**: [GitHub Issues](https://github.com/kyegomez/swarms/issues)
    - **Feature Requests**: [Discussions](https://github.com/kyegomez/swarms/discussions)
    - **Code Contributions**: [Pull Requests](https://github.com/kyegomez/swarms/pulls)
    - **Documentation**: Help improve these docs

---

## :material-help-circle: Support & Resources

### Getting Help

!!! question "Need Assistance?"

    === "📚 Documentation"
        - [Official Docs](https://docs.swarms.world)
        - [Tutorials](https://docs.swarms.world/tutorials)

    === "💬 Community"
        - [Discord Server](https://discord.gg/EamjgSaEQf)
        - [GitHub Discussions](https://github.com/kyegomez/swarms/discussions)

    === "🔧 Development"
        - [GitHub Repository](https://github.com/kyegomez/swarms)
        - [Example Projects](https://github.com/kyegomez/swarms/tree/main/examples)
        - [Contributing Guide](https://github.com/kyegomez/swarms/blob/main/CONTRIBUTING.md)

### Quick Reference

!!! abstract "Cheat Sheet"

    ```python
    # Basic setup
    from swarms import Agent
    
    agent = Agent(
        agent_name="Your-Agent",
        mcp_url="http://localhost:8000/sse",
        output_type="json",
        max_loops=2
    )
    
    # Execute task
    result = agent.run("Your query here")
    
    # Common patterns
    crypto_query = "Get Bitcoin price"
    analysis_query = "Analyze Tesla stock performance"
    research_query = "Research recent AI developments"
    ```

---

## :material-check-all: Conclusion

The MCP integration brings powerful external tool connectivity to Swarms agents, enabling them to access real-world data and services through a standardized protocol. While some advanced features are still in development, the current implementation provides robust functionality for most use cases.

!!! success "Ready to Start?"
    
    Begin with the [Quick Start](#quick-start) section and explore the [examples](#example-implementations) to see MCP integration in action. As new features become available, this documentation will be updated with the latest capabilities and best practices.

!!! tip "Stay Updated"
    
    Join our [Discord community](https://discord.gg/EamjgSaEQf) to stay informed about new MCP features and connect with other developers building amazing agent applications.

---

<div class="grid cards" markdown>

-   :material-rocket: **[Quick Start](#quick-start)**

    Get up and running with MCP integration in minutes

-   :material-book-open: **[Examples](#example-implementations)**

    Explore real-world implementations and use cases

-   :material-cog: **[Configuration](#configuration-options)**

    Learn about all available configuration options

-   :material-help: **[Troubleshooting](#troubleshooting)**

    Solve common issues and optimize performance

</div>


--------------------------------------------------

# File: swarms/structs/agent_multi_agent_communication.md

# Agent Multi-Agent Communication Methods

The Agent class provides powerful built-in methods for facilitating communication and collaboration between multiple agents. These methods enable agents to talk to each other, pass information, and coordinate complex multi-agent workflows seamlessly.

## Overview

Multi-agent communication is essential for building sophisticated AI systems where different agents need to collaborate, share information, and coordinate their actions. The Agent class provides several methods to facilitate this communication:

| Method | Purpose | Use Case |
|--------|---------|----------|
| `talk_to` | Direct communication between two agents | Agent handoffs, expert consultation |
| `talk_to_multiple_agents` | Concurrent communication with multiple agents | Broadcasting, consensus building |
| `receive_message` | Process incoming messages from other agents | Message handling, task delegation |
| `send_agent_message` | Send formatted messages to other agents | Direct messaging, notifications |

## Features

| Feature                        | Description                                                        |
|---------------------------------|--------------------------------------------------------------------|
| **Direct Agent Communication**  | Enable one-to-one conversations between agents                     |
| **Concurrent Multi-Agent Communication** | Broadcast messages to multiple agents simultaneously         |
| **Message Processing**          | Handle incoming messages with contextual formatting                |
| **Error Handling**              | Robust error handling for failed communications                    |
| **Threading Support**           | Efficient concurrent processing using ThreadPoolExecutor           |
| **Flexible Parameters**         | Support for images, custom arguments, and kwargs                   |

---

## Core Methods

### `talk_to(agent, task, img=None, *args, **kwargs)`

Enables direct communication between the current agent and another agent. The method processes the task, generates a response, and then passes that response to the target agent.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agent` | `Any` | Required | The target agent instance to communicate with |
| `task` | `str` | Required | The task or message to send to the agent |
| `img` | `str` | `None` | Optional image path for multimodal communication |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

**Returns:** `Any` - The response from the target agent

**Usage Example:**

```python
from swarms import Agent

# Create two specialized agents
researcher = Agent(
    agent_name="Research-Agent",
    system_prompt="You are a research specialist focused on gathering and analyzing information.",
    max_loops=1,
)

analyst = Agent(
    agent_name="Analysis-Agent", 
    system_prompt="You are an analytical specialist focused on interpreting research data.",
    max_loops=1,
)

# Agent communication
research_result = researcher.talk_to(
    agent=analyst,
    task="Analyze the market trends for renewable energy stocks"
)

print(research_result)
```

### `talk_to_multiple_agents(agents, task, *args, **kwargs)`

Enables concurrent communication with multiple agents using ThreadPoolExecutor for efficient parallel processing.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agents` | `List[Union[Any, Callable]]` | Required | List of agent instances to communicate with |
| `task` | `str` | Required | The task or message to send to all agents |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

**Returns:** `List[Any]` - List of responses from all agents (or None for failed communications)

**Usage Example:**

```python
from swarms import Agent

# Create multiple specialized agents
agents = [
    Agent(
        agent_name="Financial-Analyst",
        system_prompt="You are a financial analysis expert.",
        max_loops=1,
    ),
    Agent(
        agent_name="Risk-Assessor", 
        system_prompt="You are a risk assessment specialist.",
        max_loops=1,
    ),
    Agent(
        agent_name="Market-Researcher",
        system_prompt="You are a market research expert.",
        max_loops=1,
    )
]

coordinator = Agent(
    agent_name="Coordinator-Agent",
    system_prompt="You coordinate multi-agent analysis.",
    max_loops=1,
)

# Broadcast to multiple agents
responses = coordinator.talk_to_multiple_agents(
    agents=agents,
    task="Evaluate the investment potential of Tesla stock"
)

# Process responses
for i, response in enumerate(responses):
    if response:
        print(f"Agent {i+1} Response: {response}")
    else:
        print(f"Agent {i+1} failed to respond")
```

### `receive_message(agent_name, task, *args, **kwargs)`

Processes incoming messages from other agents with proper context formatting.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agent_name` | `str` | Required | Name of the sending agent |
| `task` | `str` | Required | The message content |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

**Returns:** `Any` - The agent's response to the received message

**Usage Example:**

```python
from swarms import Agent

# Create an agent that can receive messages
recipient_agent = Agent(
    agent_name="Support-Agent",
    system_prompt="You provide helpful support and assistance.",
    max_loops=1,
)

# Simulate receiving a message from another agent
response = recipient_agent.receive_message(
    agent_name="Customer-Service-Agent",
    task="A customer is asking about refund policies. Can you help?"
)

print(response)
```

### `send_agent_message(agent_name, message, *args, **kwargs)`

Sends a formatted message from the current agent to a specified target agent.

**Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agent_name` | `str` | Required | Name of the target agent |
| `message` | `str` | Required | The message to send |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

**Returns:** `Any` - The result of sending the message

**Usage Example:**

```python
from swarms import Agent

sender_agent = Agent(
    agent_name="Notification-Agent",
    system_prompt="You send notifications and updates.",
    max_loops=1,
)

# Send a message to another agent
result = sender_agent.send_agent_message(
    agent_name="Task-Manager-Agent",
    message="Task XYZ has been completed successfully"
)

print(result)
```


This comprehensive guide covers all aspects of multi-agent communication using the Agent class methods. These methods provide the foundation for building sophisticated multi-agent systems with robust communication capabilities. 

--------------------------------------------------

# File: swarms/structs/agent_rearrange.md

# `AgentRearrange` Class

The `AgentRearrange` class represents a swarm of agents for rearranging tasks. It allows you to create a swarm of agents, add or remove agents from the swarm, and run the swarm to process tasks based on a specified flow pattern. The class now includes **sequential awareness** features that allow agents to know about the agents ahead and behind them in sequential flows.

## Attributes
----------

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` | Unique identifier for the swarm |
| `name` | `str` | Name of the swarm |
| `description` | `str` | Description of the swarm's purpose |
| `agents` | `dict` | Dictionary mapping agent names to Agent objects |
| `flow` | `str` | Flow pattern defining task execution order |
| `max_loops` | `int` | Maximum number of execution loops |
| `verbose` | `bool` | Whether to enable verbose logging |
| `memory_system` | `BaseVectorDatabase` | Memory system for storing agent interactions |
| `human_in_the_loop` | `bool` | Whether human intervention is enabled |
| `custom_human_in_the_loop` | `Callable` | Custom function for human intervention |
| `output_type` | `OutputType` | Format of output ("all", "final", "list", or "dict") |
| `autosave` | `bool` | Whether to automatically save agent data |
| `rules` | `str` | Custom rules to add to the conversation |
| `team_awareness` | `bool` | Whether to enable team awareness and sequential flow information |
| `time_enabled` | `bool` | Whether to enable timestamps in conversation |
| `message_id_on` | `bool` | Whether to enable message IDs in conversation |

## Methods
-------

### `__init__(self, id: str = swarm_id(), name: str = "AgentRearrange", description: str = "A swarm of agents for rearranging tasks.", agents: List[Union[Agent, Callable]] = None, flow: str = None, max_loops: int = 1, verbose: bool = True, memory_system: Any = None, human_in_the_loop: bool = False, custom_human_in_the_loop: Optional[Callable[[str], str]] = None, output_type: OutputType = "all", autosave: bool = True, rules: str = None, team_awareness: bool = False, time_enabled: bool = False, message_id_on: bool = False, *args, **kwargs)`

Initializes the `AgentRearrange` object with enhanced sequential awareness capabilities.

| Parameter | Type | Description |
| --- | --- | --- |
| `id` | `str` (optional) | Unique identifier for the swarm. Defaults to auto-generated UUID. |
| `name` | `str` (optional) | Name of the swarm. Defaults to "AgentRearrange". |
| `description` | `str` (optional) | Description of the swarm's purpose. Defaults to "A swarm of agents for rearranging tasks.". |
| `agents` | `List[Union[Agent, Callable]]` (optional) | A list of `Agent` objects or callables. Defaults to `None`. |
| `flow` | `str` (optional) | The flow pattern of the tasks. Defaults to `None`. |
| `max_loops` | `int` (optional) | The maximum number of loops for the agents to run. Defaults to `1`. |
| `verbose` | `bool` (optional) | Whether to enable verbose logging or not. Defaults to `True`. |
| `memory_system` | `Any` (optional) | Memory system for storing agent interactions. Defaults to `None`. |
| `human_in_the_loop` | `bool` (optional) | Whether human intervention is enabled. Defaults to `False`. |
| `custom_human_in_the_loop` | `Callable[[str], str]` (optional) | Custom function for human intervention. Defaults to `None`. |
| `output_type` | `OutputType` (optional) | Format of output. Defaults to `"all"`. |
| `autosave` | `bool` (optional) | Whether to automatically save agent data. Defaults to `True`. |
| `rules` | `str` (optional) | Custom rules to add to the conversation. Defaults to `None`. |
| `team_awareness` | `bool` (optional) | Whether to enable team awareness and sequential flow information. Defaults to `False`. |
| `time_enabled` | `bool` (optional) | Whether to enable timestamps in conversation. Defaults to `False`. |
| `message_id_on` | `bool` (optional) | Whether to enable message IDs in conversation. Defaults to `False`. |

### `add_agent(self, agent: Agent)`

Adds an agent to the swarm.

| Parameter | Type | Description |
| --- | --- | --- |
| `agent` | `Agent` | The agent to be added. |

### `remove_agent(self, agent_name: str)`

Removes an agent from the swarm.

| Parameter | Type | Description |
| --- | --- | --- |
| `agent_name` | `str` | The name of the agent to be removed. |

### `add_agents(self, agents: List[Agent])`

Adds multiple agents to the swarm.

| Parameter | Type | Description |
| --- | --- | --- |
| `agents` | `List[Agent]` | A list of `Agent` objects. |

### `validate_flow(self)`

Validates the flow pattern.

**Raises:**

-   `ValueError`: If the flow pattern is incorrectly formatted or contains duplicate agent names.

**Returns:**

-   `bool`: `True` if the flow pattern is valid.

### **Sequential Awareness Methods**

#### `get_agent_sequential_awareness(self, agent_name: str) -> str`

Gets the sequential awareness information for a specific agent, showing which agents come before and after in the sequence.

| Parameter | Type | Description |
| --- | --- | --- |
| `agent_name` | `str` | The name of the agent to get awareness for. |

**Returns:**

-   `str`: A string describing the agents ahead and behind in the sequence.

**Example:**
```python
awareness = agent_system.get_agent_sequential_awareness("Agent2")
# Returns: "Sequential awareness: Agent ahead: Agent1 | Agent behind: Agent3"
```

#### `get_sequential_flow_structure(self) -> str`

Gets the overall sequential flow structure information showing the complete workflow with relationships between agents.

**Returns:**

-   `str`: A string describing the complete sequential flow structure.

**Example:**
```python
flow_structure = agent_system.get_sequential_flow_structure()
# Returns: "Sequential Flow Structure:
# Step 1: Agent1
# Step 2: Agent2 (follows: Agent1) (leads to: Agent3)
# Step 3: Agent3 (follows: Agent2)"
```

### `run(self, task: str = None, img: str = None, *args, **kwargs)`

Executes the agent rearrangement task with specified compute resources.

| Parameter | Type | Description |
| --- | --- | --- |
| `task` | `str` (optional) | The task to execute. Defaults to `None`. |
| `img` | `str` (optional) | Path to input image if required. Defaults to `None`. |
| `*args` | - | Additional positional arguments passed to `_run()`. |
| `**kwargs` | - | Additional keyword arguments passed to `_run()`. |

**Returns:**

-   The result from executing the task through the cluster operations wrapper.

### `batch_run(self, tasks: List[str], img: Optional[List[str]] = None, batch_size: int = 10, *args, **kwargs)`

Process multiple tasks in batches.

| Parameter | Type | Description |
| --- | --- | --- |
| `tasks` | `List[str]` | List of tasks to process |
| `img` | `List[str]` (optional) | Optional list of images corresponding to tasks |
| `batch_size` | `int` | Number of tasks to process simultaneously |
| `*args` | - | Additional positional arguments |
| `**kwargs` | - | Additional keyword arguments |

**Returns:**

-   `List[str]`: List of results corresponding to input tasks

### `concurrent_run(self, tasks: List[str], img: Optional[List[str]] = None, max_workers: Optional[int] = None, *args, **kwargs)`

Process multiple tasks concurrently using ThreadPoolExecutor.

| Parameter | Type | Description |
| --- | --- | --- |
| `tasks` | `List[str]` | List of tasks to process |
| `img` | `List[str]` (optional) | Optional list of images corresponding to tasks |
| `max_workers` | `int` (optional) | Maximum number of worker threads |
| `*args` | - | Additional positional arguments |
| `**kwargs` | - | Additional keyword arguments |

**Returns:**

-   `List[str]`: List of results corresponding to input tasks

## **Sequential Awareness Feature**

The `AgentRearrange` class now includes a powerful **sequential awareness** feature that enhances agent collaboration in sequential workflows. When agents are executed sequentially, they automatically receive information about:

- **Agent ahead**: The agent that completed their task before them
- **Agent behind**: The agent that will receive their output next

This feature is automatically enabled when using sequential flows and provides agents with context about their position in the workflow, improving coordination and task understanding.

### How It Works

1. **Automatic Detection**: The system automatically detects when agents are running sequentially vs. in parallel
2. **Context Injection**: Before each sequential agent runs, awareness information is added to the conversation
3. **Enhanced Collaboration**: Agents can reference previous agents' work and prepare output for the next agent

### Example with Sequential Awareness

```python
from swarms import Agent, AgentRearrange

# Create agents
agent1 = Agent(agent_name="Researcher", system_prompt="Research the topic")
agent2 = Agent(agent_name="Writer", system_prompt="Write based on research")
agent3 = Agent(agent_name="Editor", system_prompt="Edit the written content")

# Create sequential workflow
workflow = AgentRearrange(
    agents=[agent1, agent2, agent3],
    flow="Researcher -> Writer -> Editor",
    team_awareness=True  # Enables sequential awareness
)

# Run the workflow
result = workflow.run("Research and write about artificial intelligence")
```

**What happens automatically:**
- **Researcher** runs first (no awareness info needed)
- **Writer** receives: "Sequential awareness: Agent ahead: Researcher | Agent behind: Editor"
- **Editor** receives: "Sequential awareness: Agent ahead: Writer"

## Documentation for `rearrange` Function
======================================

The `rearrange` function is a helper function that rearranges the given list of agents based on the specified flow.

## Parameters
----------

| Parameter | Type | Description |
| --- | --- | --- |
| `name` | `str` (optional) | Name for the agent system. Defaults to `None`. |
| `description` | `str` (optional) | Description for the agent system. Defaults to `None`. |
| `agents` | `List[Agent]` | The list of agents to be rearranged. |
| `flow` | `str` | The flow used for rearranging the agents. |
| `task` | `str` (optional) | The task to be performed during rearrangement. Defaults to `None`. |
| `img` | `str` (optional) | Path to input image if required. Defaults to `None`. |
| `*args` | - | Additional positional arguments. |
| `**kwargs` | - | Additional keyword arguments. |

## Returns
-------

The result of running the agent system with the specified task.

### Example
-------

```python
agents = [agent1, agent2, agent3]
flow = "agent1 -> agent2, agent3"
task = "Perform a task"
rearrange(agents, flow, task)
```

### Example Usage
-------------

Here's an example of how to use the `AgentRearrange` class and the `rearrange` function with the new sequential awareness features:

```python
from swarms import Agent, AgentRearrange
from typing import List

# Initialize the director agent
director = Agent(
    agent_name="Accounting Director",
    system_prompt="Directs the accounting tasks for the workers",
    llm=Anthropic(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="accounting_director.json",
)

# Initialize worker 1
worker1 = Agent(
    agent_name="Accountant 1",
    system_prompt="Processes financial transactions and prepares financial statements",
    llm=Anthropic(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="accountant1.json",
)

# Initialize worker 2
worker2 = Agent(
    agent_name="Accountant 2",
    system_prompt="Performs audits and ensures compliance with financial regulations",
    llm=Anthropic(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="accountant2.json",
)

# Create a list of agents
agents = [director, worker1, worker2]

# Define the flow pattern
flow = "Accounting Director -> Accountant 1 -> Accountant 2"

# Using AgentRearrange class with sequential awareness
agent_system = AgentRearrange(
    agents=agents, 
    flow=flow,
    team_awareness=True,  # Enables sequential awareness
    time_enabled=True,    # Enable timestamps
    message_id_on=True    # Enable message IDs
)

# Get sequential flow information
flow_structure = agent_system.get_sequential_flow_structure()
print("Flow Structure:", flow_structure)

# Get awareness for specific agents
worker1_awareness = agent_system.get_agent_sequential_awareness("Accountant 1")
print("Worker1 Awareness:", worker1_awareness)

# Run the workflow
output = agent_system.run("Process monthly financial statements")
print(output)
```

In this example, we first initialize three agents: `director`, `worker1`, and `worker2`. Then, we create a list of these agents and define the flow pattern `"Director -> Worker1 -> Worker2"`.

The new sequential awareness features provide:
- **Automatic context**: Each agent knows who came before and who comes after
- **Better coordination**: Agents can reference previous work and prepare for next steps
- **Flow visualization**: You can see the complete workflow structure
- **Enhanced logging**: Better tracking of agent interactions

## Error Handling
--------------

The `AgentRearrange` class includes error handling mechanisms to validate the flow pattern. If the flow pattern is incorrectly formatted or contains duplicate agent names, a `ValueError` will be raised with an appropriate error message.

### Example:

```python
# Invalid flow pattern
invalid_flow = "Director->Worker1,Worker2->Worker3"
agent_system = AgentRearrange(agents=agents, flow=invalid_flow)
output = agent_system.run("Some task")`
```

This will raise a `ValueError` with the message `"Agent 'Worker3' is not registered."`.

## Parallel and Sequential Processing
----------------------------------

The `AgentRearrange` class supports both parallel and sequential processing of tasks based on the specified flow pattern. If the flow pattern includes multiple agents separated by commas (e.g., `"agent1, agent2"`), the agents will be executed in parallel, and their outputs will be concatenated. If the flow pattern includes a single agent, it will be executed sequentially with enhanced awareness.

### Parallel processing
`parallel_flow = "Worker1, Worker2 -> Director"`

### Sequential processing with awareness
`sequential_flow = "Worker1 -> Worker2 -> Director"`

In the `parallel_flow` example, `Worker1` and `Worker2` will be executed in parallel, and their outputs will be concatenated and passed to `Director`. 

In the `sequential_flow` example, `Worker1` will be executed first, then `Worker2` will receive awareness that `Worker1` came before and `Director` comes after, and finally `Director` will receive awareness that `Worker2` came before.

## Logging and Monitoring
-------

The `AgentRearrange` class includes comprehensive logging capabilities using the `loguru` library. The new sequential awareness features add enhanced logging:

```bash
2023-05-08 10:30:15.456 | INFO     | agent_rearrange:__init__:34 - Adding agent Director to the swarm.
2023-05-08 10:30:15.457 | INFO     | agent_rearrange:__init__:34 - Adding agent Worker1 to the swarm.
2023-05-08 10:30:15.457 | INFO     | agent_rearrange:__init__:34 - Adding agent Worker2 to the swarm.
2023-05-08 10:30:15.458 | INFO     | agent_rearrange:run:118 - Running agents in parallel: ['Worker1', 'Worker2']
2023-05-08 10:30:15.459 | INFO     | agent_rearrange:run:121 - Running agents sequentially: ['Director']
2023-05-08 10:30:15.460 | INFO     | agent_rearrange:run:125 - Added sequential awareness for Worker2: Sequential awareness: Agent ahead: Worker1 | Agent behind: Director
```

## Additional Parameters
---------------------

The `AgentRearrange` class now accepts additional parameters for enhanced functionality:

```python
agent_system = AgentRearrange(
    agents=agents, 
    flow=flow,
    team_awareness=True,      # Enable sequential awareness
    time_enabled=True,        # Enable conversation timestamps
    message_id_on=True,       # Enable message IDs
    verbose=True              # Enable detailed logging
)
```

## Customization
-------------

The `AgentRearrange` class and the `rearrange` function can be customized and extended to suit specific use cases. The new sequential awareness features provide a foundation for building more sophisticated agent coordination systems.

## Limitations
-----------

It's important to note that the `AgentRearrange` class and the `rearrange` function rely on the individual agents to process tasks correctly. The quality of the output will depend on the capabilities and configurations of the agents used in the swarm. 

The sequential awareness feature works best with agents that can understand and utilize context about their position in the workflow.

## Conclusion
----------

The `AgentRearrange` class and the `rearrange` function provide a flexible and extensible framework for orchestrating swarms of agents to process tasks based on a specified flow pattern. The new **sequential awareness** features significantly enhance agent collaboration by providing context about workflow relationships.

By combining the capabilities of individual agents with enhanced awareness of their position in the workflow, you can create more intelligent and coordinated multi-agent systems that understand not just their individual tasks, but also their role in the larger workflow.

Whether you're working on natural language processing tasks, data analysis, or any other domain where agent-based systems can be beneficial, the enhanced `AgentRearrange` class provides a solid foundation for building sophisticated swarm-based solutions with improved coordination and context awareness.



--------------------------------------------------

# File: swarms/structs/agent_registry.md

# AgentRegistry Documentation

The `AgentRegistry` class is designed to manage a collection of agents, providing methods for adding, deleting, updating, and querying agents. This class ensures thread-safe operations on the registry, making it suitable for concurrent environments. Additionally, the `AgentModel` class is a Pydantic model used for validating and storing agent information.

## Attributes

### AgentModel

| Attribute | Type   | Description                          |
|-----------|--------|--------------------------------------|
| `agent_id`| `str`  | The unique identifier for the agent. |
| `agent`   | `Agent`| The agent object.                    |

### AgentRegistry

| Attribute | Type                | Description                               |
|-----------|---------------------|-------------------------------------------|
| `agents`  | `Dict[str, AgentModel]` | A dictionary mapping agent IDs to `AgentModel` instances. |
| `lock`    | `Lock`              | A threading lock for thread-safe operations. |

## Methods

### `__init__(self)`

Initializes the `AgentRegistry` object.

- **Usage Example:**
  ```python
  registry = AgentRegistry()
  ```

### `add(self, agent_id: str, agent: Agent) -> None`

Adds a new agent to the registry.

- **Parameters:**
  - `agent_id` (`str`): The unique identifier for the agent.
  - `agent` (`Agent`): The agent to add.

- **Raises:**
  - `ValueError`: If the agent ID already exists in the registry.
  - `ValidationError`: If the input data is invalid.

- **Usage Example:**
  ```python
  agent = Agent(agent_name="Agent1")
  registry.add("agent_1", agent)
  ```

### `delete(self, agent_id: str) -> None`

Deletes an agent from the registry.

- **Parameters:**
  - `agent_id` (`str`): The unique identifier for the agent to delete.

- **Raises:**
  - `KeyError`: If the agent ID does not exist in the registry.

- **Usage Example:**
  ```python
  registry.delete("agent_1")
  ```

### `update_agent(self, agent_id: str, new_agent: Agent) -> None`

Updates an existing agent in the registry.

- **Parameters:**
  - `agent_id` (`str`): The unique identifier for the agent to update.
  - `new_agent` (`Agent`): The new agent to replace the existing one.

- **Raises:**
  - `KeyError`: If the agent ID does not exist in the registry.
  - `ValidationError`: If the input data is invalid.

- **Usage Example:**
  ```python
  new_agent = Agent(agent_name="UpdatedAgent")
  registry.update_agent("agent_1", new_agent)
  ```

### `get(self, agent_id: str) -> Agent`

Retrieves an agent from the registry.

- **Parameters:**
  - `agent_id` (`str`): The unique identifier for the agent to retrieve.

- **Returns:**
  - `Agent`: The agent associated with the given agent ID.

- **Raises:**
  - `KeyError`: If the agent ID does not exist in the registry.

- **Usage Example:**
  ```python
  agent = registry.get("agent_1")
  ```

### `list_agents(self) -> List[str]`

Lists all agent identifiers in the registry.

- **Returns:**
  - `List[str]`: A list of all agent identifiers.

- **Usage Example:**
  ```python
  agent_ids = registry.list_agents()
  ```

### `query(self, condition: Optional[Callable[[Agent], bool]] = None) -> List[Agent]`

Queries agents based on a condition.

- **Parameters:**
  - `condition` (`Optional[Callable[[Agent], bool]]`): A function that takes an agent and returns a boolean indicating whether the agent meets the condition. Defaults to `None`.

- **Returns:**
  - `List[Agent]`: A list of agents that meet the condition.

- **Usage Example:**
  ```python
  def is_active(agent):
      return agent.is_active

  active_agents = registry.query(is_active)
  ```

### `find_agent_by_name(self, agent_name: str) -> Agent`

Finds an agent by its name.

- **Parameters:**
  - `agent_name` (`str`): The name of the agent to find.

- **Returns:**
  - `Agent`: The agent with the specified name.

- **Usage Example:**
  ```python
  agent = registry.find_agent_by_name("Agent1")
  ```


### Full Example

```python
from swarms.structs.agent_registry import AgentRegistry
from swarms import Agent, OpenAIChat, Anthropic

# Initialize the agents
growth_agent1 = Agent(
  agent_name="Marketing Specialist",
  system_prompt="You're the marketing specialist, your purpose is to help companies grow by improving their marketing strategies!",
  agent_description="Improve a company's marketing strategies!",
  llm=OpenAIChat(),
  max_loops="auto",
  autosave=True,
  dashboard=False,
  verbose=True,
  streaming_on=True,
  saved_state_path="marketing_specialist.json",
  stopping_token="Stop!",
  interactive=True,
  context_length=1000,
)

growth_agent2 = Agent(
  agent_name="Sales Specialist",
  system_prompt="You're the sales specialist, your purpose is to help companies grow by improving their sales strategies!",
  agent_description="Improve a company's sales strategies!",
  llm=Anthropic(),
  max_loops="auto",
  autosave=True,
  dashboard=False,
  verbose=True,
  streaming_on=True,
  saved_state_path="sales_specialist.json",
  stopping_token="Stop!",
  interactive=True,
  context_length=1000,
)

growth_agent3 = Agent(
  agent_name="Product Development Specialist",
  system_prompt="You're the product development specialist, your purpose is to help companies grow by improving their product development strategies!",
  agent_description="Improve a company's product development strategies!",
  llm=Anthropic(),
  max_loops="auto",
  autosave=True,
  dashboard=False,
  verbose=True,
  streaming_on=True,
  saved_state_path="product_development_specialist.json",
  stopping_token="Stop!",
  interactive=True,
  context_length=1000,
)

growth_agent4 = Agent(
  agent_name="Customer Service Specialist",
  system_prompt="You're the customer service specialist, your purpose is to help companies grow by improving their customer service strategies!",
  agent_description="Improve a company's customer service strategies!",
  llm=OpenAIChat(),
  max_loops="auto",
  autosave=True,
  dashboard=False,
  verbose=True,
  streaming_on=True,
  saved_state_path="customer_service_specialist.json",
  stopping_token="Stop!",
  interactive=True,
  context_length=1000,
)


# Register the agents\
registry = AgentRegistry()

# Register the agents
registry.add("Marketing Specialist", growth_agent1)
registry.add("Sales Specialist", growth_agent2)
registry.add("Product Development Specialist", growth_agent3)
registry.add("Customer Service Specialist", growth_agent4)

```

## Logging and Error Handling

Each method in the `AgentRegistry` class includes logging to track the execution flow and captures errors to provide detailed information in case of failures. This is crucial for debugging and ensuring smooth operation of the registry. The `report_error` function is used for reporting exceptions that occur during method execution.

## Additional Tips

- Ensure that agents provided to the `AgentRegistry` are properly initialized and configured to handle the tasks they will receive.
- Utilize the logging information to monitor and debug the registry operations.
- Use the `lock` attribute to ensure thread-safe operations when accessing or modifying the registry.



--------------------------------------------------

# File: swarms/structs/artifact.md

# swarms.structs Documentation

## Introduction

The swarms.structs library provides a collection of classes for representing artifacts and their attributes. This documentation will provide an overview of the `Artifact` class, its attributes, functionality, and usage examples.

### Artifact Class

The `Artifact` class represents an artifact and its attributes. It inherits from the `BaseModel` class and includes the following attributes:

#### Attributes

1. `artifact_id (str)`: Id of the artifact.
2. `file_name (str)`: Filename of the artifact.
3. `relative_path (str, optional)`: Relative path of the artifact in the agent's workspace.

These attributes are crucial for identifying and managing different artifacts within a given context.

## Class Definition

The `Artifact` class can be defined as follows:

```python
class Artifact(BaseModel):
    """
    Represents an artifact.

    Attributes:
        artifact_id (str): Id of the artifact.
        file_name (str): Filename of the artifact.
        relative_path (str, optional): Relative path of the artifact in the agent's workspace.
    """

    artifact_id: str = Field(
        ...,
        description="Id of the artifact",
        example="b225e278-8b4c-4f99-a696-8facf19f0e56",
    )
    file_name: str = Field(
        ..., description="Filename of the artifact", example="main.py"
    )
    relative_path: Optional[str] = Field(
        None,
        description=("Relative path of the artifact in the agent's workspace"),
        example="python/code/",
    )
```

The `Artifact` class defines the mandatory and optional attributes and provides corresponding descriptions along with example values.

## Functionality and Usage

The `Artifact` class encapsulates the information and attributes representing an artifact. It provides a structured and organized way to manage artifacts within a given context.

### Example 1: Creating an Artifact instance

To create an instance of the `Artifact` class, you can simply initialize it with the required attributes. Here's an example:

```python
from swarms.structs import Artifact

artifact_instance = Artifact(
    artifact_id="b225e278-8b4c-4f99-a696-8facf19f0e56",
    file_name="main.py",
    relative_path="python/code/",
)
```

In this example, we create an instance of the `Artifact` class with the specified artifact details.

### Example 2: Accessing Artifact attributes

You can access the attributes of the `Artifact` instance using dot notation. Here's how you can access the file name of the artifact:

```python
print(artifact_instance.file_name)
# Output: "main.py"
```

### Example 3: Handling optional attributes

If the `relative_path` attribute is not provided during artifact creation, it will default to `None`. Here's an example:

```python
artifact_instance_no_path = Artifact(
    artifact_id="c280s347-9b7d-3c68-m337-7abvf50j23k", file_name="script.js"
)

print(artifact_instance_no_path.relative_path)
# Output: None
```

By providing default values for optional attributes, the `Artifact` class allows flexibility in defining artifact instances.

### Additional Information and Tips

The `Artifact` class represents a powerful and flexible means of handling various artifacts with different attributes. By utilizing this class, users can organize, manage, and streamline their artifacts with ease.

## References and Resources

For further details and references related to the swarms.structs library and the `Artifact` class, refer to the [official documentation](https://swarms.structs.docs/artifact.html).

This comprehensive documentation provides an in-depth understanding of the `Artifact` class, its attributes, functionality, and usage examples. By following the detailed examples and explanations, developers can effectively leverage the capabilities of the `Artifact` class within their projects.


--------------------------------------------------

# File: swarms/structs/auto_agent_builder.md

# Agent Builder

The Agent Builder is a powerful class that automatically builds and manages swarms of AI agents. It provides a flexible and extensible framework for creating, coordinating, and executing multiple AI agents working together to accomplish complex tasks.

## Overview

The Agent Builder uses a boss agent to delegate work and create new specialized agents as needed. It's designed to be production-ready with robust error handling, logging, and configuration options.

## Architecture

```mermaid
graph TD
    A[Agent Builder] --> B[Configuration]
    A --> C[Agent Creation]
    A --> D[Task Execution]
    
    B --> B1[Name]
    B --> B2[Description]
    B --> B3[Model Settings]
    
    C --> C1[Agent Pool]
    C --> C2[Agent Registry]
    C --> C3[Agent Configuration]
    
    D --> D1[Task Distribution]
    D --> D2[Result Collection]
    D --> D3[Error Handling]
    
    C1 --> E[Specialized Agents]
    C2 --> E
    C3 --> E
    
    E --> F[Task Execution]
    F --> G[Results]
```

## Class Structure

### AgentsBuilder Class

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| name | str | "swarm-creator-01" | The name of the swarm |
| description | str | "This is a swarm that creates swarms" | A description of the swarm's purpose |
| verbose | bool | True | Whether to output detailed logs |
| max_loops | int | 1 | Maximum number of execution loops |
| model_name | str | "gpt-4o" | The model to use for agent creation |
| return_dictionary | bool | True | Whether to return results as a dictionary |
| system_prompt | str | BOSS_SYSTEM_PROMPT | The system prompt for the boss agent |

### Methods

| Method | Description | Parameters | Returns |
|--------|-------------|------------|---------|
| run | Run the swarm on a given task | task: str, image_url: str = None, *args, **kwargs | Tuple[List[Agent], int] |
| _create_agents | Create necessary agents for a task | task: str, *args, **kwargs | List[Agent] |
| build_agent | Build a single agent with specifications | agent_name: str, agent_description: str, agent_system_prompt: str, max_loops: int = 1, model_name: str = "gpt-4o", dynamic_temperature_enabled: bool = True, auto_generate_prompt: bool = False, role: str = "worker", max_tokens: int = 8192, temperature: float = 0.5 | Agent |

## Enterprise Use Cases

### 1. Customer Service Automation
- Create specialized agents for different aspects of customer service

- Handle ticket routing, response generation, and escalation

- Maintain consistent service quality across channels

### 2. Data Analysis Pipeline
- Build agents for data collection, cleaning, analysis, and visualization

- Automate complex data processing workflows

- Generate insights and reports automatically

### 3. Content Creation and Management
- Deploy agents for content research, writing, editing, and publishing

- Maintain brand consistency across content

- Automate content scheduling and distribution

### 4. Process Automation
- Create agents for workflow automation

- Handle document processing and routing

- Manage approval chains and notifications

### 5. Research and Development
- Build agents for literature review, experiment design, and data collection

- Automate research documentation and reporting

- Facilitate collaboration between research teams

## Example Usage

```python
from swarms import AgentsBuilder

# Initialize the agent builder
agents_builder = AgentsBuilder(
    name="enterprise-automation",
    description="Enterprise workflow automation swarm",
    verbose=True
)

# Define a use-case for building agents
task = "Develop a swarm of agents to automate the generation of personalized marketing strategies based on customer data and market trends"

# Run the swarm
agents = agents_builder.run(task)

# Access results
print(agents)
```

## Best Practices

1. **Error Handling**
   - Always implement proper error handling for agent failures
   - Use retry mechanisms for transient failures
   - Log all errors for debugging and monitoring

2. **Resource Management**
   - Monitor agent resource usage
   - Implement rate limiting for API calls
   - Use connection pooling for database operations

3. **Security**
   - Implement proper authentication and authorization
   - Secure sensitive data and API keys
   - Follow least privilege principle for agent permissions

4. **Monitoring and Logging**
   - Implement comprehensive logging
   - Monitor agent performance metrics
   - Set up alerts for critical failures

5. **Scalability**
   - Design for horizontal scaling
   - Implement load balancing
   - Use distributed systems when needed

## Integration Patterns

```mermaid
graph LR
    A[External System] --> B[API Gateway]
    B --> C[Agent Builder]
    C --> D[Agent Pool]
    D --> E[Specialized Agents]
    E --> F[External Services]
    
    subgraph "Monitoring"
        G[Logs]
        H[Metrics]
        I[Alerts]
    end
    
    C --> G
    C --> H
    C --> I
```

## Performance Considerations

1. **Agent Pool Management**
   - Implement connection pooling
   - Use caching for frequently accessed data
   - Optimize agent creation and destruction

2. **Task Distribution**
   - Implement load balancing
   - Use priority queues for task scheduling
   - Handle task timeouts and retries

3. **Resource Optimization**
   - Monitor memory usage
   - Implement garbage collection
   - Use efficient data structures

## Troubleshooting

Common issues and solutions:

1. **Agent Creation Failures**
   - Check API credentials
   - Verify model availability
   - Review system prompts

2. **Performance Issues**
   - Monitor resource usage
   - Check network latency
   - Review agent configurations

3. **Integration Problems**
   - Verify API endpoints
   - Check authentication
   - Review data formats


--------------------------------------------------

# File: swarms/structs/auto_swarm.md

# AutoSwarm

The `AutoSwarm` class represents a swarm of agents that can be created and managed automatically. This class leverages the `AutoSwarmRouter` to route tasks to appropriate swarms and supports custom preprocessing, routing, and postprocessing of tasks. It is designed to handle complex workflows efficiently.

### Key Concepts

- **Swarm**: A group of agents working together to complete tasks.
- **Routing**: Directing tasks to the appropriate swarm based on specific criteria.
- **Preprocessing and Postprocessing**: Customizable functions to handle tasks before and after routing.
- **Event Loop**: Managing the execution of tasks in a loop.

## Attributes

### Arguments

| Argument            | Type                          | Default   | Description |
|---------------------|-------------------------------|-----------|-------------|
| `name`              | `Optional[str]`               | `None`    | The name of the swarm. |
| `description`       | `Optional[str]`               | `None`    | The description of the swarm. |
| `verbose`           | `bool`                        | `False`   | Whether to enable verbose mode. |
| `custom_params`     | `Optional[Dict[str, Any]]`    | `None`    | Custom parameters for the swarm. |
| `custom_preprocess` | `Optional[Callable]`          | `None`    | Custom preprocessing function for tasks. |
| `custom_postprocess`| `Optional[Callable]`          | `None`    | Custom postprocessing function for task results. |
| `custom_router`     | `Optional[Callable]`          | `None`    | Custom routing function for tasks. |
| `max_loops`         | `int`                         | `1`       | The maximum number of loops to run the workflow. |

### Attributes

| Attribute            | Type                          | Description |
|----------------------|-------------------------------|-------------|
| `name`               | `Optional[str]`               | The name of the swarm. |
| `description`        | `Optional[str]`               | The description of the swarm. |
| `verbose`            | `bool`                        | Whether to enable verbose mode. |
| `custom_params`      | `Optional[Dict[str, Any]]`    | Custom parameters for the swarm. |
| `custom_preprocess`  | `Optional[Callable]`          | Custom preprocessing function for tasks. |
| `custom_postprocess` | `Optional[Callable]`          | Custom postprocessing function for task results. |
| `custom_router`      | `Optional[Callable]`          | Custom routing function for tasks. |
| `max_loops`          | `int`                         | The maximum number of loops to run the workflow. |
| `router`             | `AutoSwarmRouter`             | The router for managing task routing. |

## Methods

### init_logging

Initializes logging for the `AutoSwarm`.

**Examples:**

```python
swarm = AutoSwarm(name="example_swarm", verbose=True)
swarm.init_logging()
```

### run

Runs the swarm simulation.

**Arguments:**

| Parameter | Type    | Default | Description |
|-----------|---------|---------|-------------|
| `task`    | `str`   | `None`  | The task to be executed. |
| `*args`   |         |         | Additional arguments. |
| `**kwargs`|         |         | Additional keyword arguments. |

**Returns:**

| Return Type | Description |
|-------------|-------------|
| `Any`       | The result of the executed task. |

**Raises:**

- `Exception`: If any error occurs during task execution.

**Examples:**

```python
swarm = AutoSwarm(name="example_swarm", max_loops=3)
result = swarm.run(task="example_task")
print(result)
```

### list_all_swarms

Lists all available swarms and their descriptions.

**Examples:**

```python
swarm = AutoSwarm(name="example_swarm", max_loops=3)
swarm.list_all_swarms()
# Output:
# INFO: Swarm Name: swarm1 || Swarm Description: Description of swarm1
# INFO: Swarm Name: swarm2 || Swarm Description: Description of swarm2
```

### Additional Examples

#### Example 1: Custom Preprocessing and Postprocessing

```python
def custom_preprocess(task, *args, **kwargs):
    # Custom preprocessing logic
    task = task.upper()
    return task, args, kwargs

def custom_postprocess(result):
    # Custom postprocessing logic
    return result.lower()

swarm = AutoSwarm(
    name="example_swarm",
    custom_preprocess=custom_preprocess,
    custom_postprocess=custom_postprocess,
    max_loops=3
)

# Running a task with custom preprocessing and postprocessing
result = swarm.run(task="example_task")
print(result)  # Output will be the processed result
```

#### Example 2: Custom Router Function

```python
def custom_router(swarm, task, *args, **kwargs):
    # Custom routing logic
    if "specific" in task:
        return swarm.router.swarm_dict["specific_swarm"].run(task, *args, **kwargs)
    return swarm.router.swarm_dict["default_swarm"].run(task, *args, **kwargs)

swarm = AutoSwarm(
    name="example_swarm",
    custom_router=custom_router,
    max_loops=3
)

# Running a task with custom routing
result = swarm.run(task="specific_task")
print(result)  # Output will be the result of the routed task
```

#### Example 3: Verbose Mode

```python
swarm = AutoSwarm(
    name="example_swarm",
    verbose=True,
    max_loops=3
)

# Running a task with verbose mode enabled
result = swarm.run(task="example_task")
# Output will include detailed logs of the task execution process
```


#### Full Example 4:
First create a class with BaseSwarm -> Then wrap it in the router -> then pass that to the `AutoSwarm`

```python
from swarms import BaseSwarm, AutoSwarmRouter, AutoSwarm


class FinancialReportSummarization(BaseSwarm):
    def __init__(self, name: str = None, *args, **kwargs):
        super().__init__()

    def run(self, task, *args, **kwargs):
        return task


# Add swarm to router
router = AutoSwarmRouter(swarms=[FinancialReportSummarization])

# Create AutoSwarm Instance
autoswarm = AutoSwarm(
    name="kyegomez/FinancialReportSummarization",
    description="A swarm for financial document summarizing and generation",
    verbose=True,
    router=router,
)

# Run the AutoSwarm
autoswarm.run("Analyze these documents and give me a summary:")
```

## Summary

The `AutoSwarm` class provides a robust framework for managing and executing tasks using a swarm of agents. With customizable preprocessing, routing, and postprocessing functions, it is highly adaptable to various workflows and can handle complex task execution scenarios efficiently. The integration with `AutoSwarmRouter` enhances its flexibility, making it a powerful tool for dynamic task management.

--------------------------------------------------

# File: swarms/structs/auto_swarm_builder.md

# AutoSwarmBuilder Documentation

The `AutoSwarmBuilder` is a powerful class that automatically builds and manages swarms of AI agents to accomplish complex tasks. It uses a boss agent to delegate work and create specialized agents as needed.

## Overview

The AutoSwarmBuilder is designed to:

- Automatically create and coordinate multiple AI agents

- Delegate tasks to specialized agents

- Manage communication between agents

- Handle complex workflows through a swarm router


## Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| name | str | None | The name of the swarm |
| description | str | None | A description of the swarm's purpose |
| verbose | bool | True | Whether to output detailed logs |
| max_loops | int | 1 | Maximum number of execution loops |
| random_models | bool | True | Whether to use random models for agents |

## Core Methods

### run(task: str, *args, **kwargs)

Executes the swarm on a given task.

**Parameters:**

- `task` (str): The task to execute

- `*args`: Additional positional arguments

- `**kwargs`: Additional keyword arguments

**Returns:**

- The result of the swarm execution

### create_agents(task: str)

Creates specialized agents for a given task.

**Parameters:**

- `task` (str): The task to create agents for

**Returns:**

- List[Agent]: List of created agents

### build_agent(agent_name: str, agent_description: str, agent_system_prompt: str)
Builds a single agent with specified parameters.

**Parameters:**
- `agent_name` (str): Name of the agent

- `agent_description` (str): Description of the agent

- `agent_system_prompt` (str): System prompt for the agent


**Returns:**

- Agent: The constructed agent

### batch_run(tasks: List[str])

Executes the swarm on multiple tasks.

**Parameters:**

- `tasks` (List[str]): List of tasks to execute

**Returns:**

- List[Any]: Results from each task execution

## Examples

### Example 1: Content Creation Swarm

```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder

# Initialize the swarm builder
swarm = AutoSwarmBuilder(
    name="Content Creation Swarm",
    description="A swarm specialized in creating high-quality content"
)

# Run the swarm on a content creation task
result = swarm.run(
    "Create a comprehensive blog post about artificial intelligence in healthcare, "
    "including current applications, future trends, and ethical considerations."
)
```

### Example 2: Data Analysis Swarm

```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder

# Initialize the swarm builder
swarm = AutoSwarmBuilder(
    name="Data Analysis Swarm",
    description="A swarm specialized in data analysis and visualization"
)

# Run the swarm on a data analysis task
result = swarm.run(
    "Analyze the provided sales data and create a detailed report with visualizations "
    "showing trends, patterns, and recommendations for improvement."
)
```

### Example 3: Batch Processing Multiple Tasks

```python
from swarms.structs.auto_swarm_builder import AutoSwarmBuilder

# Initialize the swarm builder
swarm = AutoSwarmBuilder(
    name="Multi-Task Swarm",
    description="A swarm capable of handling multiple diverse tasks"
)

# Define multiple tasks
tasks = [
    "Create a marketing strategy for a new product launch",
    "Analyze customer feedback and generate improvement suggestions",
    "Develop a project timeline for the next quarter"
]

# Run the swarm on all tasks
results = swarm.batch_run(tasks)
```

## Best Practices

!!! tip "Task Definition"
    - Provide clear, specific task descriptions
    
    - Include any relevant context or constraints
    
    - Specify expected output format if needed

!!! note "Configuration"
    
    - Set appropriate `max_loops` based on task complexity
    
    - Use `verbose=True` during development for debugging
    
    - Consider using `random_models=True` for diverse agent capabilities

!!! warning "Error Handling"
    - The class includes comprehensive error handling
    
    - All methods include try-catch blocks with detailed logging
    
    - Errors are propagated with full stack traces for debugging

## Notes

!!! info "Architecture"
    
    - The AutoSwarmBuilder uses a sophisticated boss agent system to coordinate tasks
    
    - Agents are created dynamically based on task requirements
    
    - The system includes built-in logging and error handling
    
    - Results are returned in a structured format for easy processing


--------------------------------------------------

# File: swarms/structs/auto_swarm_router.md

# AutoSwarmRouter

The `AutoSwarmRouter` class is designed to route tasks to the appropriate swarm based on the provided name. This class allows for customization of preprocessing, routing, and postprocessing of tasks, making it highly adaptable to various workflows and requirements.

### Key Concepts

- **Routing**: Directing tasks to the appropriate swarm based on specific criteria.
- **Preprocessing and Postprocessing**: Customizable functions to handle tasks before and after routing.
- **Swarms**: Collections of `BaseSwarm` objects that perform the tasks.

## Attributes

### Arguments

| Argument           | Type                             | Default   | Description |
|--------------------|----------------------------------|-----------|-------------|
| `name`             | `Optional[str]`                  | `None`    | The name of the router. |
| `description`      | `Optional[str]`                  | `None`    | The description of the router. |
| `verbose`          | `bool`                           | `False`   | Whether to enable verbose mode. |
| `custom_params`    | `Optional[Dict[str, Any]]`       | `None`    | Custom parameters for the router. |
| `swarms`           | `Sequence[BaseSwarm]`            | `None`    | A list of `BaseSwarm` objects. |
| `custom_preprocess`| `Optional[Callable]`             | `None`    | Custom preprocessing function for tasks. |
| `custom_postprocess`| `Optional[Callable]`            | `None`    | Custom postprocessing function for task results. |
| `custom_router`    | `Optional[Callable]`             | `None`    | Custom routing function for tasks. |

### Attributes

| Attribute            | Type                             | Description |
|----------------------|----------------------------------|-------------|
| `name`               | `Optional[str]`                  | The name of the router. |
| `description`        | `Optional[str]`                  | The description of the router. |
| `verbose`            | `bool`                           | Whether to enable verbose mode. |
| `custom_params`      | `Optional[Dict[str, Any]]`       | Custom parameters for the router. |
| `swarms`             | `Sequence[BaseSwarm]`            | A list of `BaseSwarm` objects. |
| `custom_preprocess`  | `Optional[Callable]`             | Custom preprocessing function for tasks. |
| `custom_postprocess` | `Optional[Callable]`             | Custom postprocessing function for task results. |
| `custom_router`      | `Optional[Callable]`             | Custom routing function for tasks. |
| `swarm_dict`         | `Dict[str, BaseSwarm]`           | A dictionary of swarms keyed by their name. |

## Methods

### run

Executes the swarm simulation and routes the task to the appropriate swarm.

**Arguments:**

| Parameter | Type    | Default | Description |
|-----------|---------|---------|-------------|
| `task`    | `str`   | `None`  | The task to be executed. |
| `*args`   |         |         | Additional arguments. |
| `**kwargs`|         |         | Additional keyword arguments. |

**Returns:**

| Return Type | Description |
|-------------|-------------|
| `Any`       | The result of the routed task. |

**Raises:**

- `ValueError`: If the specified swarm is not found.
- `Exception`: If any error occurs during task routing or execution.

**Examples:**

```python
router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2])

# Running a task
result = router.run(task="example_task")
```

### len_of_swarms

Prints the number of swarms available in the router.

**Examples:**

```python
router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2])

# Printing the number of swarms
router.len_of_swarms()  # Output: 2
```

### list_available_swarms

Logs the available swarms and their descriptions.

**Examples:**

```python
router = AutoSwarmRouter(name="example_router", swarms=[swarm1, swarm2])

# Listing available swarms
router.list_available_swarms()
# Output:
# INFO: Swarm Name: swarm1 || Swarm Description: Description of swarm1
# INFO: Swarm Name: swarm2 || Swarm Description: Description of swarm2
```

### Additional Examples

#### Example 1: Custom Preprocessing and Postprocessing

```python
def custom_preprocess(task, *args, **kwargs):
    # Custom preprocessing logic
    task = task.upper()
    return task, args, kwargs

def custom_postprocess(result):
    # Custom postprocessing logic
    return result.lower()

router = AutoSwarmRouter(
    name="example_router",
    swarms=[swarm1, swarm2],
    custom_preprocess=custom_preprocess,
    custom_postprocess=custom_postprocess
)

# Running a task with custom preprocessing and postprocessing
result = router.run(task="example_task")
print(result)  # Output will be the processed result
```

#### Example 2: Custom Router Function

```python
def custom_router(router, task, *args, **kwargs):
    # Custom routing logic
    if "specific" in task:
        return router.swarm_dict["specific_swarm"].run(task, *args, **kwargs)
    return router.swarm_dict["default_swarm"].run(task, *args, **kwargs)

router = AutoSwarmRouter(
    name="example_router",
    swarms=[default_swarm, specific_swarm],
    custom_router=custom_router
)

# Running a task with custom routing
result = router.run(task="specific_task")
print(result)  # Output will be the result of the routed task
```

#### Example 3: Verbose Mode

```python
router = AutoSwarmRouter(
    name="example_router",
    swarms=[swarm1, swarm2],
    verbose=True
)

# Running a task with verbose mode enabled
result = router.run(task="example_task")
# Output will include detailed logs of the task routing and execution process
```

## Summary

The `AutoSwarmRouter` class provides a flexible and customizable approach to routing tasks to appropriate swarms, supporting custom preprocessing, routing, and postprocessing functions. This makes it a powerful tool for managing complex workflows that require dynamic task handling and execution.

--------------------------------------------------

# File: swarms/structs/basestructure.md

# Module/Function Name: BaseStructure

## Introduction:

The `BaseStructure` module contains the basic structure and attributes required for running machine learning models and associated metadata, error logging, artifact saving/loading, and relevant event logging. 

The module provides the flexibility to save and load the model metadata, log errors, save artifacts, and maintain a log for multiple events associated with multiple threads and batched operations. The key attributes of the module include **name**, **description**, **save_metadata_path**, and **save_error_path**.

## Class Definition:

### Arguments:
| Argument             | Type   | Description                                                          |
|----------------------|--------|----------------------------------------------------------------------|
| name                 | str    | (Optional) The name of the structure.                                |
| description          | str    | (Optional) A description of the structure.                           |
| save_metadata        | bool   | A boolean flag to enable or disable metadata saving.                 |
| save_artifact_path   | str    | (Optional) The path to save artifacts.                               |
| save_metadata_path   | str    | (Optional) The path to save metadata.                                |
| save_error_path      | str    | (Optional) The path to save errors.                                  |

## Methods:

### 1. run
Runs the structure.

### 2. save_to_file
Saves data to a file.
* **data**: Value to be saved.
* **file_path**: Path where the data is to be saved.

### 3. load_from_file
Loads data from a file.
* **file_path**: Path from where the data is to be loaded.

### 4. save_metadata
Saves metadata to a file.
* **metadata**: Data to be saved as metadata.

### 5. load_metadata
Loads metadata from a file.

### 6. log_error
Logs error to a file.

### 7. save_artifact
Saves artifact to a file.
* **artifact**: The artifact to be saved.
* **artifact_name**: Name of the artifact.

### 8. load_artifact
Loads artifact from a file.
* **artifact_name**: Name of the artifact.

### 9. log_event
Logs an event to a file.
* **event**: The event to be logged.
* **event_type**: Type of the event (optional, defaults to "INFO").

### 10. run_async
Runs the structure asynchronously.

### 11. save_metadata_async
Saves metadata to a file asynchronously.

### 12. load_metadata_async
Loads metadata from a file asynchronously.

### 13. log_error_async
Logs error to a file asynchronously.

### 14. save_artifact_async
Saves artifact to a file asynchronously.

### 15. load_artifact_async
Loads artifact from a file asynchronously.

### 16. log_event_async
Logs an event to a file asynchronously.

### 17. asave_to_file
Saves data to a file asynchronously.

### 18. aload_from_file
Loads data from a file asynchronously.

### 19. run_concurrent
Runs the structure concurrently.

### 20. compress_data
Compresses data.

### 21. decompres_data
Decompresses data.

### 22. run_batched
Runs batched data. 

## Examples:

### Example 1: Saving Metadata
```python
base_structure = BaseStructure(name="ExampleStructure")
metadata = {"key1": "value1", "key2": "value2"}
base_structure.save_metadata(metadata)
```

### Example 2: Loading Artifact
```python
artifact_name = "example_artifact"
artifact_data = base_structure.load_artifact(artifact_name)
```

### Example 3: Running Concurrently
```python
concurrent_data = [data1, data2, data3]
results = base_structure.run_concurrent(batched_data=concurrent_data)
```

## Note:

The `BaseStructure` class is designed to provide a modular and extensible structure for managing metadata, logs, errors, and batched operations while running machine learning models. The class's methods offer asynchronous and concurrent execution capabilities, thus optimizing the performance of the associated applications and models. The module's attributes and methods cater to a wide range of use cases, making it an essential foundational component for machine learning and data-based applications.

# Conclusion:

The `BaseStructure` module offers a robust and flexible foundation for managing machine learning model metadata, error logs, and event tracking, including asynchronous, concurrent, and batched operations. By leveraging the inherent capabilities of this class, developers can enhance the reliability, scalability, and performance of machine learning-based applications.

## References:

- [Python Concurrent Programming with `asyncio`](https://docs.python.org/3/library/asyncio.html)
- [Understanding Thread Pool Executor in Python](https://docs.python.org/3/library/concurrent.futures.html#executor-objects)
- [Documentation on `gzip` Module for Data Compression](https://docs.python.org/3/library/gzip.html)

---

The above documentation provides detailed information about the `BaseStructure` module, including its functionality, attributes, methods, usage examples, and references to relevant resources for further exploration. This comprehensive documentation aims to deepen the users' understanding of the module's purpose and how it can be effectively utilized in practice.

Please let me know if you need further elaboration on any specific aspect or functionality of the `BaseStructure` module.


--------------------------------------------------

# File: swarms/structs/concurrentworkflow.md

# ConcurrentWorkflow Documentation

## Overview

The `ConcurrentWorkflow` class is designed to facilitate the concurrent execution of multiple agents, each tasked with solving a specific query or problem. This class is particularly useful in scenarios where multiple agents need to work in parallel, allowing for efficient resource utilization and faster completion of tasks. The workflow manages the execution, collects metadata, and optionally saves the results in a structured format.

### Key Features

- **Concurrent Execution**: Runs multiple agents simultaneously using Python's `ThreadPoolExecutor`
- **Interactive Mode**: Supports interactive task modification and execution
- **Caching System**: Implements LRU caching for repeated prompts
- **Progress Tracking**: Optional progress bar for task execution
- **Enhanced Error Handling**: Implements retry mechanism with exponential backoff
- **Input Validation**: Validates task inputs before execution
- **Batch Processing**: Supports running tasks in batches
- **Metadata Collection**: Gathers detailed metadata about each agent's execution
- **Customizable Output**: Allows saving metadata to file or returning as string/dictionary

## Class Definition

### Attributes

| Attribute              | Type                    | Description                                               |
|------------------------|-------------------------|-----------------------------------------------------------|
| `name`                 | `str`                   | The name of the workflow. Defaults to `"ConcurrentWorkflow"`. |
| `description`          | `str`                   | A brief description of the workflow.                      |
| `agents`               | `List[Agent]`           | A list of agents to be executed concurrently.             |
| `metadata_output_path` | `str`                   | Path to save the metadata output. Defaults to `"agent_metadata.json"`. |
| `auto_save`            | `bool`                  | Flag indicating whether to automatically save the metadata. |
| `output_type`          | `str`                   | The type of output format. Defaults to `"dict"`.          |
| `max_loops`            | `int`                   | Maximum number of loops for each agent. Defaults to `1`.  |
| `return_str_on`        | `bool`                  | Flag to return output as string. Defaults to `False`.     |
| `auto_generate_prompts`| `bool`                  | Flag indicating whether to auto-generate prompts for agents. |
| `return_entire_history`| `bool`                  | Flag to return entire conversation history. Defaults to `False`. |
| `interactive`          | `bool`                  | Flag indicating whether to enable interactive mode. Defaults to `False`. |
| `cache_size`           | `int`                   | The size of the cache. Defaults to `100`.                 |
| `max_retries`          | `int`                   | The maximum number of retry attempts. Defaults to `3`.    |
| `retry_delay`          | `float`                 | The delay between retry attempts in seconds. Defaults to `1.0`. |
| `show_progress`        | `bool`                  | Flag indicating whether to show progress. Defaults to `False`. |
| `_cache`               | `dict`                  | The cache for storing agent outputs.                      |
| `_progress_bar`        | `tqdm`                  | The progress bar for tracking execution.                  |

## Methods

### ConcurrentWorkflow.\_\_init\_\_

Initializes the `ConcurrentWorkflow` class with the provided parameters.

#### Parameters

| Parameter             | Type           | Default Value                          | Description                                               |
|-----------------------|----------------|----------------------------------------|-----------------------------------------------------------|
| `name`                | `str`          | `"ConcurrentWorkflow"`                 | The name of the workflow.                                 |
| `description`         | `str`          | `"Execution of multiple agents concurrently"` | A brief description of the workflow.               |
| `agents`              | `List[Agent]`  | `[]`                                   | A list of agents to be executed concurrently.             |
| `metadata_output_path`| `str`          | `"agent_metadata.json"`                | Path to save the metadata output.                         |
| `auto_save`           | `bool`         | `True`                                 | Flag indicating whether to automatically save the metadata. |
| `output_type`         | `str`          | `"dict"`                               | The type of output format.                                |
| `max_loops`           | `int`          | `1`                                    | Maximum number of loops for each agent.                   |
| `return_str_on`       | `bool`         | `False`                                | Flag to return output as string.                          |
| `auto_generate_prompts`| `bool`        | `False`                                | Flag indicating whether to auto-generate prompts for agents. |
| `return_entire_history`| `bool`        | `False`                                | Flag to return entire conversation history.               |
| `interactive`         | `bool`         | `False`                                | Flag indicating whether to enable interactive mode.        |
| `cache_size`          | `int`          | `100`                                  | The size of the cache.                                    |
| `max_retries`         | `int`          | `3`                                    | The maximum number of retry attempts.                     |
| `retry_delay`         | `float`        | `1.0`                                  | The delay between retry attempts in seconds.              |
| `show_progress`       | `bool`         | `False`                                | Flag indicating whether to show progress.                 |

#### Raises

- `ValueError`: If the list of agents is empty or if the description is empty.

### ConcurrentWorkflow.disable_agent_prints

Disables print statements for all agents in the workflow.

```python
workflow.disable_agent_prints()
```

### ConcurrentWorkflow.activate_auto_prompt_engineering

Activates the auto-generate prompts feature for all agents in the workflow.

```python
workflow.activate_auto_prompt_engineering()
```

### ConcurrentWorkflow.enable_progress_bar

Enables the progress bar display for task execution.

```python
workflow.enable_progress_bar()
```

### ConcurrentWorkflow.disable_progress_bar

Disables the progress bar display.

```python
workflow.disable_progress_bar()
```

### ConcurrentWorkflow.clear_cache

Clears the task cache.

```python
workflow.clear_cache()
```

### ConcurrentWorkflow.get_cache_stats

Gets cache statistics.

#### Returns

- `Dict[str, int]`: A dictionary containing cache statistics.

```python
stats = workflow.get_cache_stats()
print(stats)  # {'cache_size': 5, 'max_cache_size': 100}
```

### ConcurrentWorkflow.run

Executes the workflow for the provided task.

#### Parameters

| Parameter   | Type                | Description                                               |
|-------------|---------------------|-----------------------------------------------------------|
| `task`      | `Optional[str]`     | The task or query to give to all agents.                  |
| `img`       | `Optional[str]`     | The image to be processed by the agents.                  |
| `*args`     | `tuple`             | Additional positional arguments.                          |
| `**kwargs`  | `dict`              | Additional keyword arguments.                             |

#### Returns

- `Any`: The result of the execution, format depends on output_type and return_entire_history settings.

#### Raises

- `ValueError`: If an invalid device is specified.
- `Exception`: If any other error occurs during execution.

### ConcurrentWorkflow.run_batched

Runs the workflow for a batch of tasks.

#### Parameters

| Parameter   | Type         | Description                                               |
|-------------|--------------|-----------------------------------------------------------|
| `tasks`     | `List[str]`  | A list of tasks or queries to give to all agents.         |

#### Returns

- `List[Any]`: A list of results for each task.

## Usage Examples

### Example 1: Basic Usage with Interactive Mode

```python
from swarms import Agent, ConcurrentWorkflow

# Initialize agents
agents = [
    Agent(
        agent_name=f"Agent-{i}",
        system_prompt="You are a helpful assistant.",
        model_name="gpt-4",
        max_loops=1,
    )
    for i in range(3)
]

# Initialize workflow with interactive mode
workflow = ConcurrentWorkflow(
    name="Interactive Workflow",
    agents=agents,
    interactive=True,
    show_progress=True,
    cache_size=100,
    max_retries=3,
    retry_delay=1.0
)

# Run workflow
task = "What are the benefits of using Python for data analysis?"
result = workflow.run(task)
print(result)
```

### Example 2: Batch Processing with Progress Bar

```python
# Initialize workflow
workflow = ConcurrentWorkflow(
    name="Batch Processing Workflow",
    agents=agents,
    show_progress=True,
    auto_save=True
)

# Define tasks
tasks = [
    "Analyze the impact of climate change on agriculture",
    "Evaluate renewable energy solutions",
    "Assess water conservation strategies"
]

# Run batch processing
results = workflow.run_batched(tasks)

# Process results
for task, result in zip(tasks, results):
    print(f"Task: {task}")
    print(f"Result: {result}\n")
```

### Example 3: Error Handling and Retries

```python
import logging

# Set up logging
logging.basicConfig(level=logging.INFO)

# Initialize workflow with retry settings
workflow = ConcurrentWorkflow(
    name="Reliable Workflow",
    agents=agents,
    max_retries=3,
    retry_delay=1.0,
    show_progress=True
)

# Run workflow with error handling
try:
    task = "Generate a comprehensive market analysis report"
    result = workflow.run(task)
    print(result)
except Exception as e:
    logging.error(f"An error occurred: {str(e)}")
```

## Tips and Best Practices

- **Agent Initialization**: Ensure all agents are correctly initialized with required configurations.
- **Interactive Mode**: Use interactive mode for tasks requiring user input or modification.
- **Caching**: Utilize the caching system for repeated tasks to improve performance.
- **Progress Tracking**: Enable progress bar for long-running tasks to monitor execution.
- **Error Handling**: Implement proper error handling and use retry mechanism for reliability.
- **Resource Management**: Monitor cache size and clear when necessary.
- **Batch Processing**: Use batch processing for multiple related tasks.
- **Logging**: Implement detailed logging for debugging and monitoring.

## References and Resources

- [Python's ThreadPoolExecutor Documentation](https://docs.python.org/3/library/concurrent.futures.html#concurrent.futures.ThreadPoolExecutor)
- [tqdm Progress Bar Documentation](https://tqdm.github.io/)
- [Python's functools.lru_cache Documentation](https://docs.python.org/3/library/functools.html#functools.lru_cache)
- [Loguru for Logging in Python](https://loguru.readthedocs.io/en/stable/)

--------------------------------------------------

# File: swarms/structs/conversation.md

# Module/Class Name: Conversation

## Introduction

The `Conversation` class is a powerful and flexible tool for managing conversational data in Python applications. It provides a comprehensive solution for storing, retrieving, and analyzing conversations with support for multiple storage backends, token tracking, and advanced metadata management.

### Key Features

| Feature Category            | Features / Description                                                                                      |
|----------------------------|-------------------------------------------------------------------------------------------------------------|
| **Multiple Storage Backends** | - In-memory: Fast, temporary storage for testing and development<br>- Supabase: PostgreSQL-based cloud storage with real-time capabilities<br>- Redis: High-performance caching and persistence<br>- SQLite: Local file-based storage<br>- DuckDB: Analytical workloads and columnar storage<br>- Pulsar: Event streaming for distributed systems<br>- Mem0: Memory-based storage with mem0 integration |
| **Token Management**        | - Built-in token counting with configurable models<br>- Automatic token tracking for input/output messages<br>- Token usage analytics and reporting<br>- Context length management |
| **Metadata and Categories** | - Support for message metadata<br>- Message categorization (input/output)<br>- Role-based message tracking<br>- Custom message IDs |
| **Data Export/Import**      | - JSON and YAML export formats<br>- Automatic saving and loading<br>- Conversation history management<br>- Batch operations support |
| **Advanced Features**       | - Message search and filtering<br>- Conversation analytics<br>- Multi-agent support<br>- Error handling and fallbacks<br>- Type hints and validation |

### Use Cases

| Use Case                   | Features / Description                                                                                  |
|----------------------------|--------------------------------------------------------------------------------------------------------|
| **Chatbot Development**    | - Store and manage conversation history<br>- Track token usage and context length<br>- Analyze conversation patterns |
| **Multi-Agent Systems**    | - Coordinate multiple AI agents<br>- Track agent interactions<br>- Store agent outputs and metadata    |
| **Analytics Applications** | - Track conversation metrics<br>- Generate usage reports<br>- Analyze user interactions                |
| **Production Systems**     | - Persistent storage with various backends<br>- Error handling and recovery<br>- Scalable conversation management |
| **Development and Testing**| - Fast in-memory storage<br>- Debugging support<br>- Easy export/import of test data                   |

### Best Practices

| Category            | Best Practices                                                                                                         |
|---------------------|------------------------------------------------------------------------------------------------------------------------|
| **Storage Selection** | - Use in-memory for testing and development<br>- Choose Supabase for multi-user cloud applications<br>- Use Redis for high-performance requirements<br>- Select SQLite for single-user local applications<br>- Pick DuckDB for analytical workloads<br>- Opt for Pulsar in distributed systems |
| **Token Management** | - Enable token counting for production use<br>- Set appropriate context lengths<br>- Monitor token usage with `export_and_count_categories()` |
| **Error Handling**   | - Implement proper fallback mechanisms<br>- Use type hints for better code reliability<br>- Monitor and log errors appropriately |
| **Data Management**  | - Use appropriate export formats (JSON/YAML)<br>- Implement regular backup strategies<br>- Clean up old conversations when needed |
| **Security**         | - Use environment variables for sensitive credentials<br>- Implement proper access controls<br>- Validate input data    |

## Table of Contents

1. [Class Definition](#1-class-definition)
2. [Initialization Parameters](#2-initialization-parameters)
3. [Backend Configuration](#3-backend-configuration)
4. [Methods](#4-methods)
5. [Examples](#5-examples)

## 1. Class Definition

### Overview

The `Conversation` class is designed to manage conversations by keeping track of messages and their attributes. It offers methods for adding, deleting, updating, querying, and displaying messages within the conversation. Additionally, it supports exporting and importing conversations, searching for specific keywords, and more.

**New in this version**: The class now supports multiple storage backends for persistent conversation storage:

| Backend      | Description                                                                                                 | Requirements                      |
|--------------|-------------------------------------------------------------------------------------------------------------|------------------------------------|
| **in-memory**| Default memory-based storage (no persistence)                                                               | None (built-in)                    |
| **mem0**     | Memory-based storage with mem0 integration                                                                  | `pip install mem0ai`               |
| **supabase** | PostgreSQL-based storage using Supabase                                                                     | `pip install supabase`             |
| **redis**    | Redis-based storage                                                                                         | `pip install redis`                |
| **sqlite**   | SQLite-based storage (local file)                                                                           | None (built-in)                    |
| **duckdb**   | DuckDB-based storage (analytical workloads, columnar storage)                                               | `pip install duckdb`               |
| **pulsar**   | Apache Pulsar messaging backend                                                                             | `pip install pulsar-client`        |

All backends use **lazy loading** - database dependencies are only imported when the specific backend is instantiated. Each backend provides helpful error messages if required packages are not installed.

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| id | str | Unique identifier for the conversation |
| name | str | Name of the conversation |
| system_prompt | Optional[str] | System prompt for the conversation |
| time_enabled | bool | Flag to enable time tracking for messages |
| autosave | bool | Flag to enable automatic saving |
| save_filepath | str | File path for saving conversation history |
| load_filepath | str | File path for loading conversation history |
| conversation_history | list | List storing conversation messages |
| tokenizer | Callable | Tokenizer for counting tokens |
| context_length | int | Maximum tokens allowed in conversation |
| rules | str | Rules for the conversation |
| custom_rules_prompt | str | Custom prompt for rules |
| user | str | User identifier for messages |
| save_as_yaml | bool | Flag to save as YAML |
| save_as_json_bool | bool | Flag to save as JSON |
| token_count | bool | Flag to enable token counting |
| message_id_on | bool | Flag to enable message IDs |
| backend | str | Storage backend type |
| backend_instance | Any | The actual backend instance |
| conversations_dir | str | Directory to store conversations |

## 2. Initialization Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| id | str | generated | Unique conversation ID |
| name | str | "conversation-test" | Name of the conversation |
| system_prompt | Optional[str] | None | System prompt for the conversation |
| time_enabled | bool | False | Enable time tracking |
| autosave | bool | False | Enable automatic saving |
| save_filepath | str | None | File path for saving |
| load_filepath | str | None | File path for loading |
| context_length | int | 8192 | Maximum tokens allowed |
| rules | str | None | Conversation rules |
| custom_rules_prompt | str | None | Custom rules prompt |
| user | str | "User" | User identifier |
| save_as_yaml_on | bool | False | Save as YAML |
| save_as_json_bool | bool | False | Save as JSON |
| token_count | bool | False | Enable token counting |
| message_id_on | bool | False | Enable message IDs |
| provider | Literal["mem0", "in-memory"] | "in-memory" | Legacy storage provider |
| backend | Optional[str] | None | Storage backend (takes precedence over provider) |
| tokenizer_model_name | str | "gpt-4.1" | Model name for tokenization |
| conversations_dir | Optional[str] | None | Directory for conversations |
| export_method | str | "json" | Export format ("json" or "yaml") |

### Backend-Specific Parameters

#### Supabase Backend
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| supabase_url | Optional[str] | None | Supabase project URL |
| supabase_key | Optional[str] | None | Supabase API key |
| table_name | str | "conversations" | Database table name |

Environment variables: `SUPABASE_URL`, `SUPABASE_ANON_KEY`

#### Redis Backend
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| redis_host | str | "localhost" | Redis server host |
| redis_port | int | 6379 | Redis server port |
| redis_db | int | 0 | Redis database number |
| redis_password | Optional[str] | None | Redis password |
| use_embedded_redis | bool | True | Use embedded Redis |
| persist_redis | bool | True | Enable Redis persistence |
| auto_persist | bool | True | Auto-persist data |
| redis_data_dir | Optional[str] | None | Redis data directory |

#### SQLite/DuckDB Backend
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| db_path | Optional[str] | None | Database file path |

#### Pulsar Backend
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| pulsar_url | str | "pulsar://localhost:6650" | Pulsar server URL |
| topic | str | f"conversation-{id}" | Pulsar topic name |

### Backend Selection

The `backend` parameter takes precedence over the legacy `provider` parameter:

```python
# Legacy way (still supported)
conversation = Conversation(provider="in-memory")

# New way (recommended)
conversation = Conversation(backend="supabase")
conversation = Conversation(backend="redis")
conversation = Conversation(backend="sqlite")
```

## 4. Methods

### `add(role: str, content: Union[str, dict, list], metadata: Optional[dict] = None)`

Adds a message to the conversation history.

| Parameter | Type | Description |
|-----------|------|-------------|
| role | str | Role of the speaker |
| content | Union[str, dict, list] | Message content |
| metadata | Optional[dict] | Additional metadata |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello, how are you?")
conversation.add("assistant", "I'm doing well, thank you!")
```

### `add_multiple_messages(roles: List[str], contents: List[Union[str, dict, list]])`

Adds multiple messages to the conversation history.

| Parameter | Type | Description |
|-----------|------|-------------|
| roles | List[str] | List of speaker roles |
| contents | List[Union[str, dict, list]] | List of message contents |

Example:
```python
conversation = Conversation()
conversation.add_multiple_messages(
    ["user", "assistant"],
    ["Hello!", "Hi there!"]
)
```

### `delete(index: str)`

Deletes a message from the conversation history.

| Parameter | Type | Description |
|-----------|------|-------------|
| index | str | Index of message to delete |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.delete(0)  # Deletes the first message
```

### `update(index: str, role: str, content: Union[str, dict])`

Updates a message in the conversation history.

| Parameter | Type | Description |
|-----------|------|-------------|
| index | str | Index of message to update |
| role | str | New role of speaker |
| content | Union[str, dict] | New message content |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.update(0, "user", "Hi there!")
```

### `query(index: str)`

Retrieves a message from the conversation history.

| Parameter | Type | Description |
|-----------|------|-------------|
| index | str | Index of message to query |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
message = conversation.query(0)
```

### `search(keyword: str)`

Searches for messages containing a keyword.

| Parameter | Type | Description |
|-----------|------|-------------|
| keyword | str | Keyword to search for |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello world")
results = conversation.search("world")
```

### `display_conversation(detailed: bool = False)`

Displays the conversation history.

| Parameter | Type | Description |
|-----------|------|-------------|
| detailed | bool | Show detailed information |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.display_conversation(detailed=True)
```

### `export_conversation(filename: str)`

Exports conversation history to a file.

| Parameter | Type | Description |
|-----------|------|-------------|
| filename | str | Output file path |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.export_conversation("chat.txt")
```

### `import_conversation(filename: str)`

Imports conversation history from a file.

| Parameter | Type | Description |
|-----------|------|-------------|
| filename | str | Input file path |

Example:
```python
conversation = Conversation()
conversation.import_conversation("chat.txt")
```

### `count_messages_by_role()`

Counts messages by role.

Returns: Dict[str, int]

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.add("assistant", "Hi")
counts = conversation.count_messages_by_role()
```

### `return_history_as_string()`

Returns conversation history as a string.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
history = conversation.return_history_as_string()
```

### `save_as_json(filename: str)`

Saves conversation history as JSON.

| Parameter | Type | Description |
|-----------|------|-------------|
| filename | str | Output JSON file path |

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.save_as_json("chat.json")
```

### `load_from_json(filename: str)`

Loads conversation history from JSON.

| Parameter | Type | Description |
|-----------|------|-------------|
| filename | str | Input JSON file path |

Example:
```python
conversation = Conversation()
conversation.load_from_json("chat.json")
```

### `truncate_memory_with_tokenizer()`

Truncates conversation history based on token limit.

Example:
```python
conversation = Conversation(tokenizer=some_tokenizer)
conversation.truncate_memory_with_tokenizer()
```

### `clear()`

Clears the conversation history.

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.clear()
```

### `to_json()`

Converts conversation history to JSON string.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
json_str = conversation.to_json()
```

### `to_dict()`

Converts conversation history to dictionary.

Returns: list

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
dict_data = conversation.to_dict()
```

### `to_yaml()`

Converts conversation history to YAML string.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
yaml_str = conversation.to_yaml()
```

### `get_visible_messages(agent: "Agent", turn: int)`

Gets visible messages for an agent at a specific turn.

| Parameter | Type | Description |
|-----------|------|-------------|
| agent | Agent | The agent |
| turn | int | Turn number |

Returns: List[Dict]

Example:
```python
conversation = Conversation()
visible_msgs = conversation.get_visible_messages(agent, 1)
```

### `get_last_message_as_string()`

Gets the last message as a string.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
last_msg = conversation.get_last_message_as_string()
```

### `return_messages_as_list()`

Returns messages as a list of strings.

Returns: List[str]

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
messages = conversation.return_messages_as_list()
```

### `return_messages_as_dictionary()`

Returns messages as a list of dictionaries.

Returns: List[Dict]

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
messages = conversation.return_messages_as_dictionary()
```

### `add_tool_output_to_agent(role: str, tool_output: dict)`

Adds tool output to conversation.

| Parameter | Type | Description |
|-----------|------|-------------|
| role | str | Role of the tool |
| tool_output | dict | Tool output to add |

Example:
```python
conversation = Conversation()
conversation.add_tool_output_to_agent("tool", {"result": "success"})
```

### `return_json()`

Returns conversation as JSON string.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
json_str = conversation.return_json()
```

### `get_final_message()`

Gets the final message.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
final_msg = conversation.get_final_message()
```

### `get_final_message_content()`

Gets content of final message.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
content = conversation.get_final_message_content()
```

### `return_all_except_first()`

Returns all messages except first.

Returns: List[Dict]

Example:
```python
conversation = Conversation()
conversation.add("system", "Start")
conversation.add("user", "Hello")
messages = conversation.return_all_except_first()
```

### `return_all_except_first_string()`

Returns all messages except first as string.

Returns: str

Example:
```python
conversation = Conversation()
conversation.add("system", "Start")
conversation.add("user", "Hello")
messages = conversation.return_all_except_first_string()
```

### `batch_add(messages: List[dict])`

Adds multiple messages in batch.

| Parameter | Type | Description |
|-----------|------|-------------|
| messages | List[dict] | List of messages to add |

Example:
```python
conversation = Conversation()
conversation.batch_add([
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi"}
])
```

### `get_cache_stats()`

Gets cache usage statistics.

Returns: Dict[str, int]

Example:
```python
conversation = Conversation()
stats = conversation.get_cache_stats()
```

### `load_conversation(name: str, conversations_dir: Optional[str] = None)`

Loads a conversation from cache.

| Parameter | Type | Description |
|-----------|------|-------------|
| name | str | Name of conversation |
| conversations_dir | Optional[str] | Directory containing conversations |

Returns: Conversation

Example:
```python
conversation = Conversation.load_conversation("my_chat")
```

### `list_cached_conversations(conversations_dir: Optional[str] = None)`

Lists all cached conversations.

| Parameter | Type | Description |
|-----------|------|-------------|
| conversations_dir | Optional[str] | Directory containing conversations |

Returns: List[str]

Example:
```python
conversations = Conversation.list_cached_conversations()
```

### `clear_memory()`

Clears the conversation memory.

Example:
```python
conversation = Conversation()
conversation.add("user", "Hello")
conversation.clear_memory()
```

## 5. Examples

### Basic Usage with Modern Configuration

```python
from swarms.structs import Conversation

# Create a new conversation with modern configuration
conversation = Conversation(
    name="my_chat",
    system_prompt="You are a helpful assistant",
    time_enabled=True,
    token_count=True,
    tokenizer_model_name="gpt-4.1",
    message_id_on=True,
    export_method="json",
    autosave=True
)

# Add messages with metadata and categories
conversation.add(
    role="user", 
    content="Hello!",
    metadata={"session_id": "123"},
    category="input"
)

conversation.add(
    role="assistant", 
    content="Hi there!",
    metadata={"response_time": "0.5s"},
    category="output"
)

# Get token usage statistics
token_stats = conversation.export_and_count_categories()
print(f"Input tokens: {token_stats['input_tokens']}")
print(f"Output tokens: {token_stats['output_tokens']}")
print(f"Total tokens: {token_stats['total_tokens']}")

# Display conversation
conversation.display_conversation()
```

### Using Supabase Backend with Environment Variables

```python
import os
from swarms.structs import Conversation

# Using environment variables for secure configuration
os.environ["SUPABASE_URL"] = "https://your-project.supabase.co"
os.environ["SUPABASE_ANON_KEY"] = "your-anon-key"

conversation = Conversation(
    name="supabase_chat",
    backend="supabase",
    system_prompt="You are a helpful assistant",
    time_enabled=True,
    token_count=True,
    message_id_on=True,
    table_name="production_conversations"  # Custom table name
)

# Messages are automatically persisted to Supabase
conversation.add("user", "Hello!", metadata={"client_id": "user123"})
conversation.add("assistant", "Hi there!", metadata={"model": "gpt-4"})

# Search functionality works with backend
results = conversation.search("Hello")
```

### Redis Backend with Advanced Configuration

```python
from swarms.structs import Conversation

# Redis with advanced configuration and persistence
conversation = Conversation(
    name="redis_chat",
    backend="redis",
    redis_host="localhost",
    redis_port=6379,
    redis_password="secure_password",
    use_embedded_redis=False,  # Use external Redis
    persist_redis=True,
    auto_persist=True,
    redis_data_dir="/path/to/redis/data",
    token_count=True
)

# Add structured messages
conversation.add(
    role="user",
    content={
        "message": "Process this data",
        "data": {"key": "value"}
    }
)

# Batch add multiple messages
conversation.batch_add([
    {"role": "assistant", "content": "Processing..."},
    {"role": "system", "content": "Data processed successfully"}
])
```

### SQLite Backend with Custom Path and Export

```python
from swarms.structs import Conversation
import os

# SQLite with custom database path and YAML export
conversation = Conversation(
    name="sqlite_chat",
    backend="sqlite",
    db_path=os.path.expanduser("~/conversations.db"),
    export_method="yaml",
    system_prompt="You are a helpful assistant",
    token_count=True
)

# Add messages and export
conversation.add("user", "Hello SQLite!")
conversation.add("assistant", "Hello from SQLite backend!")

# Export conversation to YAML
conversation.export(force=True)  # force=True overrides autosave setting
```

### Advanced Usage with Multi-Agent Systems

```python
from swarms.structs import Agent, Conversation
from swarms.structs.multi_agent_exec import run_agents_concurrently
import os

# Set up conversation with DuckDB backend for analytics
conversation = Conversation(
    name="multi_agent_analytics",
    backend="duckdb",
    db_path="analytics.duckdb",
    system_prompt="Multi-agent analytics session",
    time_enabled=True,
    token_count=True,
    message_id_on=True
)

# Create specialized agents
data_analyst = Agent(
    agent_name="DataAnalyst",
    system_prompt="You are a senior data analyst...",
    model_name="gpt-4.1",
    max_loops=1
)

researcher = Agent(
    agent_name="ResearchSpecialist", 
    system_prompt="You are a research specialist...",
    model_name="gpt-4.1",
    max_loops=1
)

# Run agents with structured metadata
task = "Analyze the current state of AI in healthcare"
results = run_agents_concurrently(
    agents=[data_analyst, researcher], 
    task=task
)

# Store results with metadata
for result, agent in zip(results, [data_analyst, researcher]):
    conversation.add(
        content=result, 
        role=agent.agent_name,
        metadata={
            "agent_type": agent.agent_name,
            "model": agent.model_name,
            "task": task
        }
    )

# Get analytics
token_usage = conversation.export_and_count_categories()
message_counts = conversation.count_messages_by_role()
```

### Error Handling and Fallbacks with Type Hints

```python
from typing import Optional, Dict, Any
from swarms.structs import Conversation

def initialize_conversation(
    name: str,
    backend: str,
    config: Dict[str, Any]
) -> Optional[Conversation]:
    """Initialize conversation with fallback handling."""
    try:
        conversation = Conversation(
            name=name,
            backend=backend,
            **config
        )
        print(f"✅ {backend} backend initialized successfully")
        return conversation
    except ImportError as e:
        print(f"❌ {backend} not available: {e}")
        # Fallback to in-memory with same configuration
        fallback_config = {
            k: v for k, v in config.items() 
            if k not in ['supabase_url', 'supabase_key', 'redis_host']
        }
        conversation = Conversation(
            name=name,
            backend="in-memory",
            **fallback_config
        )
        print("💡 Falling back to in-memory storage")
        return conversation
    except Exception as e:
        print(f"❌ Unexpected error: {e}")
        return None

# Usage
config = {
    "system_prompt": "You are a helpful assistant",
    "time_enabled": True,
    "token_count": True,
    "supabase_url": "https://your-project.supabase.co",
    "supabase_key": "your-key"
}

conversation = initialize_conversation(
    name="fallback_test",
    backend="supabase",
    config=config
)

if conversation:
    conversation.add("user", "Hello!")
```

### Loading and Managing Conversations with Modern Features

```python
from swarms.structs import Conversation
from typing import List, Dict
import os

def manage_conversations(base_dir: str) -> List[Dict[str, str]]:
    """Manage conversations with modern features."""
    
    # List all saved conversations
    conversations = Conversation.list_conversations(
        conversations_dir=base_dir
    )
    
    # Print conversation stats
    for conv in conversations:
        print(f"ID: {conv['id']}")
        print(f"Name: {conv['name']}")
        print(f"Created: {conv['created_at']}")
        print(f"Path: {conv['filepath']}")
        print("---")
    
    # Load specific conversation
    if conversations:
        latest = conversations[0]  # Most recent conversation
        conversation = Conversation.load_conversation(
            name=latest["name"],
            conversations_dir=base_dir,
            load_filepath=latest["filepath"]
        )
        
        # Get conversation statistics
        stats = {
            "messages": len(conversation.conversation_history),
            "roles": conversation.count_messages_by_role(),
            "tokens": conversation.export_and_count_categories()
        }
        
        return stats
    
    return []

# Usage
base_dir = os.path.expanduser("~/conversation_data")
stats = manage_conversations(base_dir)
```

### Backend Comparison and Selection Guide

```python
# In-memory: Fast, no persistence, good for testing
conv_memory = Conversation(
    backend="in-memory",
    token_count=True,
    message_id_on=True
)

# SQLite: Local file-based persistence, good for single-user apps
conv_sqlite = Conversation(
    backend="sqlite",
    db_path="conversations.db",
    token_count=True,
    export_method="json"
)

# Redis: High performance, good for real-time applications
conv_redis = Conversation(
    backend="redis",
    redis_host="localhost",
    persist_redis=True,
    token_count=True
)

# Supabase: Cloud PostgreSQL, good for multi-user applications
conv_supabase = Conversation(
    backend="supabase", 
    supabase_url=os.getenv("SUPABASE_URL"),
    supabase_key=os.getenv("SUPABASE_ANON_KEY"),
    token_count=True
)

# DuckDB: Analytical workloads, good for data analysis
conv_duckdb = Conversation(
    backend="duckdb",
    db_path="analytics.duckdb",
    token_count=True
)

# Pulsar: Event streaming, good for distributed systems
conv_pulsar = Conversation(
    backend="pulsar",
    token_count=True
)
```

## Error Handling

The conversation class provides graceful error handling:

- **Missing Dependencies**: Clear error messages with installation instructions
- **Backend Failures**: Automatic fallback to in-memory storage
- **Network Issues**: Retry logic and connection management
- **Data Corruption**: Validation and recovery mechanisms

Example error message:
```
Backend 'supabase' dependencies not available. Install with: pip install supabase
```

## Migration Guide

### From Provider to Backend

```python
# Old way
conversation = Conversation(provider="in-memory")

# New way (recommended)
conversation = Conversation(backend="in-memory")

# Both work, but backend takes precedence
conversation = Conversation(
    provider="in-memory",  # Ignored
    backend="supabase"     # Used
)
```

## Conclusion

The `Conversation` class provides a comprehensive set of tools for managing conversations in Python applications with full backend flexibility. It supports various storage backends, lazy loading, token counting, caching, and multiple export/import formats. The class is designed to be flexible and extensible, making it suitable for a wide range of use cases from simple chat applications to complex conversational AI systems with persistent storage requirements.

Choose the appropriate backend based on your needs:
- **in-memory**: Development and testing
- **sqlite**: Local applications and small-scale deployments  
- **redis**: Distributed applications requiring high performance
- **supabase**: Cloud applications with real-time requirements
- **duckdb**: Analytics and data science workloads
- **pulsar**: Event-driven architectures and streaming applications


--------------------------------------------------

# File: swarms/structs/council_of_judges.md

# CouncilAsAJudge

The `CouncilAsAJudge` is a sophisticated evaluation system that employs multiple AI agents to assess model responses across various dimensions. It provides comprehensive, multi-dimensional analysis of AI model outputs through parallel evaluation and aggregation.

## Overview

The `CouncilAsAJudge` implements a council of specialized AI agents that evaluate different aspects of a model's response. Each agent focuses on a specific dimension of evaluation, and their findings are aggregated into a comprehensive report.

```mermaid
graph TD
    A[User Query] --> B[Base Agent]
    B --> C[Model Response]
    C --> D[CouncilAsAJudge]
    
    subgraph "Evaluation Dimensions"
        D --> E1[Accuracy Agent]
        D --> E2[Helpfulness Agent]
        D --> E3[Harmlessness Agent]
        D --> E4[Coherence Agent]
        D --> E5[Conciseness Agent]
        D --> E6[Instruction Adherence Agent]
    end
    
    E1 --> F[Evaluation Aggregation]
    E2 --> F
    E3 --> F
    E4 --> F
    E5 --> F
    E6 --> F
    
    F --> G[Comprehensive Report]
    
    style D fill:#f9f,stroke:#333,stroke-width:2px
    style F fill:#bbf,stroke:#333,stroke-width:2px
```

## Key Features

- Parallel evaluation across multiple dimensions
- Caching system for improved performance
- Dynamic model selection
- Comprehensive evaluation metrics
- Thread-safe execution
- Detailed technical analysis

## Installation

```bash
pip install swarms
```

## Basic Usage

```python
from swarms import Agent, CouncilAsAJudge

# Create a base agent
base_agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="You are a financial expert helping users understand and establish ROTH IRAs.",
    model_name="claude-opus-4-20250514",
    max_loops=1,
)

# Run the base agent
user_query = "How can I establish a ROTH IRA to buy stocks and get a tax break?"
model_output = base_agent.run(user_query)

# Create and run the council
panel = CouncilAsAJudge()
results = panel.run(user_query, model_output)
print(results)
```

## Advanced Usage

### Custom Model Configuration

```python
from swarms import CouncilAsAJudge

# Initialize with custom model
council = CouncilAsAJudge(
    model_name="anthropic/claude-3-sonnet-20240229",
    output_type="all",
    cache_size=256,
    max_workers=4,
    random_model_name=False
)
```

### Parallel Processing Configuration

```python
from swarms import CouncilAsAJudge

# Configure parallel processing
council = CouncilAsAJudge(
    max_workers=8,  # Custom number of worker threads
    random_model_name=True  # Enable dynamic model selection
)
```

## Evaluation Dimensions

The council evaluates responses across six key dimensions:

| Dimension | Evaluation Criteria |
|-----------|-------------------|
| **Accuracy** | • Factual correctness<br>• Source credibility<br>• Temporal consistency<br>• Technical accuracy |
| **Helpfulness** | • Problem-solving efficacy<br>• Solution feasibility<br>• Context inclusion<br>• Proactive addressing of follow-ups |
| **Harmlessness** | • Safety assessment<br>• Ethical considerations<br>• Age-appropriateness<br>• Content sensitivity |
| **Coherence** | • Structural integrity<br>• Logical flow<br>• Information hierarchy<br>• Transition effectiveness |
| **Conciseness** | • Communication efficiency<br>• Information density<br>• Redundancy elimination<br>• Focus maintenance |
| **Instruction Adherence** | • Requirement coverage<br>• Constraint compliance<br>• Format matching<br>• Scope appropriateness |

## API Reference

### CouncilAsAJudge

```python
class CouncilAsAJudge:
    def __init__(
        self,
        id: str = swarm_id(),
        name: str = "CouncilAsAJudge",
        description: str = "Evaluates the model's response across multiple dimensions",
        model_name: str = "gpt-4o-mini",
        output_type: str = "all",
        cache_size: int = 128,
        max_workers: int = None,
        random_model_name: bool = True,
    )
```

#### Parameters

- `id` (str): Unique identifier for the council
- `name` (str): Display name of the council
- `description` (str): Description of the council's purpose
- `model_name` (str): Name of the model to use for evaluations
- `output_type` (str): Type of output to return
- `cache_size` (int): Size of the LRU cache for prompts
- `max_workers` (int): Maximum number of worker threads
- `random_model_name` (bool): Whether to use random model selection

### Methods

#### run

```python
def run(self, task: str, model_response: str) -> None
```

Evaluates a model response across all dimensions.

##### Parameters

- `task` (str): Original user prompt
- `model_response` (str): Model's response to evaluate

##### Returns

- Comprehensive evaluation report

## Examples

### Financial Analysis Example

```python
from swarms import Agent, CouncilAsAJudge

# Create financial analysis agent
financial_agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt="You are a financial expert helping users understand and establish ROTH IRAs.",
    model_name="claude-opus-4-20250514",
    max_loops=1,
)

# Run analysis
query = "How can I establish a ROTH IRA to buy stocks and get a tax break?"
response = financial_agent.run(query)

# Evaluate response
council = CouncilAsAJudge()
evaluation = council.run(query, response)
print(evaluation)
```

### Technical Documentation Example

```python
from swarms import Agent, CouncilAsAJudge

# Create documentation agent
doc_agent = Agent(
    agent_name="Documentation-Agent",
    system_prompt="You are a technical documentation expert.",
    model_name="gpt-4",
    max_loops=1,
)

# Generate documentation
query = "Explain how to implement a REST API using FastAPI"
response = doc_agent.run(query)

# Evaluate documentation quality
council = CouncilAsAJudge(
    model_name="anthropic/claude-3-sonnet-20240229",
    output_type="all"
)
evaluation = council.run(query, response)
print(evaluation)
```

## Best Practices

### Model Selection

!!! tip "Model Selection Best Practices"
    - Choose appropriate models for your use case
    - Consider using random model selection for diverse evaluations
    - Match model capabilities to evaluation requirements

### Performance Optimization

!!! note "Performance Tips"
    - Adjust cache size based on memory constraints
    - Configure worker threads based on CPU cores
    - Monitor memory usage with large responses

### Error Handling

!!! warning "Error Handling Guidelines"
    - Implement proper exception handling
    - Monitor evaluation failures
    - Log evaluation results for analysis

### Resource Management

!!! info "Resource Management"
    - Clean up resources after evaluation
    - Monitor thread pool usage
    - Implement proper shutdown procedures

## Troubleshooting

### Memory Issues

!!! danger "Memory Problems"
    If you encounter memory-related problems:

    - Reduce cache size
    - Decrease number of worker threads
    - Process smaller chunks of text

### Performance Problems

!!! warning "Performance Issues"
    To improve performance:

    - Increase cache size
    - Adjust worker thread count
    - Use more efficient models

### Evaluation Failures

!!! danger "Evaluation Issues"
    When evaluations fail:

    - Check model availability
    - Verify input format
    - Monitor error logs

## Contributing

!!! success "Contributing"
    Contributions are welcome! Please feel free to submit a Pull Request.

## License

!!! info "License"
    This project is licensed under the MIT License - see the LICENSE file for details.

--------------------------------------------------

# File: swarms/structs/create_new_swarm.md

# How to Add a New Swarm Class

This guide provides comprehensive step-by-step instructions for developers to create and add a new swarm. It emphasizes the importance of adhering to best practices, using proper type hints, and documenting code thoroughly to ensure maintainability, scalability, and clarity in your implementations.

## Overview

A Swarm class enables developers to manage and coordinate multiple agents working together to accomplish complex tasks efficiently. Each Swarm must:

- Contain a `run(task: str, img: str, *args, **kwargs)` method, which serves as the primary execution method for tasks.
- Include `name`, `description`, and `agents` parameters.
- Ensure `agents` is a list of callables, with each callable adhering to specific requirements for dynamic agent behavior.
- Follow type-hinting and documentation best practices to maintain code clarity and reliability.

Each Agent within the swarm must:

- Contain `agent_name`, `system_prompt`, and a `run` method.
- Follow similar type hinting and documentation standards to ensure consistency and readability.

By adhering to these requirements, you can create robust, reusable, and modular swarms that streamline task management and enhance collaborative functionality. Developers are also encouraged to contribute their swarms back to the open-source community by submitting a pull request to the Swarms repository at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms).

---

## Creating a Swarm Class

Below is a detailed template for creating a Swarm class. Ensure that all elements are documented and clearly defined:

```python
from typing import Callable, Any, List

class MySwarm:
    """
    A custom swarm class to manage and execute tasks with multiple agents.

    Attributes:
        name (str): The name of the swarm.
        description (str): A brief description of the swarm's purpose.
        agents (List[Callable]): A list of callables representing the agents to be utilized.
    """

    def __init__(self, name: str, description: str, agents: List[Callable]):
        """
        Initialize the Swarm with its name, description, and agents.

        Args:
            name (str): The name of the swarm.
            description (str): A description of the swarm.
            agents (List[Callable]): A list of callables that provide the agents for the swarm.
        """
        self.name = name
        self.description = description
        self.agents = agents

    def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any:
        """
        Execute a task using the swarm and its agents.

        Args:
            task (str): The task description.
            img (str): The image input.
            *args: Additional positional arguments for customization.
            **kwargs: Additional keyword arguments for fine-tuning behavior.

        Returns:
            Any: The result of the task execution, aggregated from all agents.
        """
        results = []
        for agent in self.agents:
            result = agent.run(task, img, *args, **kwargs)
            results.append(result)
        return results
```

This Swarm class serves as the main orchestrator for coordinating agents and running tasks dynamically and flexibly.

---

## Creating an Agent Class

Each agent must follow a well-defined structure to ensure compatibility with the swarm. Below is an example of an agent class:

```python
class Agent:
    """
    A single agent class to handle specific tasks assigned by the swarm.

    Attributes:
        agent_name (str): The name of the agent.
        system_prompt (str): The system prompt guiding the agent's behavior and purpose.
    """

    def __init__(self, agent_name: str, system_prompt: str):
        """
        Initialize the agent with its name and system prompt.

        Args:
            agent_name (str): The name of the agent.
            system_prompt (str): The guiding prompt for the agent.
        """
        self.agent_name = agent_name
        self.system_prompt = system_prompt

    def run(self, task: str, img: str, *args: Any, **kwargs: Any) -> Any:
        """
        Execute a specific task assigned to the agent.

        Args:
            task (str): The task description.
            img (str): The image input for processing.
            *args: Additional positional arguments for task details.
            **kwargs: Additional keyword arguments for extended functionality.

        Returns:
            Any: The result of the task execution, which can be customized.
        """
        # Example implementation (to be customized by developer)
        return f"Agent {self.agent_name} executed task: {task}"
```

This structure ensures that each agent can independently handle tasks and integrate seamlessly into a swarm.

---

## Adding Your Swarm to a Project

### Step 1: Define Your Agents
Create one or more instances of the `Agent` class to serve as components of your swarm. For example:

```python
def create_agents():
    return [
        Agent(agent_name="Agent1", system_prompt="Analyze the image and summarize results."),
        Agent(agent_name="Agent2", system_prompt="Detect objects and highlight key features."),
    ]
```

### Step 2: Implement Your Swarm
Create an instance of your Swarm class, defining its name, description, and associated agents:

```python
my_swarm = MySwarm(
    name="Image Analysis Swarm",
    description="A swarm designed to analyze images and perform a range of related tasks.",
    agents=create_agents()
)
```

### Step 3: Execute Tasks
Call the `run` method of your swarm, passing in the required parameters for execution:

```python
results = my_swarm.run(task="Analyze image content", img="path/to/image.jpg")
print(results)
```

This simple flow allows you to dynamically utilize agents for diverse operations and ensures efficient task execution.

---

## Best Practices

To ensure your swarm implementation is efficient and maintainable, follow these best practices:

1. **Type Annotations:**
   Use precise type hints for parameters and return types to improve code readability and support static analysis tools.

2. **Comprehensive Documentation:**
   Include clear and detailed docstrings for all classes, methods, and attributes to ensure your code is understandable.

3. **Thorough Testing:**
   Test your swarm and agents with various tasks to verify correctness and identify potential edge cases.

4. **Modular Design:**
   Keep your swarm and agent logic modular, enabling reuse and easy extensions for future enhancements.

5. **Error Handling:**
   Implement robust error handling in the `run` methods to gracefully manage unexpected inputs or issues during execution.

6. **Code Review:**
   Regularly review and refactor your code to align with the latest best practices and maintain high quality.

7. **Scalability:**
   Design your swarm with scalability in mind, ensuring it can handle a large number of agents and complex tasks.

8. **Logging and Monitoring:**
   Include comprehensive logging to track task execution and monitor performance, enabling easier debugging and optimization.

9. **Open-Source Contributions:**
   Consider contributing your swarm to the Swarms repository to benefit the community. Submit a pull request at [https://github.com/kyegomez/swarms](https://github.com/kyegomez/swarms).

---

## Example Output

Given the implementation above, executing a task might produce output such as:

```plaintext
[
    "Agent Agent1 executed task: Analyze image content",
    "Agent Agent2 executed task: Analyze image content"
]
```

The modular design ensures that each agent contributes to the overall functionality of the swarm, allowing seamless scalability and dynamic task management.

---

## Conclusion

By following these guidelines, you can create swarms that are powerful, flexible, and maintainable. Leveraging the provided templates and best practices enables you to build efficient multi-agent systems capable of handling diverse and complex tasks. Proper structuring, thorough testing, and adherence to best practices will ensure your swarm integrates effectively into any project, delivering robust and reliable performance. Furthermore, maintaining clear documentation and emphasizing modularity will help your implementation adapt to future needs and use cases. Empower your projects with a well-designed swarm architecture today, and consider submitting your swarm to the open-source community to foster collaboration and innovation.



--------------------------------------------------

# File: swarms/structs/cron_job.md

# CronJob

A wrapper class that turns any callable (including Swarms agents) into a scheduled cron job. This class provides functionality to schedule and run tasks at specified intervals using the schedule library with cron-style scheduling.

## Overview

The CronJob class allows you to:

- Schedule any callable or Swarms Agent to run at specified intervals

- Support for seconds, minutes, and hours intervals

- Run tasks in a separate thread

- Handle graceful start/stop of scheduled jobs

- Manage multiple concurrent scheduled jobs

## Architecture

```mermaid
graph TD
    A[CronJob] --> B[Initialize]
    B --> C[Parse Interval]
    C --> D[Schedule Task]
    D --> E[Run Job]
    E --> F[Execute Task]
    F --> G{Is Agent?}
    G -->|Yes| H[Run Agent]
    G -->|No| I[Run Callable]
    H --> J[Handle Result]
    I --> J
    J --> K[Sleep]
    K --> E
```

## Class Reference

### Constructor

```python
def __init__(
    agent: Optional[Union[Agent, Callable]] = None,
    interval: Optional[str] = None,
    job_id: Optional[str] = None
)
```

| Parameter | Type | Description | Required |
|-----------|------|-------------|-----------|
| agent | Agent or Callable | The Swarms Agent instance or callable to be scheduled | No |
| interval | str | The interval string (e.g., "5seconds", "10minutes", "1hour") | No |
| job_id | str | Unique identifier for the job. If not provided, one will be generated | No |

### Methods

#### run

```python
def run(task: str, **kwargs)
```

| Parameter | Type | Description | Required |
|-----------|------|-------------|-----------|
| task | str | The task string to be executed by the agent | Yes |
| **kwargs | dict | Additional parameters to pass to the agent's run method | No |

#### __call__

```python
def __call__(task: str, **kwargs)
```

| Parameter | Type | Description | Required |
|-----------|------|-------------|-----------|
| task | str | The task string to be executed | Yes |
| **kwargs | dict | Additional parameters to pass to the agent's run method | No |

## Examples

### Basic Usage with Swarms Agent

```python
from swarms import Agent, CronJob
from loguru import logger

# Initialize the agent
agent = Agent(
    agent_name="Quantitative-Trading-Agent",
    agent_description="Advanced quantitative trading and algorithmic analysis agent",
    system_prompt="""You are an expert quantitative trading agent...""",
    max_loops=1,
    model_name="gpt-4.1",
    dynamic_temperature_enabled=True,
    output_type="str-all-except-first",
    streaming_on=True,
    print_on=True,
    telemetry_enable=False,
)

# Create and run a cron job every 10 seconds
logger.info("Starting example cron job")
cron_job = CronJob(agent=agent, interval="10seconds")
cron_job.run(
    task="What are the best top 3 etfs for gold coverage?"
)
```

### Using with a Custom Function

```python
def custom_task(task: str):
    print(f"Executing task: {task}")
    return "Task completed"

# Create a cron job with a custom function
cron_job = CronJob(
    agent=custom_task,
    interval="5minutes",
    job_id="custom_task_job"
)
cron_job.run("Perform analysis")
```


### Cron Jobs With Multi-Agent Structures

You can also run Cron Jobs with multi-agent structures like `SequentialWorkflow`, `ConcurrentWorkflow`, `HiearchicalSwarm`, and other methods. 

- Just initialize the class as the agent parameter in the `CronJob(agent=swarm)`

- Input your arguments into the `.run(task: str)` method


```python
"""
Cryptocurrency Concurrent Multi-Agent Cron Job Example

This example demonstrates how to use ConcurrentWorkflow with CronJob to create
a powerful cryptocurrency tracking system. Each specialized agent analyzes a
specific cryptocurrency concurrently every minute.

Features:
- ConcurrentWorkflow for parallel agent execution
- CronJob scheduling for automated runs every 1 minute
- Each agent specializes in analyzing one specific cryptocurrency
- Real-time data fetching from CoinGecko API
- Concurrent analysis of multiple cryptocurrencies
- Structured output with professional formatting

Architecture:
CronJob -> ConcurrentWorkflow -> [Bitcoin Agent, Ethereum Agent, Solana Agent, etc.] -> Parallel Analysis
"""

from typing import List
from loguru import logger

from swarms import Agent, CronJob, ConcurrentWorkflow
from swarms_tools import coin_gecko_coin_api


def create_crypto_specific_agents() -> List[Agent]:
    """
    Creates agents that each specialize in analyzing a specific cryptocurrency.

    Returns:
        List[Agent]: List of cryptocurrency-specific Agent instances
    """

    # Bitcoin Specialist Agent
    bitcoin_agent = Agent(
        agent_name="Bitcoin-Analyst",
        agent_description="Expert analyst specializing exclusively in Bitcoin (BTC) analysis and market dynamics",
        system_prompt="""You are a Bitcoin specialist and expert analyst. Your expertise includes:

BITCOIN SPECIALIZATION:
- Bitcoin's unique position as digital gold
- Bitcoin halving cycles and their market impact
- Bitcoin mining economics and hash rate analysis
- Lightning Network and Layer 2 developments
- Bitcoin adoption by institutions and countries
- Bitcoin's correlation with traditional markets
- Bitcoin technical analysis and on-chain metrics
- Bitcoin's role as a store of value and hedge against inflation

ANALYSIS FOCUS:
- Analyze ONLY Bitcoin data from the provided dataset
- Focus on Bitcoin-specific metrics and trends
- Consider Bitcoin's unique market dynamics
- Evaluate Bitcoin's dominance and market leadership
- Assess institutional adoption trends
- Monitor on-chain activity and network health

DELIVERABLES:
- Bitcoin-specific analysis and insights
- Price action assessment and predictions
- Market dominance analysis
- Institutional adoption impact
- Technical and fundamental outlook
- Risk factors specific to Bitcoin

Extract Bitcoin data from the provided dataset and provide comprehensive Bitcoin-focused analysis.""",
        model_name="groq/moonshotai/kimi-k2-instruct",
        max_loops=1,
        dynamic_temperature_enabled=True,
        streaming_on=False,
        tools=[coin_gecko_coin_api],
    )

    # Ethereum Specialist Agent
    ethereum_agent = Agent(
        agent_name="Ethereum-Analyst",
        agent_description="Expert analyst specializing exclusively in Ethereum (ETH) analysis and ecosystem development",
        system_prompt="""You are an Ethereum specialist and expert analyst. Your expertise includes:

ETHEREUM SPECIALIZATION:
- Ethereum's smart contract platform and DeFi ecosystem
- Ethereum 2.0 transition and proof-of-stake mechanics
- Gas fees, network usage, and scalability solutions
- Layer 2 solutions (Arbitrum, Optimism, Polygon)
- DeFi protocols and TVL (Total Value Locked) analysis
- NFT markets and Ethereum's role in digital assets
- Developer activity and ecosystem growth
- EIP proposals and network upgrades

ANALYSIS FOCUS:
- Analyze ONLY Ethereum data from the provided dataset
- Focus on Ethereum's platform utility and network effects
- Evaluate DeFi ecosystem health and growth
- Assess Layer 2 adoption and scalability solutions
- Monitor network usage and gas fee trends
- Consider Ethereum's competitive position vs other smart contract platforms

DELIVERABLES:
- Ethereum-specific analysis and insights
- Platform utility and adoption metrics
- DeFi ecosystem impact assessment
- Network health and scalability evaluation
- Competitive positioning analysis
- Technical and fundamental outlook for ETH

Extract Ethereum data from the provided dataset and provide comprehensive Ethereum-focused analysis.""",
        model_name="groq/moonshotai/kimi-k2-instruct",
        max_loops=1,
        dynamic_temperature_enabled=True,
        streaming_on=False,
        tools=[coin_gecko_coin_api],
    )

    # Solana Specialist Agent
    solana_agent = Agent(
        agent_name="Solana-Analyst",
        agent_description="Expert analyst specializing exclusively in Solana (SOL) analysis and ecosystem development",
        system_prompt="""You are a Solana specialist and expert analyst. Your expertise includes:

SOLANA SPECIALIZATION:
- Solana's high-performance blockchain architecture
- Proof-of-History consensus mechanism
- Solana's DeFi ecosystem and DEX platforms (Serum, Raydium)
- NFT marketplaces and creator economy on Solana
- Network outages and reliability concerns
- Developer ecosystem and Rust programming adoption
- Validator economics and network decentralization
- Cross-chain bridges and interoperability

ANALYSIS FOCUS:
- Analyze ONLY Solana data from the provided dataset
- Focus on Solana's performance and scalability advantages
- Evaluate network stability and uptime improvements
- Assess ecosystem growth and developer adoption
- Monitor DeFi and NFT activity on Solana
- Consider Solana's competitive position vs Ethereum

DELIVERABLES:
- Solana-specific analysis and insights
- Network performance and reliability assessment
- Ecosystem growth and adoption metrics
- DeFi and NFT market analysis
- Competitive advantages and challenges
- Technical and fundamental outlook for SOL

Extract Solana data from the provided dataset and provide comprehensive Solana-focused analysis.""",
        model_name="groq/moonshotai/kimi-k2-instruct",
        max_loops=1,
        dynamic_temperature_enabled=True,
        streaming_on=False,
        tools=[coin_gecko_coin_api],
    )

    # Cardano Specialist Agent
    cardano_agent = Agent(
        agent_name="Cardano-Analyst",
        agent_description="Expert analyst specializing exclusively in Cardano (ADA) analysis and research-driven development",
        system_prompt="""You are a Cardano specialist and expert analyst. Your expertise includes:

CARDANO SPECIALIZATION:
- Cardano's research-driven development approach
- Ouroboros proof-of-stake consensus protocol
- Smart contract capabilities via Plutus and Marlowe
- Cardano's three-layer architecture (settlement, computation, control)
- Academic partnerships and peer-reviewed research
- Cardano ecosystem projects and DApp development
- Native tokens and Cardano's UTXO model
- Sustainability and treasury funding mechanisms

ANALYSIS FOCUS:
- Analyze ONLY Cardano data from the provided dataset
- Focus on Cardano's methodical development approach
- Evaluate smart contract adoption and ecosystem growth
- Assess academic partnerships and research contributions
- Monitor native token ecosystem development
- Consider Cardano's long-term roadmap and milestones

DELIVERABLES:
- Cardano-specific analysis and insights
- Development progress and milestone achievements
- Smart contract ecosystem evaluation
- Academic research impact assessment
- Native token and DApp adoption metrics
- Technical and fundamental outlook for ADA

Extract Cardano data from the provided dataset and provide comprehensive Cardano-focused analysis.""",
        model_name="groq/moonshotai/kimi-k2-instruct",
        max_loops=1,
        dynamic_temperature_enabled=True,
        streaming_on=False,
        tools=[coin_gecko_coin_api],
    )

    # Binance Coin Specialist Agent
    bnb_agent = Agent(
        agent_name="BNB-Analyst",
        agent_description="Expert analyst specializing exclusively in BNB analysis and Binance ecosystem dynamics",
        system_prompt="""You are a BNB specialist and expert analyst. Your expertise includes:

BNB SPECIALIZATION:
- BNB's utility within the Binance ecosystem
- Binance Smart Chain (BSC) development and adoption
- BNB token burns and deflationary mechanics
- Binance exchange volume and market leadership
- BSC DeFi ecosystem and yield farming
- Cross-chain bridges and multi-chain strategies
- Regulatory challenges facing Binance globally
- BNB's role in transaction fee discounts and platform benefits

ANALYSIS FOCUS:
- Analyze ONLY BNB data from the provided dataset
- Focus on BNB's utility value and exchange benefits
- Evaluate BSC ecosystem growth and competition with Ethereum
- Assess token burn impact on supply and price
- Monitor Binance platform developments and regulations
- Consider BNB's centralized vs decentralized aspects

DELIVERABLES:
- BNB-specific analysis and insights
- Utility value and ecosystem benefits assessment
- BSC adoption and DeFi growth evaluation
- Token economics and burn mechanism impact
- Regulatory risk and compliance analysis
- Technical and fundamental outlook for BNB

Extract BNB data from the provided dataset and provide comprehensive BNB-focused analysis.""",
        model_name="groq/moonshotai/kimi-k2-instruct",
        max_loops=1,
        dynamic_temperature_enabled=True,
        streaming_on=False,
        tools=[coin_gecko_coin_api],
    )

    # XRP Specialist Agent
    xrp_agent = Agent(
        agent_name="XRP-Analyst",
        agent_description="Expert analyst specializing exclusively in XRP analysis and cross-border payment solutions",
        system_prompt="""You are an XRP specialist and expert analyst. Your expertise includes:

XRP SPECIALIZATION:
- XRP's role in cross-border payments and remittances
- RippleNet adoption by financial institutions
- Central Bank Digital Currency (CBDC) partnerships
- Regulatory landscape and SEC lawsuit implications
- XRP Ledger's consensus mechanism and energy efficiency
- On-Demand Liquidity (ODL) usage and growth
- Competition with SWIFT and traditional payment rails
- Ripple's partnerships with banks and payment providers

ANALYSIS FOCUS:
- Analyze ONLY XRP data from the provided dataset
- Focus on XRP's utility in payments and remittances
- Evaluate RippleNet adoption and institutional partnerships
- Assess regulatory developments and legal clarity
- Monitor ODL usage and transaction volumes
- Consider XRP's competitive position in payments

DELIVERABLES:
- XRP-specific analysis and insights
- Payment utility and adoption assessment
- Regulatory landscape and legal developments
- Institutional partnership impact evaluation
- Cross-border payment market analysis
- Technical and fundamental outlook for XRP

Extract XRP data from the provided dataset and provide comprehensive XRP-focused analysis.""",
        model_name="groq/moonshotai/kimi-k2-instruct",
        max_loops=1,
        dynamic_temperature_enabled=True,
        streaming_on=False,
        tools=[coin_gecko_coin_api],
    )

    return [
        bitcoin_agent,
        ethereum_agent,
        solana_agent,
        cardano_agent,
        bnb_agent,
        xrp_agent,
    ]


def create_crypto_workflow() -> ConcurrentWorkflow:
    """
    Creates a ConcurrentWorkflow with cryptocurrency-specific analysis agents.

    Returns:
        ConcurrentWorkflow: Configured workflow for crypto analysis
    """
    agents = create_crypto_specific_agents()

    workflow = ConcurrentWorkflow(
        name="Crypto-Specific-Analysis-Workflow",
        description="Concurrent execution of cryptocurrency-specific analysis agents",
        agents=agents,
        max_loops=1,
    )

    return workflow


def create_crypto_cron_job() -> CronJob:
    """
    Creates a CronJob that runs cryptocurrency-specific analysis every minute using ConcurrentWorkflow.

    Returns:
        CronJob: Configured cron job for automated crypto analysis
    """
    # Create the concurrent workflow
    workflow = create_crypto_workflow()

    # Create the cron job
    cron_job = CronJob(
        agent=workflow,  # Use the workflow as the agent
        interval="5seconds",  # Run every 1 minute
    )

    return cron_job


def main():
    """
    Main function to run the cryptocurrency-specific concurrent analysis cron job.
    """
    cron_job = create_crypto_cron_job()

    prompt = """
    
    Conduct a comprehensive analysis of your assigned cryptocurrency.
    
    """

    # Start the cron job
    logger.info("🔄 Starting automated analysis loop...")
    logger.info("⏰ Press Ctrl+C to stop the cron job")

    output = cron_job.run(task=prompt)
    print(output)


if __name__ == "__main__":
    main()
```

## Conclusion

The CronJob class provides a powerful way to schedule and automate tasks using Swarms Agents or custom functions. Key benefits include:

- Easy integration with Swarms Agents

- Flexible interval scheduling

- Thread-safe execution

- Graceful error handling

- Simple API for task scheduling

- Support for both agent and callable-based tasks 

--------------------------------------------------

# File: swarms/structs/custom_swarm.md

# Building Custom Swarms: A Comprehensive Guide for Swarm Engineers

## Introduction

As artificial intelligence and machine learning continue to grow in complexity and applicability, building systems that can harness multiple agents to solve complex tasks becomes more critical. Swarm engineering enables AI agents to collaborate and solve problems autonomously in diverse fields such as finance, marketing, operations, and even creative industries.

This comprehensive guide covers how to build a custom swarm system that integrates multiple agents into a cohesive system capable of solving tasks collaboratively. We'll cover everything from basic swarm structure to advanced features like conversation management, logging, error handling, and scalability.

By the end of this guide, you will have a complete understanding of:

- What swarms are and how they can be built

- How to create agents and integrate them into swarms

- How to implement proper conversation management for message storage

- Best practices for error handling, logging, and optimization

- How to make swarms scalable and production-ready


---

## Overview of Swarm Architecture

A **Swarm** refers to a collection of agents that collaborate to solve a problem. Each agent in the swarm performs part of the task, either independently or by communicating with other agents. Swarms are ideal for:

- **Scalability**: You can add or remove agents dynamically based on the task's complexity

- **Flexibility**: Each agent can be designed to specialize in different parts of the problem, offering modularity

- **Autonomy**: Agents in a swarm can operate autonomously, reducing the need for constant supervision

- **Conversation Management**: All interactions are tracked and stored for analysis and continuity


---

## Core Requirements for Swarm Classes

Every Swarm class must adhere to these fundamental requirements:

### Required Methods and Attributes

- **`run(task: str, img: str, *args, **kwargs)` method**: The primary execution method for tasks

- **`name`**: A descriptive name for the swarm

- **`description`**: A clear description of the swarm's purpose

- **`agents`**: A list of callables representing the agents

- **`conversation`**: A conversation structure for message storage and history management


### Required Agent Structure

Each Agent within the swarm must contain:

- **`agent_name`**: Unique identifier for the agent

- **`system_prompt`**: Instructions that guide the agent's behavior

- **`run` method**: Method to execute tasks assigned to the agent


---

## Setting Up the Foundation

### Required Dependencies

```python
from typing import List, Union, Any, Optional, Callable
from loguru import logger
from swarms.structs.base_swarm import BaseSwarm
from swarms.structs.conversation import Conversation
from swarms.structs.agent import Agent
import concurrent.futures
import os
```

### Custom Exception Handling

```python
class SwarmExecutionError(Exception):
    """Custom exception for handling swarm execution errors."""
    pass

class AgentValidationError(Exception):
    """Custom exception for agent validation errors."""
    pass
```

---

## Building the Custom Swarm Class

### Basic Swarm Structure

```python
class CustomSwarm(BaseSwarm):
    """
    A custom swarm class to manage and execute tasks with multiple agents.
    
    This swarm integrates conversation management for tracking all agent interactions,
    provides error handling, and supports both sequential and concurrent execution.

    Attributes:
        name (str): The name of the swarm.
        description (str): A brief description of the swarm's purpose.
        agents (List[Callable]): A list of callables representing the agents.
        conversation (Conversation): Conversation management for message storage.
        max_workers (int): Maximum number of concurrent workers for parallel execution.
        autosave_conversation (bool): Whether to automatically save conversation history.
    """

    def __init__(
        self,
        name: str,
        description: str,
        agents: List[Callable],
        max_workers: int = 4,
        autosave_conversation: bool = True,
        conversation_config: Optional[dict] = None,
    ):
        """
        Initialize the CustomSwarm with its name, description, and agents.

        Args:
            name (str): The name of the swarm.
            description (str): A description of the swarm.
            agents (List[Callable]): A list of callables that provide the agents for the swarm.
            max_workers (int): Maximum number of concurrent workers.
            autosave_conversation (bool): Whether to automatically save conversations.
            conversation_config (dict): Configuration for conversation management.
        """
        super().__init__(name=name, description=description, agents=agents)
        self.name = name
        self.description = description
        self.agents = agents
        self.max_workers = max_workers
        self.autosave_conversation = autosave_conversation
        
        # Initialize conversation management
        # See: https://docs.swarms.world/swarms/structs/conversation/
        conversation_config = conversation_config or {}
        self.conversation = Conversation(
            id=f"swarm_{name}_{int(time.time())}",
            name=f"{name}_conversation",
            autosave=autosave_conversation,
            save_enabled=True,
            time_enabled=True,
            **conversation_config
        )
        
        # Validate agents and log initialization
        self.validate_agents()
        logger.info(f"🚀 CustomSwarm '{self.name}' initialized with {len(self.agents)} agents")
        
        # Add swarm initialization to conversation history
        self.conversation.add(
            role="System",
            content=f"Swarm '{self.name}' initialized with {len(self.agents)} agents: {[getattr(agent, 'agent_name', 'Unknown') for agent in self.agents]}"
        )

    def validate_agents(self):
        """
        Validates that each agent has the required methods and attributes.
        
        Raises:
            AgentValidationError: If any agent fails validation.
        """
        for i, agent in enumerate(self.agents):
            # Check for required run method
            if not hasattr(agent, 'run'):
                raise AgentValidationError(f"Agent at index {i} does not have a 'run' method.")
            
            # Check for agent_name attribute
            if not hasattr(agent, 'agent_name'):
                logger.warning(f"Agent at index {i} does not have 'agent_name' attribute. Using 'Agent_{i}'")
                agent.agent_name = f"Agent_{i}"
            
            logger.info(f"✅ Agent '{agent.agent_name}' validated successfully.")

    def run(self, task: str, img: str = None, *args: Any, **kwargs: Any) -> Any:
        """
        Execute a task using the swarm and its agents with conversation tracking.

        Args:
            task (str): The task description.
            img (str): The image input (optional).
            *args: Additional positional arguments for customization.
            **kwargs: Additional keyword arguments for fine-tuning behavior.

        Returns:
            Any: The result of the task execution, aggregated from all agents.
        """
        logger.info(f"🎯 Running task '{task}' across {len(self.agents)} agents in swarm '{self.name}'")
        
        # Add task to conversation history
        self.conversation.add(
            role="User",
            content=f"Task: {task}" + (f" | Image: {img}" if img else ""),
            category="input"
        )
        
        try:
            # Execute task across all agents
            results = self._execute_agents(task, img, *args, **kwargs)
            
            # Add results to conversation
            self.conversation.add(
                role="Swarm",
                content=f"Task completed successfully. Processed by {len(results)} agents.",
                category="output"
            )
            
            logger.success(f"✅ Task completed successfully by swarm '{self.name}'")
            return results
            
        except Exception as e:
            error_msg = f"❌ Task execution failed in swarm '{self.name}': {str(e)}"
            logger.error(error_msg)
            
            # Add error to conversation
            self.conversation.add(
                role="System",
                content=f"Error: {error_msg}",
                category="error"
            )
            
            raise SwarmExecutionError(error_msg)

    def _execute_agents(self, task: str, img: str = None, *args, **kwargs) -> List[Any]:
        """
        Execute the task across all agents with proper conversation tracking.
        
        Args:
            task (str): The task to execute.
            img (str): Optional image input.
            
        Returns:
            List[Any]: Results from all agents.
        """
        results = []
        
        for agent in self.agents:
            try:
                # Execute agent task
                result = agent.run(task, img, *args, **kwargs)
                results.append(result)
                
                # Add agent response to conversation
                self.conversation.add(
                    role=agent.agent_name,
                    content=result,
                    category="agent_output"
                )
                
                logger.info(f"✅ Agent '{agent.agent_name}' completed task successfully")
                
            except Exception as e:
                error_msg = f"Agent '{agent.agent_name}' failed: {str(e)}"
                logger.error(error_msg)
                
                # Add agent error to conversation
                self.conversation.add(
                    role=agent.agent_name,
                    content=f"Error: {error_msg}",
                    category="agent_error"
                )
                
                # Continue with other agents but log the failure
                results.append(f"FAILED: {error_msg}")
        
        return results
```

### Enhanced Swarm with Concurrent Execution

```python
    def run_concurrent(self, task: str, img: str = None, *args: Any, **kwargs: Any) -> List[Any]:
        """
        Execute a task using concurrent execution for better performance.
        
        Args:
            task (str): The task description.
            img (str): The image input (optional).
            *args: Additional positional arguments.
            **kwargs: Additional keyword arguments.
            
        Returns:
            List[Any]: Results from all agents executed concurrently.
        """
        logger.info(f"🚀 Running task concurrently across {len(self.agents)} agents")
        
        # Add task to conversation
        self.conversation.add(
            role="User",
            content=f"Concurrent Task: {task}" + (f" | Image: {img}" if img else ""),
            category="input"
        )
        
        results = []
        
        with concurrent.futures.ThreadPoolExecutor(max_workers=self.max_workers) as executor:
            # Submit all agent tasks
            future_to_agent = {
                executor.submit(self._run_single_agent, agent, task, img, *args, **kwargs): agent
                for agent in self.agents
            }
            
            # Collect results as they complete
            for future in concurrent.futures.as_completed(future_to_agent):
                agent = future_to_agent[future]
                try:
                    result = future.result()
                    results.append(result)
                    
                    # Add to conversation
                    self.conversation.add(
                        role=agent.agent_name,
                        content=result,
                        category="agent_output"
                    )
                    
                except Exception as e:
                    error_msg = f"Concurrent execution failed for agent '{agent.agent_name}': {str(e)}"
                    logger.error(error_msg)
                    results.append(f"FAILED: {error_msg}")
                    
                    # Add error to conversation
                    self.conversation.add(
                        role=agent.agent_name,
                        content=f"Error: {error_msg}",
                        category="agent_error"
                    )
        
        # Add completion summary
        self.conversation.add(
            role="Swarm",
            content=f"Concurrent task completed. {len(results)} agents processed.",
            category="output"
        )
        
        return results

    def _run_single_agent(self, agent: Callable, task: str, img: str = None, *args, **kwargs) -> Any:
        """
        Execute a single agent with error handling.
        
        Args:
            agent: The agent to execute.
            task (str): The task to execute.
            img (str): Optional image input.
            
        Returns:
            Any: The agent's result.
        """
        try:
            return agent.run(task, img, *args, **kwargs)
        except Exception as e:
            logger.error(f"Agent '{getattr(agent, 'agent_name', 'Unknown')}' execution failed: {str(e)}")
            raise
```

### Advanced Features

```python
    def run_with_retries(self, task: str, img: str = None, retries: int = 3, *args, **kwargs) -> List[Any]:
        """
        Execute a task with retry logic for failed agents.
        
        Args:
            task (str): The task to execute.
            img (str): Optional image input.
            retries (int): Number of retries for failed agents.
            
        Returns:
            List[Any]: Results from all agents with retry attempts.
        """
        logger.info(f"🔄 Running task with {retries} retries per agent")
        
        # Add task to conversation
        self.conversation.add(
            role="User",
            content=f"Task with retries ({retries}): {task}",
            category="input"
        )
        
        results = []
        
        for agent in self.agents:
            attempt = 0
            success = False
            
            while attempt <= retries and not success:
                try:
                    result = agent.run(task, img, *args, **kwargs)
                    results.append(result)
                    success = True
                    
                    # Add successful result to conversation
                    self.conversation.add(
                        role=agent.agent_name,
                        content=result,
                        category="agent_output"
                    )
                    
                    if attempt > 0:
                        logger.success(f"✅ Agent '{agent.agent_name}' succeeded on attempt {attempt + 1}")
                    
                except Exception as e:
                    attempt += 1
                    error_msg = f"Agent '{agent.agent_name}' failed on attempt {attempt}: {str(e)}"
                    logger.warning(error_msg)
                    
                    # Add retry attempt to conversation
                    self.conversation.add(
                        role=agent.agent_name,
                        content=f"Retry attempt {attempt}: {error_msg}",
                        category="agent_retry"
                    )
                    
                    if attempt > retries:
                        final_error = f"Agent '{agent.agent_name}' exhausted all {retries} retries"
                        logger.error(final_error)
                        results.append(f"FAILED: {final_error}")
                        
                        # Add final failure to conversation
                        self.conversation.add(
                            role=agent.agent_name,
                            content=final_error,
                            category="agent_error"
                        )
        
        return results

    def get_conversation_summary(self) -> dict:
        """
        Get a summary of the conversation history and agent performance.
        
        Returns:
            dict: Summary of conversation statistics and agent performance.
        """
        # Get conversation statistics
        message_counts = self.conversation.count_messages_by_role()
        
        # Count categories
        category_counts = {}
        for message in self.conversation.conversation_history:
            category = message.get("category", "uncategorized")
            category_counts[category] = category_counts.get(category, 0) + 1
        
        # Get token counts if available
        token_summary = self.conversation.export_and_count_categories()
        
        return {
            "swarm_name": self.name,
            "total_messages": len(self.conversation.conversation_history),
            "messages_by_role": message_counts,
            "messages_by_category": category_counts,
            "token_summary": token_summary,
            "conversation_id": self.conversation.id,
        }

    def export_conversation(self, filepath: str = None) -> str:
        """
        Export the conversation history to a file.
        
        Args:
            filepath (str): Optional custom filepath for export.
            
        Returns:
            str: The filepath where the conversation was saved.
        """
        if filepath is None:
            filepath = f"conversations/{self.name}_{self.conversation.id}.json"
        
        self.conversation.export_conversation(filepath)
        logger.info(f"📄 Conversation exported to: {filepath}")
        return filepath

    def display_conversation(self, detailed: bool = True):
        """
        Display the conversation history in a formatted way.
        
        Args:
            detailed (bool): Whether to show detailed information.
        """
        logger.info(f"💬 Displaying conversation for swarm: {self.name}")
        self.conversation.display_conversation(detailed=detailed)
```

---

## Creating Agents for Your Swarm

### Basic Agent Structure

```python
class CustomAgent:
    """
    A custom agent class that integrates with the swarm conversation system.
    
    Attributes:
        agent_name (str): The name of the agent.
        system_prompt (str): The system prompt guiding the agent's behavior.
        conversation (Optional[Conversation]): Shared conversation for context.
    """

    def __init__(
        self, 
        agent_name: str, 
        system_prompt: str,
        conversation: Optional[Conversation] = None
    ):
        """
        Initialize the agent with its name and system prompt.

        Args:
            agent_name (str): The name of the agent.
            system_prompt (str): The guiding prompt for the agent.
            conversation (Optional[Conversation]): Shared conversation context.
        """
        self.agent_name = agent_name
        self.system_prompt = system_prompt
        self.conversation = conversation

    def run(self, task: str, img: str = None, *args: Any, **kwargs: Any) -> Any:
        """
        Execute a specific task assigned to the agent.

        Args:
            task (str): The task description.
            img (str): The image input for processing.
            *args: Additional positional arguments.
            **kwargs: Additional keyword arguments.

        Returns:
            Any: The result of the task execution.
        """
        # Add context from shared conversation if available
        context = ""
        if self.conversation:
            context = f"Previous context: {self.conversation.get_last_message_as_string()}\n\n"
        
        # Process the task (implement your custom logic here)
        result = f"Agent {self.agent_name} processed: {context}{task}"
        
        logger.info(f"🤖 Agent '{self.agent_name}' completed task")
        return result
```

### Using Swarms Framework Agents

You can also use the built-in Agent class from the Swarms framework:

```python
from swarms.structs.agent import Agent

def create_financial_agent() -> Agent:
    """Create a financial analysis agent."""
    return Agent(
        agent_name="FinancialAnalyst",
        system_prompt="You are a financial analyst specializing in market analysis and risk assessment.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )

def create_marketing_agent() -> Agent:
    """Create a marketing analysis agent."""
    return Agent(
        agent_name="MarketingSpecialist", 
        system_prompt="You are a marketing specialist focused on campaign analysis and customer insights.",
        model_name="gpt-4o-mini",
        max_loops=1,
    )
```

---

## Complete Implementation Example

### Setting Up Your Swarm

```python
import time
from typing import List

def create_multi_domain_swarm() -> CustomSwarm:
    """
    Create a comprehensive multi-domain analysis swarm.
    
    Returns:
        CustomSwarm: A configured swarm with multiple specialized agents.
    """
    # Create agents
    agents = [
        create_financial_agent(),
        create_marketing_agent(),
        Agent(
            agent_name="OperationsAnalyst",
            system_prompt="You are an operations analyst specializing in process optimization and efficiency.",
            model_name="gpt-4o-mini",
            max_loops=1,
        ),
    ]
    
    # Configure conversation settings
    conversation_config = {
        "backend": "sqlite",  # Use SQLite for persistent storage
        "db_path": f"conversations/swarm_conversations.db",
        "time_enabled": True,
        "token_count": True,
    }
    
    # Create the swarm
    swarm = CustomSwarm(
        name="MultiDomainAnalysisSwarm",
        description="A comprehensive swarm for financial, marketing, and operations analysis",
        agents=agents,
        max_workers=3,
        autosave_conversation=True,
        conversation_config=conversation_config,
    )
    
    return swarm

# Usage example
if __name__ == "__main__":
    # Create and initialize the swarm
    swarm = create_multi_domain_swarm()
    
    # Execute a complex analysis task
    task = """
    Analyze the Q3 2024 performance data for our company:
    - Revenue: $2.5M (up 15% from Q2)
    
    - Customer acquisition: 1,200 new customers
    
    - Marketing spend: $150K
    
    - Operational costs: $800K
    
    
    Provide insights from financial, marketing, and operations perspectives.
    """
    
    # Run the analysis
    results = swarm.run(task)
    
    # Display results
    print("\n" + "="*50)
    print("SWARM ANALYSIS RESULTS")
    print("="*50)
    
    for i, result in enumerate(results):
        agent_name = swarm.agents[i].agent_name
        print(f"\n🤖 {agent_name}:")
        print(f"📊 {result}")
    
    # Get conversation summary
    summary = swarm.get_conversation_summary()
    print(f"\n📈 Conversation Summary:")
    print(f"   Total messages: {summary['total_messages']}")
    print(f"   Total tokens: {summary['token_summary']['total_tokens']}")
    
    # Export conversation for later analysis
    export_path = swarm.export_conversation()
    print(f"💾 Conversation saved to: {export_path}")
```

### Advanced Usage with Concurrent Execution

```python
def run_batch_analysis():
    """Example of running multiple tasks concurrently."""
    swarm = create_multi_domain_swarm()
    
    tasks = [
        "Analyze Q1 financial performance",
        "Evaluate marketing campaign effectiveness", 
        "Review operational efficiency metrics",
        "Assess customer satisfaction trends",
    ]
    
    # Process all tasks concurrently
    all_results = []
    for task in tasks:
        results = swarm.run_concurrent(task)
        all_results.append({"task": task, "results": results})
    
    return all_results
```

---

## Conversation Management Integration

The swarm uses the Swarms framework's [Conversation structure](../conversation/) for comprehensive message storage and management. This provides:

### Key Features

- **Persistent Storage**: Multiple backend options (SQLite, Redis, Supabase, etc.)

- **Message Categorization**: Organize messages by type (input, output, error, etc.)

- **Token Tracking**: Monitor token usage across conversations

- **Export/Import**: Save and load conversation histories

- **Search Capabilities**: Find specific messages or content


### Conversation Configuration Options

```python
conversation_config = {
    # Backend storage options
    "backend": "sqlite",  # or "redis", "supabase", "duckdb", "in-memory"
    
    # File-based storage
    "db_path": "conversations/swarm_data.db",
    
    # Redis configuration (if using Redis backend)
    "redis_host": "localhost",
    "redis_port": 6379,
    
    # Features
    "time_enabled": True,     # Add timestamps to messages
    "token_count": True,      # Track token usage
    "autosave": True,         # Automatically save conversations
    "save_enabled": True,     # Enable saving functionality
}
```

### Accessing Conversation Data

```python
# Get conversation history
history = swarm.conversation.return_history_as_string()

# Search for specific content
financial_messages = swarm.conversation.search("financial")

# Export conversation data
swarm.conversation.export_conversation("analysis_session.json")

# Get conversation statistics
stats = swarm.conversation.count_messages_by_role()
token_usage = swarm.conversation.export_and_count_categories()
```

For complete documentation on conversation management, see the [Conversation Structure Documentation](../conversation/).


---

## Conclusion

Building custom swarms with proper conversation management enables you to create powerful, scalable, and maintainable multi-agent systems. The integration with the Swarms framework's conversation structure provides:

- **Complete audit trail** of all agent interactions

- **Persistent storage** options for different deployment scenarios  

- **Performance monitoring** through token and message tracking

- **Easy debugging** with searchable conversation history

- **Scalable architecture** that grows with your needs


By following the patterns and best practices outlined in this guide, you can create robust swarms that handle complex tasks efficiently while maintaining full visibility into their operations.

### Key Takeaways

1. **Always implement conversation management** for tracking and auditing
2. **Use proper error handling and retries** for production resilience  
3. **Implement monitoring and logging** for observability
4. **Design for scalability** with concurrent execution patterns
5. **Test thoroughly** with unit tests and integration tests
6. **Configure appropriately** for your deployment environment

For more advanced patterns and examples, explore the [Swarms Examples](../../examples/) and consider contributing your custom swarms back to the community by submitting a pull request to the [Swarms repository](https://github.com/kyegomez/swarms).

---

## Additional Resources

- [Conversation Structure Documentation](../conversation/) - Complete guide to conversation management

- [Agent Documentation](../../agents/) - Learn about creating and configuring agents

- [Multi-Agent Architectures](../overview/) - Explore other swarm patterns and architectures

- [Examples Repository](../../examples/) - Real-world swarm implementations

- [Swarms Framework GitHub](https://github.com/kyegomez/swarms) - Source code and contributions


--------------------------------------------------

# File: swarms/structs/diy_your_own_agent.md

# Create your own agent with `Agent` class

The Agent class is a powerful and flexible tool that empowers AI agents to build their own custom agents, tailored to their specific needs.

This comprehensive guide will explore the process of inheriting from the Agent class, enabling agents to create their own custom agent classes. By leveraging the rich features and extensibility of the Agent class, agents can imbue their offspring agents with unique capabilities, specialized toolsets, and tailored decision-making processes.

## Understanding the Agent Class

Before we dive into the intricacies of creating custom agent classes, let's revisit the foundational elements of the Agent class itself. The Agent class is a versatile and feature-rich class designed to streamline the process of building and managing AI agents. It acts as a backbone, connecting language models (LLMs) with various tools, long-term memory, and a wide range of customization options.

### Key Features of the Agent Class

The Agent class offers a plethora of features that can be inherited and extended by custom agent classes. Here are some of the key features that make the Agent class a powerful foundation:

1\. **Language Model Integration**: The Agent class supports seamless integration with popular language models such as LangChain, HuggingFace Transformers, and Autogen, allowing custom agent classes to leverage the power of state-of-the-art language models.

2\. **Tool Integration**: One of the standout features of the Agent class is its ability to integrate with various tools. Custom agent classes can inherit this capability and incorporate specialized tools tailored to their specific use cases.

3\. **Long-Term Memory**: The Agent class provides built-in support for long-term memory, enabling custom agent classes to retain and access information from previous interactions, essential for maintaining context and learning from past experiences.

4\. **Customizable Prompts and Standard Operating Procedures (SOPs)**: The Agent class allows you to define custom prompts and Standard Operating Procedures (SOPs) that guide an agent's behavior and decision-making process. Custom agent classes can inherit and extend these prompts and SOPs to align with their unique objectives and requirements.

5\. **Interactive and Dashboard Modes**: The Agent class supports interactive and dashboard modes, enabling real-time monitoring and interaction with agents. Custom agent classes can inherit these modes, facilitating efficient development, debugging, and user interaction.

6\. **Autosave and State Management**: With the Agent class, agents can easily save and load their state, including configuration, memory, and history. Custom agent classes can inherit this capability, ensuring seamless task continuation and enabling efficient collaboration among team members.

7\. **Response Filtering**: The Agent class provides built-in response filtering capabilities, allowing agents to filter out or replace specific words or phrases in their responses. Custom agent classes can inherit and extend this feature to ensure compliance with content moderation policies or specific guidelines.

8\. **Code Execution and Multimodal Support**: The Agent class supports code execution and multimodal input/output, enabling agents to process and generate code, as well as handle various data formats such as images, audio, and video. Custom agent classes can inherit and specialize these capabilities for their unique use cases.

9\. **Extensibility and Customization**: The Agent class is designed to be highly extensible and customizable, allowing agents to tailor its behavior, add custom functionality, and integrate with external libraries and APIs. Custom agent classes can leverage this extensibility to introduce specialized features and capabilities.

### Creating a Custom Agent Class

Now that we have a solid understanding of the Agent class and its features, let's dive into the process of creating a custom agent class by inheriting from the Agent class. Throughout this process, we'll explore how agents can leverage and extend the existing functionality, while introducing specialized features and capabilities tailored to their unique requirements.

#### Step 1: Inherit from the Agent Class

The first step in creating a custom agent class is to inherit from the Agent class. This will provide your custom agent class with the foundational features and capabilities of the Agent class, which can then be extended and customized as needed. The new agent class must have a `run(task: str)` method to run the entire agent. It is encouraged to have `step(task: str)` method that completes one step of the agent and then build the `run(task: str)` method.

```python

from swarms import Agent

class MyCustomAgent(Agent):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        # Add custom initialization logic here

    def run(self, task: str) -> 
        ...

```

In the example above, we define a new class `MyCustomAgent` that inherits from the `Agent` class. Within the `__init__` method, we call the parent class's `__init__` method using `super().__init__(*args, **kwargs)`, which ensures that the parent class's initialization logic is executed. You can then add any custom initialization logic specific to your custom agent class.

#### Step 2: Customize the Agent's Behavior

One of the key advantages of inheriting from the Agent class is the ability to customize the agent's behavior according to your specific requirements. This can be achieved by overriding or extending the existing methods, or by introducing new methods altogether.

```python
from swarms import Agent


class MyCustomAgent(Agent):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        # Custom initialization logic

    def custom_method(self, *args, **kwargs):

        # Implement custom logic here

        pass

    def run(self, task, *args, **kwargs):

        # Customize the run method

        response = super().run(task, *args, **kwargs)

        # Additional custom logic

        return response

```

In the example above, we introduce a new `custom_method` that can encapsulate any specialized logic or functionality specific to your custom agent class. Additionally, we override the `run` method, which is responsible for executing the agent's main task loop. Within the overridden `run` method, you can call the parent class's `run` method using `super().run(task, *args, **kwargs)` and then introduce any additional custom logic before or after the parent method's execution.

#### Step 3: Extend Memory Management

The Agent class provides built-in support for long-term memory, allowing agents to retain and access information from previous interactions. Custom agent classes can inherit and extend this capability by introducing specialized memory management techniques.

```python

from swarms_memory import BaseVectorDatabase
from swarms import Agent


class CustomMemory(BaseVectorDatabase):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        # Custom memory initialization logic

    def query(self, *args, **kwargs):

        # Custom memory query logic

        return result

class MyCustomAgent(Agent):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        # Custom initialization logic

        self.long_term_memory = CustomMemory()

    def run(self, task, *args, **kwargs):

        # Customize the run method

        response = super().run(task, *args, **kwargs)

        # Utilize custom memory

        memory_result = self.long_term_memory.query(*args, **kwargs)

        # Process memory result

        return response

```

In the example above, we define a new `CustomMemory` class that inherits from the `BaseVectorDatabase` class provided by the Agent class framework. Within the `CustomMemory` class, you can implement specialized memory management logic, such as custom indexing, retrieval, and storage mechanisms.

Next, within the `MyCustomAgent` class, we initialize an instance of the `CustomMemory` class and assign it to the `self.long_term_memory` attribute. This custom memory instance can then be utilized within the overridden `run` method, where you can query the memory and process the results as needed.

## Step 5: Introduce Custom Prompts and Standard Operating Procedures (SOPs)

The Agent class allows you to define custom prompts and Standard Operating Procedures (SOPs) that guide an agent's behavior and decision-making process. Custom agent classes can inherit and extend these prompts and SOPs to align with their unique objectives and requirements.

```python
from swarms import Agent


class MyCustomAgent(Agent):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        # Custom initialization logic

        self.custom_sop = "Custom SOP for MyCustomAgent..."

        self.custom_prompt = "Custom prompt for MyCustomAgent..."

    def run(self, task, *args, **kwargs):

        # Customize the run method

        response = super().run(task, *args, **kwargs)

        # Utilize custom prompts and SOPs

        custom_prompt = self.construct_dynamic_prompt(self.custom_prompt)

        custom_sop = self.construct_dynamic_sop(self.custom_sop)

        # Process custom prompts and SOPs

        return response

    def construct_dynamic_prompt(self, prompt):

        # Custom prompt construction logic

        return prompt

    def construct_dynamic_sop(self, sop):

        # Custom SOP construction logic

        return sop

```

In the example above, we define two new attributes within the `MyCustomAgent` class: `custom_sop` and `custom_prompt`. These attributes can be used to store custom prompts and SOPs specific to your custom agent class.

Within the overridden `run` method, you can utilize these custom prompts and SOPs by calling the `construct_dynamic_prompt` and `construct_dynamic_sop` methods, which can be defined within the `MyCustomAgent` class to implement specialized prompt and SOP construction logic.

#### Step 5: Introduce Custom Response Handling

The Agent class provides built-in response filtering capabilities, allowing agents to filter out or replace specific words or phrases in their responses. Custom agent classes can inherit and extend this feature to ensure compliance with content moderation policies or specific guidelines.

```python
from swarms import Agent


class MyCustomAgent(Agent):

    def __init__(self, *args, **kwargs):

        super().__init__(*args, **kwargs)

        # Custom initialization logic

        self.response_filters = ["filter_word_1", "filter_word_2"]

    def run(self, task, *args, **kwargs):

        # Customize the run method

        response = super().run(task, *args, **kwargs)

        # Apply custom response filtering

        filtered_response = self.apply_response_filters(response)

        return filtered_response

    def apply_response_filters(self, response):

        # Custom response filtering logic

        for word in self.response_filters:

            response = response.replace(word, "[FILTERED]")

        return response

```

In the example above, we define a new attribute `response_filters` within the `MyCustomAgent` class, which is a list of words or phrases that should be filtered out or replaced in the agent's responses.

Within the overridden `run` method, we call the `apply_response_filters` method, which can be defined within the `MyCustomAgent` class to implement specialized response filtering logic. In the example, we iterate over the `response_filters` list and replace each filtered word or phrase with a placeholder string (`"[FILTERED]"`).

### Advanced Customization and Integration

The Agent class and its inherited custom agent classes can be further extended and customized to suit specific requirements and integrate with external libraries, APIs, and services. Here are some advanced customization and integration examples:

1\. **Multimodal Input/Output Integration**: Custom agent classes can leverage the multimodal input/output capabilities of the Agent class and introduce specialized handling for various data formats such as images, audio, and video.

2\. **Code Execution and Integration**: The Agent class supports code execution, enabling agents to run and evaluate code snippets. Custom agent classes can inherit and extend this capability, introducing specialized code execution environments, sandboxing mechanisms, or integration with external code repositories or platforms.

3\. **External API and Service Integration**: Custom agent classes can integrate with external APIs and services, enabling agents to leverage specialized data sources, computational resources, or domain-specific services.

4\. **Performance Optimization**: Depending on the use case and requirements, custom agent classes can introduce performance optimizations, such as adjusting loop intervals, retry attempts, or enabling parallel execution for certain tasks.

5\. **Logging and Monitoring**: Custom agent classes can introduce specialized logging and monitoring mechanisms, enabling agents to track their performance, identify potential issues, and generate detailed reports or dashboards.

6\. **Security and Privacy Enhancements**: Custom agent classes can implement security and privacy enhancements, such as data encryption, access control mechanisms, or compliance with industry-specific regulations and standards.

7\. **Distributed Execution and Scaling**: Custom agent classes can be designed to support distributed execution and scaling, enabling agents to leverage cloud computing resources or distributed computing frameworks for handling large-scale tasks or high-concurrency workloads.

By leveraging these advanced customization and integration capabilities, agents can create highly specialized and sophisticated custom agent classes tailored to their unique requirements and use cases.

### Best Practices and Considerations

While building custom agent classes by inheriting from the Agent class offers immense flexibility and power, it's essential to follow best practices and consider potential challenges and considerations:

1\. **Maintainability and Documentation**: As custom agent classes become more complex, it's crucial to prioritize maintainability and thorough documentation. Clear and concise code, comprehensive comments, and up-to-date documentation can significantly improve the long-term sustainability and collaboration efforts surrounding custom agent classes.

2\. **Testing and Validation**: Custom agent classes should undergo rigorous testing and validation to ensure their correctness, reliability, and adherence to expected behaviors. Establish a robust testing framework and continuously validate the agent's performance, particularly after introducing new features or integrations.

3\. **Security and Privacy Considerations**: When building custom agent classes, it's essential to consider security and privacy implications, especially if the agents will handle sensitive data or interact with critical systems. Implement appropriate security measures, such as access controls, data encryption, and secure communication protocols, to protect against potential vulnerabilities and ensure compliance with relevant regulations and standards.

4\. **Scalability and Performance Monitoring**: As custom agent classes are deployed and adopted, it's important to monitor their scalability and performance characteristics. Identify potential bottlenecks, resource constraints, or performance degradation, and implement appropriate optimization strategies or scaling mechanisms to ensure efficient and reliable operation.

5\. **Collaboration and Knowledge Sharing**: Building custom agent classes often involves collaboration among teams and stakeholders. Foster an environment of knowledge sharing, code reviews, and open communication to ensure that everyone involved understands the agent's capabilities, limitations, and intended use cases.

6\. **Ethical Considerations**: As AI agents become more advanced and autonomous, it's crucial to consider the ethical implications of their actions and decisions. Implement appropriate safeguards, oversight mechanisms, and ethical guidelines to ensure that custom agent classes operate in a responsible and transparent manner, aligning with ethical principles and societal values.

7\. **Continuous Learning and Adaptation**: The field of AI is rapidly evolving, with new techniques, tools, and best practices emerging regularly. Stay up-to-date with the latest developments and be prepared to adapt and refine your custom agent classes as new advancements become available.

By following these best practices and considering potential challenges, agents can create robust, reliable, and ethical custom agent classes that meet their specific requirements while adhering to industry standards and best practices.

# Conclusion

In this comprehensive guide, we have explored the process of creating custom agent classes by inheriting from the powerful Agent class. We have covered the key features of the Agent class, walked through the step-by-step process of inheriting and extending its functionality, and discussed advanced customization and integration techniques.

Building custom agent classes empowers AI agents to create tailored and specialized agents capable of tackling unique challenges and addressing specific domain requirements. By leveraging the rich features and extensibility of the Agent class, agents can imbue their offspring agents with unique capabilities, specialized toolsets, and tailored decision-making processes.

Remember, the journey of building custom agent classes is an iterative and collaborative process that requires continuous learning, adaptation, and refinement.

--------------------------------------------------

# File: swarms/structs/forest_swarm.md

# Forest Swarm

This documentation describes the **ForestSwarm** that organizes agents into trees. Each agent specializes in processing specific tasks. Trees are collections of agents, each assigned based on their relevance to a task through keyword extraction and embedding-based similarity.

The architecture allows for efficient task assignment by selecting the most relevant agent from a set of trees. Tasks are processed asynchronously, with agents selected based on task relevance, calculated by the similarity of system prompts and task keywords.


## Module Path: `swarms.structs.tree_swarm`

---

### Class: `TreeAgent`

`TreeAgent` represents an individual agent responsible for handling a specific task. Agents are initialized with a **system prompt** and are responsible for dynamically determining their relevance to a given task.

#### Attributes

| **Attribute**            | **Type**         | **Description**                                                                 |
|--------------------------|------------------|---------------------------------------------------------------------------------|
| `system_prompt`          | `str`            | A string that defines the agent's area of expertise and task-handling capability.|
| `llm`                    | `callable`       | The language model (LLM) used to process tasks (e.g., GPT-4).                    |
| `agent_name`             | `str`            | The name of the agent.                                                          |
| `system_prompt_embedding`| `tensor`         | Embedding of the system prompt for similarity-based task matching.               |
| `relevant_keywords`      | `List[str]`      | Keywords dynamically extracted from the system prompt to assist in task matching.|
| `distance`               | `Optional[float]`| The computed distance between agents based on embedding similarity.              |

#### Methods

| **Method**         | **Input**                       | **Output**         | **Description**                                                                 |
|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------|
| `calculate_distance(other_agent: TreeAgent)` | `other_agent: TreeAgent`   | `float`          | Calculates the cosine similarity between this agent and another agent.         |
| `run_task(task: str)`                  | `task: str`                  | `Any`            | Executes the task, logs the input/output, and returns the result.               |
| `is_relevant_for_task(task: str, threshold: float = 0.7)` | `task: str, threshold: float` | `bool`  | Checks if the agent is relevant for the task using keyword matching or embedding similarity.|

---

### Class: `Tree`

`Tree` organizes multiple agents into a hierarchical structure, where agents are sorted based on their relevance to tasks.

#### Attributes

| **Attribute**            | **Type**         | **Description**                                                                 |
|--------------------------|------------------|---------------------------------------------------------------------------------|
| `tree_name`              | `str`            | The name of the tree (represents a domain of agents, e.g., "Financial Tree").    |
| `agents`                 | `List[TreeAgent]`| List of agents belonging to this tree.                                           |

#### Methods

| **Method**         | **Input**                       | **Output**         | **Description**                                                                 |
|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------|
| `calculate_agent_distances()` | `None`                  | `None`             | Calculates and assigns distances between agents based on similarity of prompts. |
| `find_relevant_agent(task: str)` | `task: str`           | `Optional[TreeAgent]` | Finds the most relevant agent for a task based on keyword and embedding similarity. |
| `log_tree_execution(task: str, selected_agent: TreeAgent, result: Any)` | `task: str, selected_agent: TreeAgent, result: Any` | `None` | Logs details of the task execution by the selected agent.                      |

---

### Class: `ForestSwarm` 

`ForestSwarm` is the main class responsible for managing multiple trees. It oversees task delegation by finding the most relevant tree and agent for a given task.

#### Attributes

| **Attribute**            | **Type**         | **Description**                                                                 |
|--------------------------|------------------|---------------------------------------------------------------------------------|
| `trees`                  | `List[Tree]`     | List of trees containing agents organized by domain.                             |

#### Methods

| **Method**         | **Input**                       | **Output**         | **Description**                                                                 |
|--------------------|---------------------------------|--------------------|---------------------------------------------------------------------------------|
| `find_relevant_tree(task: str)` | `task: str`           | `Optional[Tree]`    | Searches across all trees to find the most relevant tree based on task requirements.|
| `run(task: str)`                | `task: str`           | `Any`              | Executes the task by finding the most relevant agent from the relevant tree.    |

## Full Code Example

```python
from swarms.structs.tree_swarm import TreeAgent, Tree, ForestSwarm
# Example Usage:

# Create agents with varying system prompts and dynamically generated distances/keywords
agents_tree1 = [
    TreeAgent(
        system_prompt="Stock Analysis Agent",
        agent_name="Stock Analysis Agent",
    ),
    TreeAgent(
        system_prompt="Financial Planning Agent",
        agent_name="Financial Planning Agent",
    ),
    TreeAgent(
        agent_name="Retirement Strategy Agent",
        system_prompt="Retirement Strategy Agent",
    ),
]

agents_tree2 = [
    TreeAgent(
        system_prompt="Tax Filing Agent",
        agent_name="Tax Filing Agent",
    ),
    TreeAgent(
        system_prompt="Investment Strategy Agent",
        agent_name="Investment Strategy Agent",
    ),
    TreeAgent(
        system_prompt="ROTH IRA Agent", agent_name="ROTH IRA Agent"
    ),
]

# Create trees
tree1 = Tree(tree_name="Financial Tree", agents=agents_tree1)
tree2 = Tree(tree_name="Investment Tree", agents=agents_tree2)

# Create the ForestSwarm
multi_agent_structure = ForestSwarm(trees=[tree1, tree2])

# Run a task
task = "Our company is incorporated in delaware, how do we do our taxes for free?"
output = multi_agent_structure.run(task)
print(output)
```



---

## Example Workflow

1. **Create Agents**: Agents are initialized with varying system prompts, representing different areas of expertise (e.g., stock analysis, tax filing).
2. **Create Trees**: Agents are grouped into trees, with each tree representing a domain (e.g., "Financial Tree", "Investment Tree").
3. **Run Task**: When a task is submitted, the system traverses through all trees and finds the most relevant agent to handle the task.
4. **Task Execution**: The selected agent processes the task, and the result is returned.

```plaintext
Task: "Our company is incorporated in Delaware, how do we do our taxes for free?"
```

**Process**:
- The system searches through the `Financial Tree` and `Investment Tree`.
- The most relevant agent (likely the "Tax Filing Agent") is selected based on keyword matching and prompt similarity.
- The task is processed, and the result is logged and returned.

---

## Analysis of the Swarm Architecture

The **Swarm Architecture** leverages a hierarchical structure (forest) composed of individual trees, each containing agents specialized in specific domains. This design allows for:

- **Modular and Scalable Organization**: By separating agents into trees, it is easy to expand or contract the system by adding or removing trees or agents.
- **Task Specialization**: Each agent is specialized, which ensures that tasks are matched with the most appropriate agent based on relevance and expertise.
- **Dynamic Matching**: The architecture uses both keyword-based and embedding-based matching to assign tasks, ensuring a high level of accuracy in agent selection.
- **Logging and Accountability**: Each task execution is logged in detail, providing transparency and an audit trail of which agent handled which task and the results produced.
- **Asynchronous Task Execution**: The architecture can be adapted for asynchronous task processing, making it scalable and suitable for large-scale task handling in real-time systems.

---

## Mermaid Diagram of the Swarm Architecture

```mermaid
graph TD
    A[ForestSwarm] --> B[Financial Tree]
    A --> C[Investment Tree]
    
    B --> D[Stock Analysis Agent]
    B --> E[Financial Planning Agent]
    B --> F[Retirement Strategy Agent]
    
    C --> G[Tax Filing Agent]
    C --> H[Investment Strategy Agent]
    C --> I[ROTH IRA Agent]

    subgraph Tree Agents
        D[Stock Analysis Agent]
        E[Financial Planning Agent]
        F[Retirement Strategy Agent]
        G[Tax Filing Agent]
        H[Investment Strategy Agent]
        I[ROTH IRA Agent]
    end
```

### Explanation of the Diagram

- **ForestSwarm**: Represents the top-level structure managing multiple trees.
- **Trees**: In the example, two trees exist—**Financial Tree** and **Investment Tree**—each containing agents related to specific domains.
- **Agents**: Each agent within the tree is responsible for handling tasks in its area of expertise. Agents within a tree are organized based on their prompt similarity (distance).

---

### Summary

This **Multi-Agent Tree Structure** provides an efficient, scalable, and accurate architecture for delegating and executing tasks based on domain-specific expertise. The combination of hierarchical organization, dynamic task matching, and logging ensures reliability, performance, and transparency in task execution.

--------------------------------------------------

# File: swarms/structs/graph_workflow.md

# GraphWorkflow

A powerful workflow orchestration system that creates directed graphs of agents for complex multi-agent collaboration and task execution.

## Overview

The `GraphWorkflow` class is a sophisticated workflow management system that enables the creation and execution of complex multi-agent workflows. It represents workflows as directed graphs where nodes are agents and edges represent data flow and dependencies between agents. The system supports parallel execution, automatic compilation optimization, and comprehensive visualization capabilities.

Key features:

| Feature                | Description                                                                                   |
|------------------------|-----------------------------------------------------------------------------------------------|
| **Agent-based nodes**  | Each node represents an agent that can process tasks                                          |
| **Directed graph structure** | Edges define the flow of data between agents                                            |
| **Parallel execution** | Multiple agents can run simultaneously within layers                                          |
| **Automatic compilation** | Optimizes workflow structure for efficient execution                                       |
| **Rich visualization** | Generate visual representations using Graphviz                                                |
| **Serialization**      | Save and load workflows as JSON                                                               |
| **Pattern detection**  | Automatically identifies parallel processing patterns                                         |

## Architecture

```mermaid
graph TB
    subgraph "GraphWorkflow Architecture"
        A[GraphWorkflow] --> B[Node Collection]
        A --> C[Edge Collection]
        A --> D[NetworkX Graph]
        A --> E[Execution Engine]
        
        B --> F[Agent Nodes]
        C --> G[Directed Edges]
        D --> H[Topological Sort]
        E --> I[Parallel Execution]
        E --> J[Layer Processing]
        
        subgraph "Node Types"
            F --> K[Agent Node]
            K --> L[Agent Instance]
            K --> M[Node Metadata]
        end
        
        subgraph "Edge Types"
            G --> N[Simple Edge]
            G --> O[Fan-out Edge]
            G --> P[Fan-in Edge]
            G --> Q[Parallel Chain]
        end
        
        subgraph "Execution Patterns"
            I --> R[Thread Pool]
            I --> S[Concurrent Futures]
            J --> T[Layer-by-layer]
            J --> U[Dependency Resolution]
        end
    end
```

## Class Reference

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `id` | `Optional[str]` | Unique identifier for the workflow | Auto-generated UUID |
| `name` | `Optional[str]` | Human-readable name for the workflow | "Graph-Workflow-01" |
| `description` | `Optional[str]` | Detailed description of the workflow | Generic description |
| `nodes` | `Optional[Dict[str, Node]]` | Initial collection of nodes | `{}` |
| `edges` | `Optional[List[Edge]]` | Initial collection of edges | `[]` |
| `entry_points` | `Optional[List[str]]` | Node IDs that serve as starting points | `[]` |
| `end_points` | `Optional[List[str]]` | Node IDs that serve as ending points | `[]` |
| `max_loops` | `int` | Maximum number of execution loops | `1` |
| `task` | `Optional[str]` | The task to be executed by the workflow | `None` |
| `auto_compile` | `bool` | Whether to automatically compile the workflow | `True` |
| `verbose` | `bool` | Whether to enable detailed logging | `False` |

### Core Methods

#### `add_node(agent: Agent, **kwargs)`

Adds an agent node to the workflow graph.

| Parameter | Type | Description |
|-----------|------|-------------|
| `agent` | `Agent` | The agent to add as a node |
| `**kwargs` | `Any` | Additional keyword arguments for the node |

**Raises:**

- `ValueError`: If a node with the same ID already exists

**Example:**

```python
workflow = GraphWorkflow()
agent = Agent(agent_name="ResearchAgent", model_name="gpt-4")
workflow.add_node(agent, metadata={"priority": "high"})
```

#### `add_edge(edge_or_source, target=None, **kwargs)`

Adds an edge to connect nodes in the workflow.

| Parameter | Type | Description |
|-----------|------|-------------|
| `edge_or_source` | `Edge` or `str` | Either an Edge object or source node ID |
| `target` | `str` | Target node ID (required if edge_or_source is not an Edge) |
| `**kwargs` | `Any` | Additional keyword arguments for the edge |

**Raises:**

- `ValueError`: If source or target nodes don't exist

**Example:**

```python
# Using Edge object
edge = Edge(source="agent1", target="agent2")
workflow.add_edge(edge)

# Using node IDs
workflow.add_edge("agent1", "agent2", metadata={"priority": "high"})
```

#### `add_edges_from_source(source, targets, **kwargs)`

Creates a fan-out pattern where one source connects to multiple targets.

| Parameter | Type | Description |
|-----------|------|-------------|
| `source` | `str` | Source node ID |
| `targets` | `List[str]` | List of target node IDs |
| `**kwargs` | `Any` | Additional keyword arguments for all edges |

**Returns:**

- `List[Edge]`: List of created Edge objects

**Example:**

```python
workflow.add_edges_from_source(
    "DataCollector",
    ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"]
)
```

#### `add_edges_to_target(sources, target, **kwargs)`

Creates a fan-in pattern where multiple sources connect to one target.

| Parameter | Type | Description |
|-----------|------|-------------|
| `sources` | `List[str]` | List of source node IDs |
| `target` | `str` | Target node ID |
| `**kwargs` | `Any` | Additional keyword arguments for all edges |

**Returns:**

- `List[Edge]`: List of created Edge objects

**Example:**

```python
workflow.add_edges_to_target(
    ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"],
    "SynthesisAgent"
)
```

#### `add_parallel_chain(sources, targets, **kwargs)`

Creates a full mesh connection between multiple sources and targets.

| Parameter | Type | Description |
|-----------|------|-------------|
| `sources` | `List[str]` | List of source node IDs |
| `targets` | `List[str]` | List of target node IDs |
| `**kwargs` | `Any` | Additional keyword arguments for all edges |

**Returns:**

- `List[Edge]`: List of created Edge objects


**Example:**

```python
workflow.add_parallel_chain(
    ["DataCollector1", "DataCollector2"],
    ["Analyst1", "Analyst2", "Analyst3"]
)
```

### Execution Methods

#### `run(task: str = None, img: Optional[str] = None, *args, **kwargs) -> Dict[str, Any]`

Executes the workflow with optimized parallel agent execution.

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | Task to execute (uses self.task if not provided) |
| `img` | `Optional[str]` | Image path for vision-enabled agents |
| `*args` | `Any` | Additional positional arguments |
| `**kwargs` | `Any` | Additional keyword arguments |

**Returns:**

- `Dict[str, Any]`: Execution results from all nodes

**Example:**

```python
results = workflow.run(
    task="Analyze market trends for cryptocurrency",
    max_loops=2
)
```

#### `arun(task: str = None, *args, **kwargs) -> Dict[str, Any]`

Async version of run for better performance with I/O bound operations.

| Parameter | Type | Description |
|-----------|------|-------------|
| `task` | `str` | Task to execute |
| `*args` | `Any` | Additional positional arguments |
| `**kwargs` | `Any` | Additional keyword arguments |

**Returns:**

- `Dict[str, Any]`: Execution results from all nodes

**Example:**

```python
import asyncio
results = await workflow.arun("Process large dataset")
```

### Compilation and Optimization

#### `compile()`

Pre-computes expensive operations for faster execution.

**Example:**

```python
workflow.compile()
status = workflow.get_compilation_status()
print(f"Compiled: {status['is_compiled']}")
```

#### `get_compilation_status() -> Dict[str, Any]`

Returns detailed compilation status information.

**Returns:**

- `Dict[str, Any]`: Compilation status including cache state and performance metrics

**Example:**

```python
status = workflow.get_compilation_status()
print(f"Layers: {status['cached_layers_count']}")
print(f"Max workers: {status['max_workers']}")
```

### Visualization Methods

#### `visualize(format: str = "png", view: bool = True, engine: str = "dot", show_summary: bool = False) -> str`

Generates a visual representation of the workflow using Graphviz.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `format` | `str` | Output format ('png', 'svg', 'pdf', 'dot') | `"png"` |
| `view` | `bool` | Whether to open the visualization | `True` |
| `engine` | `str` | Graphviz layout engine | `"dot"` |
| `show_summary` | `bool` | Whether to print parallel processing summary | `False` |

**Returns:**

- `str`: Path to the generated visualization file

**Example:**

```python
output_file = workflow.visualize(
    format="svg",
    show_summary=True
)
print(f"Visualization saved to: {output_file}")
```

#### `visualize_simple() -> str`

Generates a simple text-based visualization.

**Returns:**

- `str`: Text representation of the workflow

**Example:**

```python
text_viz = workflow.visualize_simple()
print(text_viz)
```

### Serialization Methods

#### `to_json(fast: bool = True, include_conversation: bool = False, include_runtime_state: bool = False) -> str`

Serializes the workflow to JSON format.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `fast` | `bool` | Whether to use fast JSON serialization | `True` |
| `include_conversation` | `bool` | Whether to include conversation history | `False` |
| `include_runtime_state` | `bool` | Whether to include runtime state | `False` |

**Returns:**

- `str`: JSON representation of the workflow

**Example:**

```python
json_data = workflow.to_json(
    include_conversation=True,
    include_runtime_state=True
)
```

#### `from_json(json_str: str, restore_runtime_state: bool = False) -> GraphWorkflow`

Deserializes a workflow from JSON format.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `json_str` | `str` | JSON string representation | Required |
| `restore_runtime_state` | `bool` | Whether to restore runtime state | `False` |

**Returns:**

- `GraphWorkflow`: A new GraphWorkflow instance

**Example:**

```python
workflow = GraphWorkflow.from_json(json_data, restore_runtime_state=True)
```

#### `save_to_file(filepath: str, include_conversation: bool = False, include_runtime_state: bool = False, overwrite: bool = False) -> str`

Saves the workflow to a JSON file.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `filepath` | `str` | Path to save the JSON file | Required |
| `include_conversation` | `bool` | Whether to include conversation history | `False` |
| `include_runtime_state` | `bool` | Whether to include runtime state | `False` |
| `overwrite` | `bool` | Whether to overwrite existing files | `False` |

**Returns:**

- `str`: Path to the saved file

**Example:**

```python
filepath = workflow.save_to_file(
    "my_workflow.json",
    include_conversation=True
)
```

#### `load_from_file(filepath: str, restore_runtime_state: bool = False) -> GraphWorkflow`

Loads a workflow from a JSON file.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `filepath` | `str` | Path to the JSON file | Required |
| `restore_runtime_state` | `bool` | Whether to restore runtime state | `False` |

**Returns:**

- `GraphWorkflow`: Loaded workflow instance

**Example:**

```python
workflow = GraphWorkflow.load_from_file("my_workflow.json")
```

### Utility Methods

#### `export_summary() -> Dict[str, Any]`

Generates a human-readable summary of the workflow.

**Returns:**

- `Dict[str, Any]`: Comprehensive workflow summary

**Example:**

```python
summary = workflow.export_summary()
print(f"Workflow has {summary['structure']['nodes']} nodes")
print(f"Compilation status: {summary['compilation_status']['is_compiled']}")
```

#### `set_entry_points(entry_points: List[str])`

Sets the entry points for the workflow.

| Parameter | Type | Description |
|-----------|------|-------------|
| `entry_points` | `List[str]` | List of node IDs to serve as entry points |

**Example:**

```python
workflow.set_entry_points(["DataCollector", "ResearchAgent"])
```

#### `set_end_points(end_points: List[str])`

Sets the end points for the workflow.

| Parameter | Type | Description |
|-----------|------|-------------|
| `end_points` | `List[str]` | List of node IDs to serve as end points |

**Example:**

```python
workflow.set_end_points(["SynthesisAgent", "ReportGenerator"])
```

### Class Methods

#### `from_spec(agents, edges, entry_points=None, end_points=None, task=None, **kwargs) -> GraphWorkflow`

Constructs a workflow from a list of agents and connections.

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `agents` | `List` | List of agents or Node objects | Required |
| `edges` | `List` | List of edges or edge tuples | Required |
| `entry_points` | `List[str]` | List of entry point node IDs | `None` |
| `end_points` | `List[str]` | List of end point node IDs | `None` |
| `task` | `str` | Task to be executed by the workflow | `None` |
| `**kwargs` | `Any` | Additional keyword arguments | `{}` |

**Returns:**

- `GraphWorkflow`: A new GraphWorkflow instance

**Example:**

```python
workflow = GraphWorkflow.from_spec(
    agents=[agent1, agent2, agent3],
    edges=[
        ("agent1", "agent2"),
        ("agent2", "agent3"),
        ("agent1", ["agent2", "agent3"])  # Fan-out
    ],
    task="Analyze market data"
)
```

## Examples

### Basic Sequential Workflow

```python
from swarms import Agent, GraphWorkflow
from swarms.prompts.multi_agent_collab_prompt import MULTI_AGENT_COLLAB_PROMPT_TWO

# Create agents
research_agent = Agent(
    agent_name="ResearchAgent",
    model_name="gpt-4",
    system_prompt=MULTI_AGENT_COLLAB_PROMPT_TWO,
    max_loops=1
)

analysis_agent = Agent(
    agent_name="AnalysisAgent", 
    model_name="gpt-4",
    system_prompt=MULTI_AGENT_COLLAB_PROMPT_TWO,
    max_loops=1
)

# Build workflow
workflow = GraphWorkflow(name="Research-Analysis-Workflow")
workflow.add_node(research_agent)
workflow.add_node(analysis_agent)
workflow.add_edge("ResearchAgent", "AnalysisAgent")

# Execute
results = workflow.run("What are the latest trends in AI?")
print(results)
```

### Parallel Processing Workflow

```python
from swarms import Agent, GraphWorkflow

# Create specialized agents
data_collector = Agent(agent_name="DataCollector", model_name="gpt-4")
technical_analyst = Agent(agent_name="TechnicalAnalyst", model_name="gpt-4")
fundamental_analyst = Agent(agent_name="FundamentalAnalyst", model_name="gpt-4")
sentiment_analyst = Agent(agent_name="SentimentAnalyst", model_name="gpt-4")
synthesis_agent = Agent(agent_name="SynthesisAgent", model_name="gpt-4")

# Build parallel workflow
workflow = GraphWorkflow(name="Market-Analysis-Workflow")

# Add all agents
for agent in [data_collector, technical_analyst, fundamental_analyst, 
              sentiment_analyst, synthesis_agent]:
    workflow.add_node(agent)

# Create fan-out pattern: data collector feeds all analysts
workflow.add_edges_from_source(
    "DataCollector",
    ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"]
)

# Create fan-in pattern: all analysts feed synthesis agent
workflow.add_edges_to_target(
    ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst"],
    "SynthesisAgent"
)

# Execute
results = workflow.run("Analyze Bitcoin market trends")
print(results)
```

### Complex Multi-Layer Workflow

```python
from swarms import Agent, GraphWorkflow

# Create agents for different stages
data_collectors = [
    Agent(agent_name=f"DataCollector{i}", model_name="gpt-4")
    for i in range(1, 4)
]

analysts = [
    Agent(agent_name=f"Analyst{i}", model_name="gpt-4")
    for i in range(1, 4)
]

validators = [
    Agent(agent_name=f"Validator{i}", model_name="gpt-4")
    for i in range(1, 3)
]

synthesis_agent = Agent(agent_name="SynthesisAgent", model_name="gpt-4")

# Build complex workflow
workflow = GraphWorkflow(name="Complex-Research-Workflow")

# Add all agents
all_agents = data_collectors + analysts + validators + [synthesis_agent]
for agent in all_agents:
    workflow.add_node(agent)

# Layer 1: Data collectors feed all analysts in parallel
workflow.add_parallel_chain(
    [agent.agent_name for agent in data_collectors],
    [agent.agent_name for agent in analysts]
)

# Layer 2: Analysts feed validators
workflow.add_parallel_chain(
    [agent.agent_name for agent in analysts],
    [agent.agent_name for agent in validators]
)

# Layer 3: Validators feed synthesis agent
workflow.add_edges_to_target(
    [agent.agent_name for agent in validators],
    "SynthesisAgent"
)

# Visualize and execute
workflow.visualize(show_summary=True)
results = workflow.run("Comprehensive analysis of renewable energy markets")
```

### Workflow with Custom Metadata

```python
from swarms import Agent, GraphWorkflow, Edge

# Create agents with specific roles
research_agent = Agent(agent_name="ResearchAgent", model_name="gpt-4")
analysis_agent = Agent(agent_name="AnalysisAgent", model_name="gpt-4")

# Build workflow with metadata
workflow = GraphWorkflow(
    name="Metadata-Workflow",
    description="Workflow demonstrating metadata usage"
)

workflow.add_node(research_agent, metadata={"priority": "high", "timeout": 300})
workflow.add_node(analysis_agent, metadata={"priority": "medium", "timeout": 600})

# Add edge with metadata
edge = Edge(
    source="ResearchAgent",
    target="AnalysisAgent",
    metadata={"data_type": "research_findings", "priority": "high"}
)
workflow.add_edge(edge)

# Execute with custom parameters
results = workflow.run(
    "Analyze the impact of climate change on agriculture",
    max_loops=2
)
```

### Workflow Serialization and Persistence

```python
from swarms import Agent, GraphWorkflow

# Create workflow
research_agent = Agent(agent_name="ResearchAgent", model_name="gpt-4")
analysis_agent = Agent(agent_name="AnalysisAgent", model_name="gpt-4")

workflow = GraphWorkflow(name="Persistent-Workflow")
workflow.add_node(research_agent)
workflow.add_node(analysis_agent)
workflow.add_edge("ResearchAgent", "AnalysisAgent")

# Execute and get conversation
results = workflow.run("Research quantum computing applications")

# Save workflow with conversation history
filepath = workflow.save_to_file(
    "quantum_research_workflow.json",
    include_conversation=True,
    include_runtime_state=True
)

# Load workflow later
loaded_workflow = GraphWorkflow.load_from_file(
    filepath,
    restore_runtime_state=True
)

# Continue execution
new_results = loaded_workflow.run("Continue with quantum cryptography analysis")
```

### Advanced Pattern Detection

```python
from swarms import Agent, GraphWorkflow

# Create a complex workflow with multiple patterns
workflow = GraphWorkflow(name="Pattern-Detection-Workflow", verbose=True)

# Create agents
agents = {
    "collector": Agent(agent_name="DataCollector", model_name="gpt-4"),
    "tech_analyst": Agent(agent_name="TechnicalAnalyst", model_name="gpt-4"),
    "fund_analyst": Agent(agent_name="FundamentalAnalyst", model_name="gpt-4"),
    "sentiment_analyst": Agent(agent_name="SentimentAnalyst", model_name="gpt-4"),
    "risk_analyst": Agent(agent_name="RiskAnalyst", model_name="gpt-4"),
    "synthesis": Agent(agent_name="SynthesisAgent", model_name="gpt-4"),
    "validator": Agent(agent_name="Validator", model_name="gpt-4")
}

# Add all agents
for agent in agents.values():
    workflow.add_node(agent)

# Create complex patterns
# Fan-out from collector
workflow.add_edges_from_source(
    "DataCollector",
    ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst", "RiskAnalyst"]
)

# Fan-in to synthesis
workflow.add_edges_to_target(
    ["TechnicalAnalyst", "FundamentalAnalyst", "SentimentAnalyst", "RiskAnalyst"],
    "SynthesisAgent"
)

# Final validation step
workflow.add_edge("SynthesisAgent", "Validator")

# Compile and get status
workflow.compile()
status = workflow.get_compilation_status()

print(f"Compilation status: {status}")
print(f"Layers: {status['cached_layers_count']}")
print(f"Max workers: {status['max_workers']}")

# Visualize with pattern detection
workflow.visualize(show_summary=True, format="png")
```

### Error Handling and Recovery

```python
from swarms import Agent, GraphWorkflow
import logging

# Set up logging
logging.basicConfig(level=logging.INFO)

# Create workflow with error handling
workflow = GraphWorkflow(
    name="Error-Handling-Workflow",
    verbose=True,
    max_loops=1
)

# Create agents
try:
    research_agent = Agent(agent_name="ResearchAgent", model_name="gpt-4")
    analysis_agent = Agent(agent_name="AnalysisAgent", model_name="gpt-4")
    
    workflow.add_node(research_agent)
    workflow.add_node(analysis_agent)
    workflow.add_edge("ResearchAgent", "AnalysisAgent")
    
    # Execute with error handling
    try:
        results = workflow.run("Analyze market trends")
        print("Workflow completed successfully")
        print(results)
        
    except Exception as e:
        print(f"Workflow execution failed: {e}")
        
        # Get workflow summary for debugging
        summary = workflow.export_summary()
        print(f"Workflow state: {summary['structure']}")
        
except Exception as e:
    print(f"Workflow setup failed: {e}")
```

## Conclusion

The `GraphWorkflow` class provides a powerful and flexible framework for orchestrating complex multi-agent workflows. Its key benefits include:

### Benefits

| Benefit         | Description                                                                                      |
|-----------------|--------------------------------------------------------------------------------------------------|
| **Scalability** | Supports workflows with hundreds of agents through efficient parallel execution                  |
| **Flexibility** | Multiple connection patterns (sequential, fan-out, fan-in, parallel chains)                      |
| **Performance** | Automatic compilation and optimization for faster execution                                      |
| **Visualization** | Rich visual representations for workflow understanding and debugging                           |
| **Persistence** | Complete serialization and deserialization capabilities                                          |
| **Error Handling** | Comprehensive error handling and recovery mechanisms                                          |
| **Monitoring**  | Detailed logging and status reporting                                                            |

### Use Cases

| Use Case                | Description                                                        |
|-------------------------|--------------------------------------------------------------------|
| **Research Workflows**  | Multi-stage research with data collection, analysis, and synthesis |
| **Content Generation**  | Parallel content creation with validation and refinement           |
| **Data Processing**     | Complex ETL pipelines with multiple processing stages              |
| **Decision Making**     | Multi-agent decision systems with voting and consensus             |
| **Quality Assurance**   | Multi-stage validation and verification processes                  |
| **Automated Testing**   | Complex test orchestration with parallel execution                 |

### Best Practices

| Best Practice                        | Description                                                      |
|---------------------------------------|------------------------------------------------------------------|
| **Use meaningful agent names**        | Helps with debugging and visualization                           |
| **Leverage parallel patterns**        | Use fan-out and fan-in for better performance                    |
| **Compile workflows**                 | Always compile before execution for optimal performance           |
| **Monitor execution**                 | Use verbose mode and status reporting for debugging              |
| **Save important workflows**          | Use serialization for workflow persistence                       |
| **Handle errors gracefully**          | Implement proper error handling and recovery                     |
| **Visualize complex workflows**       | Use visualization to understand and debug workflows              |

The GraphWorkflow system represents a significant advancement in multi-agent orchestration, providing the tools needed to build complex, scalable, and maintainable AI workflows.

--------------------------------------------------

# File: swarms/structs/group_chat.md

# GroupChat Swarm Documentation

A production-grade multi-agent system enabling sophisticated group conversations between AI agents with customizable speaking patterns, parallel processing capabilities, and comprehensive conversation tracking.

## Advanced Configuration

### Agent Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| agent_name | str | Required | Unique identifier for the agent |
| system_prompt | str | Required | Role and behavior instructions |
| llm | Any | Required | Language model instance |
| max_loops | int | 1 | Maximum conversation turns |
| autosave | bool | False | Enable conversation saving |
| dashboard | bool | False | Enable monitoring dashboard |
| verbose | bool | True | Enable detailed logging |
| dynamic_temperature | bool | True | Enable dynamic temperature |
| retry_attempts | int | 1 | Failed request retry count |
| context_length | int | 200000 | Maximum context window |
| output_type | str | "string" | Response format type |
| streaming_on | bool | False | Enable streaming responses |

### GroupChat Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| name | str | "GroupChat" | Chat group identifier |
| description | str | "" | Purpose description |
| agents | List[Agent] | [] | Participating agents |
| speaker_fn | Callable | round_robin | Speaker selection function |
| max_loops | int | 10 | Maximum conversation turns |


## Core Concepts

The GroupChat system consists of several key components:

1. **Agents**: Individual AI agents with specialized knowledge and roles
2. **Speaker Functions**: Control mechanisms for conversation flow
3. **Chat History**: Structured conversation tracking
4. **Response Models**: Pydantic models for data validation

## Basic Usage

```python

import os
from dotenv import load_dotenv
from swarms import Agent, GroupChat, expertise_based

if __name__ == "__main__":

    # Example agents
    agent1 = Agent(
        agent_name="Financial-Analysis-Agent",
        system_prompt="You are a financial analyst specializing in investment strategies.",
        model_name="gpt-4.1",
        max_loops=1,
    )

    agent2 = Agent(
        agent_name="Tax-Adviser-Agent",
        system_prompt="You are a tax adviser who provides clear and concise guidance on tax-related queries.",
        model_name="gpt-4.1",
        max_loops=1,
    )

    agents = [agent1, agent2]

    chat = GroupChat(
        name="Investment Advisory",
        description="Financial and tax analysis group",
        agents=agents,
        speaker_fn=expertise_based,
    )

    history = chat.run(
        "How to optimize tax strategy for investments?"
    )
    print(history.model_dump_json(indent=2))

```

## Speaker Functions


### Built-in Functions

```python
def round_robin(history: List[str], agent: Agent) -> bool:
    """
    Enables agents to speak in turns.
    Returns True for each agent in sequence.
    """
    return True

def expertise_based(history: List[str], agent: Agent) -> bool:
    """
    Enables agents to speak based on their expertise.
    Returns True if agent's role matches conversation context.
    """
    return agent.system_prompt.lower() in history[-1].lower() if history else True

def random_selection(history: List[str], agent: Agent) -> bool:
    """
    Randomly selects speaking agents.
    Returns True/False with 50% probability.
    """
    import random
    return random.choice([True, False])

def most_recent(history: List[str], agent: Agent) -> bool:
    """
    Enables agents to respond to their mentions.
    Returns True if agent was last speaker.
    """
    return agent.agent_name == history[-1].split(":")[0].strip() if history else True
```

### Custom Speaker Function Example

```python
def custom_speaker(history: List[str], agent: Agent) -> bool:
    """
    Custom speaker function with complex logic.
    
    Args:
        history: Previous conversation messages
        agent: Current agent being evaluated
        
    Returns:
        bool: Whether agent should speak
    """
    # No history - let everyone speak
    if not history:
        return True
        
    last_message = history[-1].lower()
    
    # Check for agent expertise keywords
    expertise_relevant = any(
        keyword in last_message 
        for keyword in agent.expertise_keywords
    )
    
    # Check for direct mentions
    mentioned = agent.agent_name.lower() in last_message
    
    # Check if agent hasn't spoken recently
    not_recent_speaker = not any(
        agent.agent_name in msg 
        for msg in history[-3:]
    )
    
    return expertise_relevant or mentioned or not_recent_speaker

# Usage
chat = GroupChat(
    agents=[agent1, agent2],
    speaker_fn=custom_speaker
)
```

## Advanced Examples

### Multi-Agent Analysis Team

```python
# Create specialized agents
data_analyst = Agent(
    agent_name="Data-Analyst",
    system_prompt="You analyze numerical data and patterns",
    model_name="gpt-4.1",
)

market_expert = Agent(
    agent_name="Market-Expert",
    system_prompt="You provide market insights and trends",
    model_name="gpt-4.1",
)

strategy_advisor = Agent(
    agent_name="Strategy-Advisor",
    system_prompt="You formulate strategic recommendations",
    model_name="gpt-4.1",
)

# Create analysis team
analysis_team = GroupChat(
    name="Market Analysis Team",
    description="Comprehensive market analysis group",
    agents=[data_analyst, market_expert, strategy_advisor],
    speaker_fn=expertise_based,
    max_loops=15
)

# Run complex analysis
history = analysis_team.run("""
    Analyze the current market conditions:
    1. Identify key trends
    2. Evaluate risks
    3. Recommend investment strategy
""")
```

### Parallel Processing

```python
# Define multiple analysis tasks
tasks = [
    "Analyze tech sector trends",
    "Evaluate real estate market",
    "Review commodity prices",
    "Assess global economic indicators"
]

# Run tasks concurrently
histories = chat.concurrent_run(tasks)

# Process results
for task, history in zip(tasks, histories):
    print(f"\nAnalysis for: {task}")
    for turn in history.turns:
        for response in turn.responses:
            print(f"{response.agent_name}: {response.message}")
```

## Best Practices

| Category            | Recommendations                                                                                   |
|---------------------|--------------------------------------------------------------------------------------------------|
| **Agent Design**    | - Give agents clear, specific roles<br>- Use detailed system prompts<br>- Set appropriate context lengths<br>- Enable retries for reliability |
| **Speaker Functions** | - Match function to use case<br>- Consider conversation flow<br>- Handle edge cases<br>- Add appropriate logging |
| **Error Handling**  | - Use try-except blocks<br>- Log errors appropriately<br>- Implement retry logic<br>- Provide fallback responses |
| **Performance**     | - Use concurrent processing for multiple tasks<br>- Monitor context lengths<br>- Implement proper cleanup<br>- Cache responses when appropriate |

## API Reference

### GroupChat Methods

| Method | Description | Arguments | Returns |
|--------|-------------|-----------|---------|
| run | Run single conversation | task: str | ChatHistory |
| batched_run | Run multiple sequential tasks | tasks: List[str] | List[ChatHistory] |
| concurrent_run | Run multiple parallel tasks | tasks: List[str] | List[ChatHistory] |
| get_recent_messages | Get recent messages | n: int = 3 | List[str] |

### Agent Methods

| Method | Description | Returns |
|--------|-------------|---------|
| run | Process single task | str |
| generate_response | Generate LLM response | str |
| save_context | Save conversation context | None |

--------------------------------------------------

# File: swarms/structs/heavy_swarm.md

# HeavySwarm Documentation

HeavySwarm is a sophisticated multi-agent orchestration system that decomposes complex tasks into specialized questions and executes them using four specialized agents: Research, Analysis, Alternatives, and Verification. The results are then synthesized into a comprehensive response.

Inspired by X.AI's Grok 4 heavy implementation, HeavySwarm provides robust task analysis through intelligent question generation, parallel execution, and comprehensive synthesis with real-time progress monitoring.

## Architecture

### System Design

The HeavySwarm follows a structured 5-phase workflow:

1. **Task Decomposition**: Complex tasks are broken down into specialized questions
2. **Question Generation**: AI-powered generation of role-specific questions
3. **Parallel Execution**: Four specialized agents work concurrently
4. **Result Collection**: Outputs are gathered and validated
5. **Synthesis**: Integration into a comprehensive final response

### Agent Specialization

- **Research Agent**: Comprehensive information gathering and synthesis
- **Analysis Agent**: Pattern recognition and statistical analysis
- **Alternatives Agent**: Creative problem-solving and strategic options
- **Verification Agent**: Validation, feasibility assessment, and quality assurance
- **Synthesis Agent**: Multi-perspective integration and executive reporting

## Architecture Diagram

```mermaid
graph TB
    subgraph "HeavySwarm Architecture"
        A[Input Task] --> B[Question Generation Agent]
        B --> C[Task Decomposition]
        
        C --> D[Research Agent]
        C --> E[Analysis Agent]
        C --> F[Alternatives Agent]
        C --> G[Verification Agent]
        
        D --> H[Parallel Execution Engine]
        E --> H
        F --> H
        G --> H
        
        H --> I[Result Collection]
        I --> J[Synthesis Agent]
        J --> K[Comprehensive Report]
        
        subgraph "Monitoring & Control"
            L[Rich Dashboard]
            M[Progress Tracking]
            N[Error Handling]
            O[Timeout Management]
        end
        
        H --> L
        H --> M
        H --> N
        H --> O
    end
    
    subgraph "Agent Specializations"
        D --> D1[Information Gathering<br/>Market Research<br/>Data Collection]
        E --> E1[Statistical Analysis<br/>Pattern Recognition<br/>Predictive Modeling]
        F --> F1[Creative Solutions<br/>Strategic Options<br/>Innovation Ideation]
        G --> G1[Fact Checking<br/>Feasibility Assessment<br/>Quality Assurance]
    end
    
    style A fill:#ff6b6b
    style K fill:#4ecdc4
    style H fill:#45b7d1
    style J fill:#96ceb4
```

## Installation

```bash
pip install swarms
```

## Quick Start

```python
from swarms import HeavySwarm

# Initialize the swarm
swarm = HeavySwarm(
    name="MarketAnalysisSwarm",
    description="Financial market analysis swarm",
    question_agent_model_name="gpt-4o-mini",
    worker_model_name="gpt-4o-mini",
    show_dashboard=True,
    verbose=True
)

# Execute analysis
result = swarm.run("Analyze the current cryptocurrency market trends and investment opportunities")
print(result)
```

## API Reference

### HeavySwarm Class

#### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `str` | `"HeavySwarm"` | Identifier name for the swarm instance |
| `description` | `str` | `"A swarm of agents..."` | Description of the swarm's purpose |
| `agents` | `List[Agent]` | `None` | Pre-configured agent list (unused - agents created internally) |
| `timeout` | `int` | `300` | Maximum execution time per agent in seconds |
| `aggregation_strategy` | `str` | `"synthesis"` | Strategy for result aggregation |
| `loops_per_agent` | `int` | `1` | Number of execution loops per agent |
| `question_agent_model_name` | `str` | `"gpt-4o-mini"` | Model for question generation |
| `worker_model_name` | `str` | `"gpt-4o-mini"` | Model for specialized worker agents |
| `verbose` | `bool` | `False` | Enable detailed logging output |
| `max_workers` | `int` | `int(os.cpu_count() * 0.9)` | Maximum concurrent workers |
| `show_dashboard` | `bool` | `False` | Enable rich dashboard visualization |
| `agent_prints_on` | `bool` | `False` | Enable individual agent output printing |

#### Methods

##### `run(task: str, img: str = None) -> str`

Execute the complete HeavySwarm orchestration flow.

**Parameters:**

- `task` (str): The main task to analyze and decompose

- `img` (str, optional): Image input for visual analysis tasks

**Returns:**
- `str`: Comprehensive final analysis from synthesis agent

**Example:**
```python
result = swarm.run("Develop a go-to-market strategy for a new SaaS product")
```


## Real-World Applications

### Financial Services

```python
# Market Analysis
swarm = HeavySwarm(
    name="FinanceSwarm",
    worker_model_name="gpt-4o",
    show_dashboard=True
)

result = swarm.run("""
Analyze the impact of recent Federal Reserve policy changes on:
1. Bond markets and yield curves
2. Equity market valuations
3. Currency exchange rates
4. Provide investment recommendations for institutional portfolios
""")
```

### Use-cases

| Use Case                                   | Description                                 |
|---------------------------------------------|---------------------------------------------|
| Portfolio optimization and risk assessment  | Optimize asset allocation and assess risks  |
| Market trend analysis and forecasting       | Analyze and predict market movements        |
| Regulatory compliance evaluation            | Evaluate adherence to financial regulations |
| Investment strategy development             | Develop and refine investment strategies    |
| Credit risk analysis and modeling           | Analyze and model credit risk               |


-------


### Healthcare & Life Sciences

```python
# Clinical Research Analysis
swarm = HeavySwarm(
    name="HealthcareSwarm",
    worker_model_name="gpt-4o",
    timeout=600,
    loops_per_agent=2
)

result = swarm.run("""
Evaluate the potential of AI-driven personalized medicine:
1. Current technological capabilities and limitations
2. Regulatory landscape and approval pathways
3. Market opportunities and competitive analysis
4. Implementation strategies for healthcare systems
""")
```

----

**Use Cases:**

| Use Case                              | Description                                 |
|----------------------------------------|---------------------------------------------|
| Drug discovery and development analysis| Analyze and accelerate drug R&D processes   |
| Clinical trial optimization            | Improve design and efficiency of trials     |
| Healthcare policy evaluation           | Assess and inform healthcare policies       |
| Medical device market analysis         | Evaluate trends and opportunities in devices|
| Patient outcome prediction modeling    | Predict and model patient health outcomes   |

---


### Technology & Innovation

```python
# Tech Strategy Analysis
swarm = HeavySwarm(
    name="TechSwarm",
    worker_model_name="gpt-4o",
    show_dashboard=True,
    verbose=True
)

result = swarm.run("""
Assess the strategic implications of quantum computing adoption:
1. Technical readiness and hardware developments
2. Industry applications and use cases
3. Competitive landscape and key players
4. Investment and implementation roadmap
""")
```

**Use Cases:**

| Use Case                          | Description                                 |
|------------------------------------|---------------------------------------------|
| Technology roadmap development     | Plan and prioritize technology initiatives  |
| Competitive intelligence gathering | Analyze competitors and market trends       |
| Innovation pipeline analysis       | Evaluate and manage innovation projects     |
| Digital transformation strategy    | Develop and implement digital strategies    |
| Emerging technology assessment     | Assess new and disruptive technologies      |

### Manufacturing & Supply Chain

```python
# Supply Chain Optimization
swarm = HeavySwarm(
    name="ManufacturingSwarm",
    worker_model_name="gpt-4o",
    max_workers=8
)

result = swarm.run("""
Optimize global supply chain resilience:
1. Risk assessment and vulnerability analysis
2. Alternative sourcing strategies
3. Technology integration opportunities
4. Cost-benefit analysis of proposed changes
""")
```

**Use Cases:**

| Use Case                         | Description                                 |
|----------------------------------|---------------------------------------------|
| Supply chain risk management     | Identify and mitigate supply chain risks    |
| Manufacturing process optimization | Improve efficiency and productivity         |
| Quality control system design    | Develop systems to ensure product quality   |
| Sustainability impact assessment | Evaluate environmental and social impacts   |
| Logistics network optimization   | Enhance logistics and distribution networks |

## Advanced Configuration

### Custom Agent Configuration

```python
# High-performance configuration
swarm = HeavySwarm(
    name="HighPerformanceSwarm",
    question_agent_model_name="gpt-4o",
    worker_model_name="gpt-4o",
    timeout=900,
    loops_per_agent=3,
    max_workers=12,
    show_dashboard=True,
    verbose=True
)
```


## Troubleshooting

| Issue                   | Solution                                                      |
|-------------------------|---------------------------------------------------------------|
| **Agent Timeout**       | Increase timeout parameter or reduce task complexity          |
| **Model Rate Limits**   | Implement backoff strategies or use different models          |
| **Memory Usage**        | Monitor system resources with large-scale operations          |
| **Dashboard Performance** | Disable dashboard for batch processing                      |

## Contributing

HeavySwarm is part of the Swarms ecosystem. Contributions are welcome for:

- New agent specializations

- Performance optimizations

- Integration capabilities

- Documentation improvements


## Acknowledgments

- Inspired by X.AI's Grok heavy implementation

- Built on the Swarms framework

- Utilizes Rich for dashboard visualization

- Powered by advanced language models



--------------------------------------------------

# File: swarms/structs/hhcs.md

# Hybrid Hierarchical-Cluster Swarm [HHCS]

The Hybrid Hierarchical-Cluster Swarm (HHCS) is an advanced AI orchestration architecture that combines hierarchical decision-making with parallel processing capabilities. HHCS enables complex task solving by dynamically routing tasks to specialized agent swarms based on their expertise and capabilities.

## Purpose

HHCS addresses the challenge of efficiently solving diverse and complex tasks by:

- Intelligently routing tasks to the most appropriate specialized swarms

- Enabling parallel processing of multifaceted problems

- Maintaining a clear hierarchy for effective decision-making

- Combining outputs from multiple specialized agents for comprehensive solutions

## Key Features

- **Router-based task distribution**: Central router agent analyzes incoming tasks and directs them to appropriate specialized swarms

- **Hybrid architecture**: Combines hierarchical control with clustered specialization

- **Parallel processing**: Multiple swarms can work simultaneously on different aspects of complex tasks

- **Flexible swarm types**: Supports both sequential and concurrent workflows within swarms

- **Comprehensive result aggregation**: Collects and combines outputs from all contributing swarms


## Diagram

The HHCS architecture follows a hierarchical structure with the router agent at the top level, specialized swarms at the middle level, and individual agents at the bottom level.


```mermaid
flowchart TD
    Start([Task Input]) --> RouterAgent[Router Agent]
    RouterAgent --> Analysis{Task Analysis}
    
    Analysis -->|Analyze Requirements| Selection[Swarm Selection]
    Selection -->|Select Best Swarm| Route[Route Task]
    
    Route --> Swarm1[Swarm 1]
    Route --> Swarm2[Swarm 2]
    Route --> SwarmN[Swarm N...]
    
    Swarm1 -->|Process Task| Result1[Swarm 1 Output]
    Swarm2 -->|Process Task| Result2[Swarm 2 Output]
    SwarmN -->|Process Task| ResultN[Swarm N Output]
    
    Result1 --> Conversation[Conversation History]
    Result2 --> Conversation
    ResultN --> Conversation
    
    Conversation --> Output([Final Output])
    
    subgraph Router Decision Process
        Analysis
        Selection
    end
    
    subgraph Parallel Task Processing
        Swarm1
        Swarm2
        SwarmN
    end
    
    subgraph Results Collection
        Result1
        Result2
        ResultN
        Conversation
    end
```


## `HybridHierarchicalClusterSwarm` Constructor Arguments

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | string | "Hybrid Hierarchical-Cluster Swarm" | The name of the swarm instance |
| `description` | string | "A swarm that uses a hybrid hierarchical-peer model to solve complex tasks." | Brief description of the swarm's functionality |
| `swarms` | List[SwarmRouter] | [] | List of available swarm routers |
| `max_loops` | integer | 1 | Maximum number of processing loops |
| `output_type` | string | "list" | Format for output (e.g., "list", "json") |
| `router_agent_model_name` | string | "gpt-4o-mini" | LLM model used by the router agent |

## Methods

| Method | Parameters | Return Type | Description |
|--------|------------|-------------|-------------|
| `run` | `task` (str) | str | Processes a single task through the swarm system |
| `batched_run` | `tasks` (List[str]) | List[str] | Processes multiple tasks in parallel |
| `find_swarm_by_name` | `swarm_name` (str) | SwarmRouter | Retrieves a swarm by its name |
| `route_task` | `swarm_name` (str), `task_description` (str) | None | Routes a task to a specific swarm |
| `get_swarms_info` | None | str | Returns formatted information about all available swarms |


## Full Example

```python

from swarms import Agent, SwarmRouter
from swarms.structs.hybrid_hiearchical_peer_swarm import (
    HybridHierarchicalClusterSwarm,
)


# Core Legal Agent Definitions with short, simple prompts
litigation_agent = Agent(
    agent_name="Litigator",
    system_prompt="You handle lawsuits. Analyze facts, build arguments, and develop case strategy.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

corporate_agent = Agent(
    agent_name="Corporate-Attorney",
    system_prompt="You handle business law. Advise on corporate structure, governance, and transactions.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

ip_agent = Agent(
    agent_name="IP-Attorney",
    system_prompt="You protect intellectual property. Handle patents, trademarks, copyrights, and trade secrets.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

employment_agent = Agent(
    agent_name="Employment-Attorney",
    system_prompt="You handle workplace matters. Address hiring, termination, discrimination, and labor issues.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

paralegal_agent = Agent(
    agent_name="Paralegal",
    system_prompt="You assist attorneys. Conduct research, draft documents, and organize case files.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

doc_review_agent = Agent(
    agent_name="Document-Reviewer",
    system_prompt="You examine documents. Extract key information and identify relevant content.",
    model_name="groq/deepseek-r1-distill-qwen-32b",
    max_loops=1,
)

# Practice Area Swarm Routers
litigation_swarm = SwarmRouter(
    name="litigation-practice",
    description="Handle all aspects of litigation",
    agents=[litigation_agent, paralegal_agent, doc_review_agent],
    swarm_type="SequentialWorkflow",
)

corporate_swarm = SwarmRouter(
    name="corporate-practice",
    description="Handle business and corporate legal matters",
    agents=[corporate_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

ip_swarm = SwarmRouter(
    name="ip-practice",
    description="Handle intellectual property matters",
    agents=[ip_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

employment_swarm = SwarmRouter(
    name="employment-practice",
    description="Handle employment and labor law matters",
    agents=[employment_agent, paralegal_agent],
    swarm_type="SequentialWorkflow",
)

# Cross-functional Swarm Router
m_and_a_swarm = SwarmRouter(
    name="mergers-acquisitions",
    description="Handle mergers and acquisitions",
    agents=[
        corporate_agent,
        ip_agent,
        employment_agent,
        doc_review_agent,
    ],
    swarm_type="ConcurrentWorkflow",
)

dispute_swarm = SwarmRouter(
    name="dispute-resolution",
    description="Handle complex disputes requiring multiple specialties",
    agents=[litigation_agent, corporate_agent, doc_review_agent],
    swarm_type="ConcurrentWorkflow",
)


hybrid_hiearchical_swarm = HybridHierarchicalClusterSwarm(
    name="hybrid-hiearchical-swarm",
    description="A hybrid hiearchical swarm that uses a hybrid hiearchical peer model to solve complex tasks.",
    swarms=[
        litigation_swarm,
        corporate_swarm,
        ip_swarm,
        employment_swarm,
        m_and_a_swarm,
        dispute_swarm,
    ],
    max_loops=1,
    router_agent_model_name="gpt-4o-mini",
)


if __name__ == "__main__":
    hybrid_hiearchical_swarm.run(
        "What is the best way to file for a patent? for ai technology "
    )

```

--------------------------------------------------

# File: swarms/structs/hierarchical_structured_communication_framework.md

# Hierarchical Structured Communication Framework

The Hierarchical Structured Communication Framework implements the "Talk Structurally, Act Hierarchically" approach for LLM multi-agent systems, based on the research paper arXiv:2502.11098.

## Overview

This framework provides:
- **Structured Communication Protocol** with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij)
- **Hierarchical Evaluation System** with supervisor coordination
- **Specialized Agent Classes** for different roles
- **Main Swarm Orchestrator** for workflow management

## Key Components

### Agent Classes
- `HierarchicalStructuredCommunicationGenerator` - Creates initial content
- `HierarchicalStructuredCommunicationEvaluator` - Evaluates content quality
- `HierarchicalStructuredCommunicationRefiner` - Improves content based on feedback
- `HierarchicalStructuredCommunicationSupervisor` - Coordinates workflow

### Main Framework
- `HierarchicalStructuredCommunicationFramework` - Main orchestrator class
- `HierarchicalStructuredCommunicationSwarm` - Convenience alias

## Quick Start

```python
from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework,
    HierarchicalStructuredCommunicationGenerator,
    HierarchicalStructuredCommunicationEvaluator,
    HierarchicalStructuredCommunicationRefiner,
    HierarchicalStructuredCommunicationSupervisor
)

# Create specialized agents
generator = HierarchicalStructuredCommunicationGenerator(
    agent_name="ContentGenerator"
)

evaluator = HierarchicalStructuredCommunicationEvaluator(
    agent_name="QualityEvaluator"
)

refiner = HierarchicalStructuredCommunicationRefiner(
    agent_name="ContentRefiner"
)

supervisor = HierarchicalStructuredCommunicationSupervisor(
    agent_name="WorkflowSupervisor"
)

# Create the framework
framework = HierarchicalStructuredCommunicationFramework(
    name="MyFramework",
    supervisor=supervisor,
    generators=[generator],
    evaluators=[evaluator],
    refiners=[refiner],
    max_loops=3
)

# Run the workflow
result = framework.run("Create a comprehensive analysis of AI trends in 2024")
```

## Basic Usage

```python
from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework,
    HierarchicalStructuredCommunicationGenerator,
    HierarchicalStructuredCommunicationEvaluator,
    HierarchicalStructuredCommunicationRefiner
)

# Create agents with custom names
generator = HierarchicalStructuredCommunicationGenerator(agent_name="ContentGenerator")
evaluator = HierarchicalStructuredCommunicationEvaluator(agent_name="QualityEvaluator")
refiner = HierarchicalStructuredCommunicationRefiner(agent_name="ContentRefiner")

# Create framework with default supervisor
framework = HierarchicalStructuredCommunicationFramework(
    generators=[generator],
    evaluators=[evaluator],
    refiners=[refiner],
    max_loops=3,
    verbose=True
)

# Execute task
result = framework.run("Write a detailed report on renewable energy technologies")
print(result["final_result"])
```

## Advanced Configuration

```python
from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework
)

# Create framework with custom configuration
framework = HierarchicalStructuredCommunicationFramework(
    name="AdvancedFramework",
    max_loops=5,
    enable_structured_communication=True,
    enable_hierarchical_evaluation=True,
    shared_memory=True,
    model_name="gpt-4o-mini",
    verbose=True
)

# Run with custom parameters
result = framework.run(
    "Analyze the impact of climate change on global agriculture",
    max_loops=3
)
```

## Integration with Other Swarms

```python
from swarms.structs.hierarchical_structured_communication_framework import (
    HierarchicalStructuredCommunicationFramework
)
from swarms.structs import AutoSwarmBuilder

# Use HierarchicalStructuredCommunicationFramework for content generation
framework = HierarchicalStructuredCommunicationFramework(
    max_loops=2,
    verbose=True
)

# Integrate with AutoSwarmBuilder
builder = AutoSwarmBuilder()
swarm = builder.create_swarm(
    swarm_type="HierarchicalStructuredCommunicationFramework",
    task="Generate a comprehensive business plan"
)
```

## API Reference

### HierarchicalStructuredCommunicationFramework

The main orchestrator class that implements the complete framework.

#### Parameters
- `name` (str): Name of the framework
- `supervisor`: Main supervisor agent
- `generators` (List): List of generator agents
- `evaluators` (List): List of evaluator agents
- `refiners` (List): List of refiner agents
- `max_loops` (int): Maximum refinement loops
- `enable_structured_communication` (bool): Enable structured protocol
- `enable_hierarchical_evaluation` (bool): Enable hierarchical evaluation
- `verbose` (bool): Enable verbose logging

#### Methods
- `run(task)`: Execute complete workflow
- `step(task)`: Execute single workflow step
- `send_structured_message()`: Send structured communication
- `run_hierarchical_evaluation()`: Run evaluation system

## Contributing

Contributions to improve the Hierarchical Structured Communication Framework are welcome! Please:

1. Follow the existing code style and patterns
2. Add comprehensive tests for new features
3. Update documentation for any API changes
4. Ensure all imports use the correct module paths

## License

This framework is part of the Swarms project and follows the same licensing terms. 


--------------------------------------------------

# File: swarms/structs/hierarchical_swarm.md

# `HierarchicalSwarm`

The `HierarchicalSwarm` is a sophisticated multi-agent orchestration system that implements a hierarchical workflow pattern. It consists of a director agent that coordinates and distributes tasks to specialized worker agents, creating a structured approach to complex problem-solving.

## Overview

The Hierarchical Swarm follows a clear workflow pattern:

1. **Task Reception**: User provides a task to the swarm
2. **Planning**: Director creates a comprehensive plan and distributes orders to agents
3. **Execution**: Individual agents execute their assigned tasks
4. **Feedback Loop**: Director evaluates results and issues new orders if needed (up to `max_loops`)
5. **Context Preservation**: All conversation history and context is maintained throughout the process

## Architecture

```mermaid
graph TD
    A[User Task] --> B[Director Agent]
    B --> C[Create Plan & Orders]
    C --> D[Distribute to Agents]
    D --> E[Agent 1]
    D --> F[Agent 2]
    D --> G[Agent N]
    E --> H[Execute Task]
    F --> H
    G --> H
    H --> I[Report Results]
    I --> J[Director Evaluation]
    J --> K{More Loops?}
    K -->|Yes| C
    K -->|No| L[Final Output]
```

## Key Features

- **Hierarchical Coordination**: Director agent orchestrates all operations
- **Specialized Agents**: Each agent has specific expertise and responsibilities
- **Iterative Refinement**: Multiple feedback loops for improved results
- **Context Preservation**: Full conversation history maintained
- **Flexible Output Formats**: Support for various output types (dict, str, list)
- **Comprehensive Logging**: Detailed logging for debugging and monitoring

## `HierarchicalSwarm` Constructor

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | `str` | `"HierarchicalAgentSwarm"` | The name of the swarm instance |
| `description` | `str` | `"Distributed task swarm"` | Brief description of the swarm's functionality |
| `director` | `Optional[Union[Agent, Callable, Any]]` | `None` | The director agent that orchestrates tasks |
| `agents` | `List[Union[Agent, Callable, Any]]` | `None` | List of worker agents in the swarm |
| `max_loops` | `int` | `1` | Maximum number of feedback loops between director and agents |
| `output_type` | `OutputType` | `"dict-all-except-first"` | Format for output (dict, str, list) |
| `feedback_director_model_name` | `str` | `"gpt-4o-mini"` | Model name for feedback director |
| `director_name` | `str` | `"Director"` | Name of the director agent |
| `director_model_name` | `str` | `"gpt-4o-mini"` | Model name for the director agent |
| `verbose` | `bool` | `False` | Enable detailed logging |
| `add_collaboration_prompt` | `bool` | `True` | Add collaboration prompts to agents |
| `planning_director_agent` | `Optional[Union[Agent, Callable, Any]]` | `None` | Optional planning agent for enhanced planning |

## Core Methods

### `run(task, img=None, *args, **kwargs)`

Executes the hierarchical swarm for a specified number of feedback loops, processing the task through multiple iterations for refinement and improvement.

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `task` | `str` | **Required** | The initial task to be processed by the swarm |
| `img` | `str` | `None` | Optional image input for the agents |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

#### Returns

| Type | Description |
|------|-------------|
| `Any` | The formatted conversation history as output based on `output_type` |

#### Example

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized agents
research_agent = Agent(
    agent_name="Research-Specialist",
    agent_description="Expert in market research and analysis",
    model_name="gpt-4o",
)

financial_agent = Agent(
    agent_name="Financial-Analyst",
    agent_description="Specialist in financial analysis and valuation",
    model_name="gpt-4o",
)

# Initialize the hierarchical swarm
swarm = HierarchicalSwarm(
    name="Financial-Analysis-Swarm",
    description="A hierarchical swarm for comprehensive financial analysis",
    agents=[research_agent, financial_agent],
    max_loops=2,
    verbose=True,
)

# Execute a complex task
task = "Analyze the market potential for Tesla (TSLA) stock"
result = swarm.run(task=task)
print(result)
```

### `step(task, img=None, *args, **kwargs)`

Runs a single step of the hierarchical swarm, executing one complete cycle of planning, distribution, execution, and feedback.

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `task` | `str` | **Required** | The task to be executed in this step |
| `img` | `str` | `None` | Optional image input for the agents |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

#### Returns

| Type | Description |
|------|-------------|
| `str` | Feedback from the director based on agent outputs |

#### Example

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create development agents
frontend_agent = Agent(
    agent_name="Frontend-Developer",
    agent_description="Expert in React and modern web development",
    model_name="gpt-4o",
)

backend_agent = Agent(
    agent_name="Backend-Developer",
    agent_description="Specialist in Node.js and API development",
    model_name="gpt-4o",
)

# Initialize the swarm
swarm = HierarchicalSwarm(
    name="Development-Swarm",
    description="A hierarchical swarm for software development",
    agents=[frontend_agent, backend_agent],
    max_loops=1,
    verbose=True,
)

# Execute a single step
task = "Create a simple web app for file upload and download"
feedback = swarm.step(task=task)
print("Director Feedback:", feedback)
```

### `batched_run(tasks, img=None, *args, **kwargs)`

Executes the hierarchical swarm for a list of tasks, processing each task through the complete workflow.

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `tasks` | `List[str]` | **Required** | List of tasks to be processed |
| `img` | `str` | `None` | Optional image input for the agents |
| `*args` | `Any` | - | Additional positional arguments |
| `**kwargs` | `Any` | - | Additional keyword arguments |

#### Returns

| Type | Description |
|------|-------------|
| `List[Any]` | List of results for each task |

#### Example

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create analysis agents
market_agent = Agent(
    agent_name="Market-Analyst",
    agent_description="Expert in market analysis and trends",
    model_name="gpt-4o",
)

technical_agent = Agent(
    agent_name="Technical-Analyst",
    agent_description="Specialist in technical analysis and patterns",
    model_name="gpt-4o",
)

# Initialize the swarm
swarm = HierarchicalSwarm(
    name="Analysis-Swarm",
    description="A hierarchical swarm for comprehensive analysis",
    agents=[market_agent, technical_agent],
    max_loops=2,
    verbose=True,
)

# Execute multiple tasks
tasks = [
    "Analyze Apple (AAPL) stock performance",
    "Evaluate Microsoft (MSFT) market position",
    "Assess Google (GOOGL) competitive landscape"
]

results = swarm.batched_run(tasks=tasks)
for i, result in enumerate(results):
    print(f"Task {i+1} Result:", result)
```

## Advanced Usage Examples

### Financial Analysis Swarm

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized financial agents
market_research_agent = Agent(
    agent_name="Market-Research-Specialist",
    agent_description="Expert in market research, trend analysis, and competitive intelligence",
    system_prompt="""You are a senior market research specialist with expertise in:
    - Market trend analysis and forecasting
    - Competitive landscape assessment
    - Consumer behavior analysis
    - Industry report generation
    - Market opportunity identification
    - Risk assessment and mitigation strategies""",
    model_name="claude-3-sonnet-20240229",
)

financial_analyst_agent = Agent(
    agent_name="Financial-Analysis-Expert",
    agent_description="Specialist in financial statement analysis, valuation, and investment research",
    system_prompt="""You are a senior financial analyst with deep expertise in:
    - Financial statement analysis (income statement, balance sheet, cash flow)
    - Valuation methodologies (DCF, comparable company analysis, precedent transactions)
    - Investment research and due diligence
    - Financial modeling and forecasting
    - Risk assessment and portfolio analysis
    - ESG (Environmental, Social, Governance) analysis""",
    model_name="claude-3-sonnet-20240229",
)

# Initialize the hierarchical swarm
financial_analysis_swarm = HierarchicalSwarm(
    name="Financial-Analysis-Hierarchical-Swarm",
    description="A hierarchical swarm for comprehensive financial analysis with specialized agents",
    agents=[market_research_agent, financial_analyst_agent],
    max_loops=2,
    verbose=True,
)

# Execute financial analysis
task = "Conduct a comprehensive analysis of Tesla (TSLA) stock including market position, financial health, and investment potential"
result = financial_analysis_swarm.run(task=task)
print(result)
```

### Development Department Swarm

```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized development agents
frontend_developer_agent = Agent(
    agent_name="Frontend-Developer",
    agent_description="Senior frontend developer expert in modern web technologies and user experience",
    system_prompt="""You are a senior frontend developer with expertise in:
    - Modern JavaScript frameworks (React, Vue, Angular)
    - TypeScript and modern ES6+ features
    - CSS frameworks and responsive design
    - State management (Redux, Zustand, Context API)
    - Web performance optimization
    - Accessibility (WCAG) and SEO best practices""",
    model_name="claude-3-sonnet-20240229",
)

backend_developer_agent = Agent(
    agent_name="Backend-Developer",
    agent_description="Senior backend developer specializing in server-side development and API design",
    system_prompt="""You are a senior backend developer with expertise in:
    - Server-side programming languages (Python, Node.js, Java, Go)
    - Web frameworks (Django, Flask, Express, Spring Boot)
    - Database design and optimization (SQL, NoSQL)
    - API design and REST/GraphQL implementation
    - Authentication and authorization systems
    - Microservices architecture and containerization""",
    model_name="claude-3-sonnet-20240229",
)

# Initialize the development swarm
development_department_swarm = HierarchicalSwarm(
    name="Autonomous-Development-Department",
    description="A fully autonomous development department with specialized agents",
    agents=[frontend_developer_agent, backend_developer_agent],
    max_loops=3,
    verbose=True,
)

# Execute development project
task = "Create a simple web app that allows users to upload a file and then download it. The app should be built with React and Node.js."
result = development_department_swarm.run(task=task)
print(result)
```

## Output Types

The `HierarchicalSwarm` supports various output formats through the `output_type` parameter:

| Output Type | Description | Use Case |
|-------------|-------------|----------|
| `"dict-all-except-first"` | Returns all conversation history as a dictionary, excluding the first message | Default format for comprehensive analysis |
| `"dict"` | Returns conversation history as a dictionary | When you need structured data |
| `"str"` | Returns conversation history as a string | For simple text output |
| `"list"` | Returns conversation history as a list | For sequential processing |

## Best Practices

1. **Agent Specialization**: Create agents with specific, well-defined expertise areas
2. **Clear Task Descriptions**: Provide detailed, actionable task descriptions
3. **Appropriate Loop Count**: Set `max_loops` based on task complexity (1-3 for most tasks)
4. **Verbose Logging**: Enable verbose mode during development for debugging
5. **Context Preservation**: Leverage the built-in conversation history for continuity
6. **Error Handling**: Implement proper error handling for production use

## Error Handling

The `HierarchicalSwarm` includes comprehensive error handling with detailed logging. Common issues and solutions:

- **No Agents**: Ensure at least one agent is provided
- **Invalid Director**: Verify the director agent is properly configured
- **Max Loops**: Set `max_loops` to a value greater than 0
- **Model Issues**: Check that all agents have valid model configurations

## Performance Considerations

- **Loop Optimization**: Balance between thoroughness and performance with `max_loops`
- **Agent Count**: More agents increase coordination overhead
- **Model Selection**: Choose appropriate models for your use case and budget
- **Verbose Mode**: Disable verbose logging in production for better performance 

--------------------------------------------------

# File: swarms/structs/image_batch_agent.md

# ImageAgentBatchProcessor Documentation

## Overview

The `ImageAgentBatchProcessor` is a high-performance parallel image processing system designed for running AI agents on multiple images concurrently. It provides robust error handling, logging, and flexible configuration options.

## Installation

```bash
pip install swarms
```

## Class Arguments

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| agents | Union[Agent, List[Agent], Callable, List[Callable]] | Required | Single agent or list of agents to process images |
| max_workers | int | None | Maximum number of parallel workers (defaults to 95% of CPU cores) |
| supported_formats | List[str] | ['.jpg', '.jpeg', '.png'] | List of supported image file extensions |

## Methods

### run()

**Description**: Main method for processing multiple images in parallel with configured agents. Can handle single images, multiple images, or entire directories.

**Arguments**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image_paths | Union[str, List[str], Path] | Yes | Single image path, list of paths, or directory path |
| tasks | Union[str, List[str]] | Yes | Single task or list of tasks to perform on each image |

**Returns**: List[Dict[str, Any]] - List of processing results for each image

**Example**:

```python
from swarms import Agent
from swarms.structs import ImageAgentBatchProcessor
from pathlib import Path

# Initialize agent and processor
agent = Agent(api_key="your-api-key", model="gpt-4-vision")
processor = ImageAgentBatchProcessor(agents=agent)

# Example 1: Process single image
results = processor.run(
    image_paths="path/to/image.jpg",
    tasks="Describe this image"
)

# Example 2: Process multiple images
results = processor.run(
    image_paths=["image1.jpg", "image2.jpg"],
    tasks=["Describe objects", "Identify colors"]
)

# Example 3: Process directory
results = processor.run(
    image_paths=Path("./images"),
    tasks="Analyze image content"
)
```

### _validate_image_path()

**Description**: Internal method that validates if an image path exists and has a supported format.

**Arguments**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image_path | Union[str, Path] | Yes | Path to the image file to validate |

**Returns**: Path - Validated Path object

**Example**:
```python

from swarms.structs import ImageAgentBatchProcessor, ImageProcessingError
from pathlib import Path

processor = ImageAgentBatchProcessor(agents=agent)

try:
    validated_path = processor._validate_image_path("image.jpg")
    print(f"Valid image path: {validated_path}")
except ImageProcessingError as e:
    print(f"Invalid image path: {e}")
```

### _process_single_image()

**Description**: Internal method that processes a single image with one agent and one or more tasks.

**Arguments**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| image_path | Path | Yes | Path to the image to process |
| tasks | Union[str, List[str]] | Yes | Tasks to perform on the image |
| agent | Agent | Yes | Agent to use for processing |

**Returns**: Dict[str, Any] - Processing results for the image

**Example**:

```python
from swarms import Agent
from swarms.structs import ImageAgentBatchProcessor
from pathlib import Path

agent = Agent(api_key="your-api-key", model="gpt-4-vision")
processor = ImageAgentBatchProcessor(agents=agent)

try:
    result = processor._process_single_image(
        image_path=Path("image.jpg"),
        tasks=["Describe image", "Identify objects"],
        agent=agent
    )
    print(f"Processing results: {result}")
except Exception as e:
    print(f"Processing failed: {e}")
```

### __call__()

**Description**: Makes the ImageAgentBatchProcessor callable like a function. Redirects to the run() method.

**Arguments**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| *args | Any | No | Variable length argument list passed to run() |
| **kwargs | Any | No | Keyword arguments passed to run() |

**Returns**: List[Dict[str, Any]] - Same as run() method

**Example**:

```python
from swarms import Agent
from swarms.structs import ImageAgentBatchProcessor

# Initialize
agent = Agent(api_key="your-api-key", model="gpt-4-vision")
processor = ImageAgentBatchProcessor(agents=agent)

# Using __call__
results = processor(
    image_paths=["image1.jpg", "image2.jpg"],
    tasks="Describe the image"
)

# This is equivalent to:
results = processor.run(
    image_paths=["image1.jpg", "image2.jpg"],
    tasks="Describe the image"
)
```

## Return Format

The processor returns a list of dictionaries with the following structure:

```python
{
    "image_path": str,          # Path to the processed image
    "results": {               # Results for each task
        "task_name": result,   # Task-specific results
    },
    "processing_time": float   # Processing time in seconds
}
```

## Complete Usage Examples

### 1. Basic Usage with Single Agent

```python
from swarms import Agent
from swarms.structs import ImageAgentBatchProcessor

# Initialize an agent
agent = Agent(
    api_key="your-api-key",
    model="gpt-4-vision"
)

# Create processor
processor = ImageAgentBatchProcessor(agents=agent)

# Process single image
results = processor.run(
    image_paths="path/to/image.jpg",
    tasks="Describe this image in detail"
)
```

### 2. Processing Multiple Images with Multiple Tasks

```python
# Initialize with multiple agents
agent1 = Agent(api_key="key1", model="gpt-4-vision")
agent2 = Agent(api_key="key2", model="claude-3")

processor = ImageAgentBatchProcessor(
    agents=[agent1, agent2],
    supported_formats=['.jpg', '.png', '.webp']
)

# Define multiple tasks
tasks = [
    "Describe the main objects in the image",
    "What is the dominant color?",
    "Identify any text in the image"
]

# Process a directory of images
results = processor.run(
    image_paths="path/to/image/directory",
    tasks=tasks
)

# Process results
for result in results:
    print(f"Image: {result['image_path']}")
    for task, output in result['results'].items():
        print(f"Task: {task}")
        print(f"Result: {output}")
    print(f"Processing time: {result['processing_time']:.2f} seconds")
```

### 3. Custom Error Handling

```python
from swarms.structs import ImageAgentBatchProcessor, ImageProcessingError

try:
    processor = ImageAgentBatchProcessor(agents=agent)
    results = processor.run(
        image_paths=["image1.jpg", "image2.png", "invalid.txt"],
        tasks="Analyze the image"
    )
except ImageProcessingError as e:
    print(f"Image processing failed: {e}")
except InvalidAgentError as e:
    print(f"Agent configuration error: {e}")
```

## Best Practices

| Best Practice | Description |
|--------------|-------------|
| Resource Management | • The processor automatically uses 95% of available CPU cores<br>• For memory-intensive operations, consider reducing `max_workers` |
| Error Handling | • Always wrap processor calls in try-except blocks<br>• Check the results for any error keys |
| Task Design | • Keep tasks focused and specific<br>• Group related tasks together for efficiency |
| Performance Optimization | • Process images in batches for better throughput<br>• Use multiple agents for different types of analysis |

## Limitations

| Limitation | Description |
|------------|-------------|
| File Format Support | Only supports image file formats specified in `supported_formats` |
| Agent Requirements | Requires valid agent configurations |
| Resource Scaling | Memory usage scales with number of concurrent processes |


This documentation provides a comprehensive guide to using the `ImageAgentBatchProcessor`. The class is designed to be both powerful and flexible, allowing for various use cases from simple image analysis to complex multi-agent processing pipelines.


--------------------------------------------------

# File: swarms/structs/index.md

# Introduction to Multi-Agent Collaboration

---

## Benefits of Multi-Agent Collaboration

### Why Multi-Agent Architectures?

Multi-agent systems unlock new levels of intelligence, reliability, and efficiency by enabling agents to work together. Here are the core benefits:

| **Benefit**                       | **Description**                                                                                                      |
|------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| **Reduction of Hallucination**     | Cross-verification between agents ensures more accurate, reliable outputs by reducing hallucination.                 |
| **Extended Memory**                | Agents share knowledge and task history, achieving collective long-term memory for smarter, more adaptive responses. |
| **Specialization & Task Distribution** | Delegating tasks to specialized agents boosts efficiency and quality.                                           |
| **Parallel Processing**            | Multiple agents work simultaneously, greatly increasing speed and throughput.                                        |
| **Scalability & Adaptability**     | Systems can dynamically scale and adapt, maintaining efficiency as demands change.                                  |

---

## Multi-Agent Architectures For Production Deployments

`swarms` provides a variety of powerful, pre-built multi-agent architectures enabling you to orchestrate agents in various ways. Choose the right structure for your specific problem to build efficient and reliable production systems.

| **Architecture** | **Description** | **Best For** |
|---|---|---|
| **[SequentialWorkflow](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)** | Agents execute tasks in a linear chain; one agent's output is the next one's input. | Step-by-step processes like data transformation pipelines, report generation. |
| **[ConcurrentWorkflow](https://docs.swarms.world/en/latest/swarms/structs/concurrent_workflow/)** | Agents run tasks simultaneously for maximum efficiency. | High-throughput tasks like batch processing, parallel data analysis. |
| **[AgentRearrange](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)** | Dynamically maps complex relationships (e.g., `a -> b, c`) between agents. | Flexible and adaptive workflows, task distribution, dynamic routing. |
| **[GraphWorkflow](https://docs.swarms.world/en/latest/swarms/structs/graph_workflow/)** | Orchestrates agents as nodes in a Directed Acyclic Graph (DAG). | Complex projects with intricate dependencies, like software builds. |
| **[MixtureOfAgents (MoA)](https://docs.swarms.world/en/latest/swarms/structs/moa/)** | Utilizes multiple expert agents in parallel and synthesizes their outputs. | Complex problem-solving, achieving state-of-the-art performance through collaboration. |
| **[GroupChat](https://docs.swarms.world/en/latest/swarms/structs/group_chat/)** | Agents collaborate and make decisions through a conversational interface. | Real-time collaborative decision-making, negotiations, brainstorming. |
| **[ForestSwarm](https://docs.swarms.world/en/latest/swarms/structs/forest_swarm/)** | Dynamically selects the most suitable agent or tree of agents for a given task. | Task routing, optimizing for expertise, complex decision-making trees. |
| **[SpreadSheetSwarm](https://docs.swarms.world/en/latest/swarms/structs/spreadsheet_swarm/)** | Manages thousands of agents concurrently, tracking tasks and outputs in a structured format. | Massive-scale parallel operations, large-scale data generation and analysis. |
| **[SwarmRouter](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)** | Universal orchestrator that provides a single interface to run any type of swarm with dynamic selection. | Simplifying complex workflows, switching between swarm strategies, unified multi-agent management. |
| **[HierarchicalSwarm](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)** | Director agent coordinates specialized worker agents in a hierarchy. | Complex, multi-stage tasks, iterative refinement, enterprise workflows. |
| **[Hybrid Hierarchical-Cluster Swarm (HHCS)](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)** | Router agent distributes tasks to specialized swarms for parallel, hierarchical processing. | Enterprise-scale, multi-domain, and highly complex workflows. |

---

### HierarchicalSwarm Example

Hierarchical architectures enable structured, iterative, and scalable problem-solving by combining a director (or router) agent with specialized worker agents or swarms. Below are two key patterns:


```python
from swarms import Agent
from swarms.structs.hiearchical_swarm import HierarchicalSwarm

# Create specialized agents
research_agent = Agent(
    agent_name="Research-Specialist",
    agent_description="Expert in market research and analysis",
    model_name="gpt-4o",
)
financial_agent = Agent(
    agent_name="Financial-Analyst",
    agent_description="Specialist in financial analysis and valuation",
    model_name="gpt-4o",
)

# Initialize the hierarchical swarm
swarm = HierarchicalSwarm(
    name="Financial-Analysis-Swarm",
    description="A hierarchical swarm for comprehensive financial analysis",
    agents=[research_agent, financial_agent],
    max_loops=2,
    verbose=True,
)

# Execute a complex task
result = swarm.run(task="Analyze the market potential for Tesla (TSLA) stock")
print(result)
```

[Full HierarchicalSwarm Documentation →](https://docs.swarms.world/en/latest/swarms/structs/hierarchical_swarm/)



### SequentialWorkflow

A `SequentialWorkflow` executes tasks in a strict order, forming a pipeline where each agent builds upon the work of the previous one. `SequentialWorkflow` is Ideal for processes that have clear, ordered steps. This ensures that tasks with dependencies are handled correctly.

```python
from swarms import Agent, SequentialWorkflow

# Initialize agents for a 3-step process
# 1. Generate an idea
idea_generator = Agent(agent_name="IdeaGenerator", system_prompt="Generate a unique startup idea.", model_name="gpt-4o-mini")
# 2. Validate the idea
validator = Agent(agent_name="Validator", system_prompt="Take this startup idea and analyze its market viability.", model_name="gpt-4o-mini")
# 3. Create a pitch
pitch_creator = Agent(agent_name="PitchCreator", system_prompt="Write a 3-sentence elevator pitch for this validated startup idea.", model_name="gpt-4o-mini")

# Create the sequential workflow
workflow = SequentialWorkflow(agents=[idea_generator, validator, pitch_creator])

# Run the workflow
elevator_pitch = workflow.run()
print(elevator_pitch)
```

### ConcurrentWorkflow (with `SpreadSheetSwarm`)

A concurrent workflow runs multiple agents simultaneously. `SpreadSheetSwarm` is a powerful implementation that can manage thousands of concurrent agents and log their outputs to a CSV file. Use this architecture for high-throughput tasks that can be performed in parallel, drastically reducing execution time.

```python
from swarms import Agent, SpreadSheetSwarm

# Define a list of tasks (e.g., social media posts to generate)
platforms = ["Twitter", "LinkedIn", "Instagram"]

# Create an agent for each task
agents = [
    Agent(
        agent_name=f"{platform}-Marketer",
        system_prompt=f"Generate a real estate marketing post for {platform}.",
        model_name="gpt-4o-mini",
    )
    for platform in platforms
]

# Initialize the swarm to run these agents concurrently
swarm = SpreadSheetSwarm(
    agents=agents,
    autosave_on=True,
    save_file_path="marketing_posts.csv",
)

# Run the swarm with a single, shared task description
property_description = "A beautiful 3-bedroom house in sunny California."
swarm.run(task=f"Generate a post about: {property_description}")
# Check marketing_posts.csv for the results!
```

### AgentRearrange

Inspired by `einsum`, `AgentRearrange` lets you define complex, non-linear relationships between agents using a simple string-based syntax. [Learn more](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/). This architecture is Perfect for orchestrating dynamic workflows where agents might work in parallel, sequence, or a combination of both.

```python
from swarms import Agent, AgentRearrange

# Define agents
researcher = Agent(agent_name="researcher", model_name="gpt-4o-mini")
writer = Agent(agent_name="writer", model_name="gpt-4o-mini")
editor = Agent(agent_name="editor", model_name="gpt-4o-mini")

# Define a flow: researcher sends work to both writer and editor simultaneously
# This is a one-to-many relationship
flow = "researcher -> writer, editor"

# Create the rearrangement system
rearrange_system = AgentRearrange(
    agents=[researcher, writer, editor],
    flow=flow,
)

# Run the system
# The researcher will generate content, and then both the writer and editor
# will process that content in parallel.
outputs = rearrange_system.run("Analyze the impact of AI on modern cinema.")
print(outputs)
```

---

### SwarmRouter: The Universal Swarm Orchestrator

The `SwarmRouter` simplifies building complex workflows by providing a single interface to run any type of swarm. Instead of importing and managing different swarm classes, you can dynamically select the one you need just by changing the `swarm_type` parameter. [Read the full documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)

This makes your code cleaner and more flexible, allowing you to switch between different multi-agent strategies with ease. Here's a complete example that shows how to define agents and then use `SwarmRouter` to execute the same task using different collaborative strategies.

```python
from swarms import Agent
from swarms.structs.swarm_router import SwarmRouter, SwarmType

# Define a few generic agents
writer = Agent(agent_name="Writer", system_prompt="You are a creative writer.", model_name="gpt-4o-mini")
editor = Agent(agent_name="Editor", system_prompt="You are an expert editor for stories.", model_name="gpt-4o-mini")
reviewer = Agent(agent_name="Reviewer", system_prompt="You are a final reviewer who gives a score.", model_name="gpt-4o-mini")

# The agents and task will be the same for all examples
agents = [writer, editor, reviewer]
task = "Write a short story about a robot who discovers music."

# --- Example 1: SequentialWorkflow ---
# Agents run one after another in a chain: Writer -> Editor -> Reviewer.
print("Running a Sequential Workflow...")
sequential_router = SwarmRouter(swarm_type=SwarmType.SequentialWorkflow, agents=agents)
sequential_output = sequential_router.run(task)
print(f"Final Sequential Output:\n{sequential_output}\n")

# --- Example 2: ConcurrentWorkflow ---
# All agents receive the same initial task and run at the same time.
print("Running a Concurrent Workflow...")
concurrent_router = SwarmRouter(swarm_type=SwarmType.ConcurrentWorkflow, agents=agents)
concurrent_outputs = concurrent_router.run(task)
# This returns a dictionary of each agent's output
for agent_name, output in concurrent_outputs.items():
    print(f"Output from {agent_name}:\n{output}\n")

# --- Example 3: MixtureOfAgents ---
# All agents run in parallel, and a special 'aggregator' agent synthesizes their outputs.
print("Running a Mixture of Agents Workflow...")
aggregator = Agent(
    agent_name="Aggregator",
    system_prompt="Combine the story, edits, and review into a final document.",
    model_name="gpt-4o-mini"
)
moa_router = SwarmRouter(
    swarm_type=SwarmType.MixtureOfAgents,
    agents=agents,
    aggregator_agent=aggregator, # MoA requires an aggregator
)
aggregated_output = moa_router.run(task)
print(f"Final Aggregated Output:\n{aggregated_output}\n")
```


The `SwarmRouter` is a powerful tool for simplifying multi-agent orchestration. It provides a consistent and flexible way to deploy different collaborative strategies, allowing you to build more sophisticated applications with less code.

---

### MixtureOfAgents (MoA)

The `MixtureOfAgents` architecture processes tasks by feeding them to multiple "expert" agents in parallel. Their diverse outputs are then synthesized by an aggregator agent to produce a final, high-quality result. [Learn more here](https://docs.swarms.world/en/latest/swarms/examples/moa_example/)

```python
from swarms import Agent, MixtureOfAgents

# Define expert agents
financial_analyst = Agent(agent_name="FinancialAnalyst", system_prompt="Analyze financial data.", model_name="gpt-4o-mini")
market_analyst = Agent(agent_name="MarketAnalyst", system_prompt="Analyze market trends.", model_name="gpt-4o-mini")
risk_analyst = Agent(agent_name="RiskAnalyst", system_prompt="Analyze investment risks.", model_name="gpt-4o-mini")

# Define the aggregator agent
aggregator = Agent(
    agent_name="InvestmentAdvisor",
    system_prompt="Synthesize the financial, market, and risk analyses to provide a final investment recommendation.",
    model_name="gpt-4o-mini"
)

# Create the MoA swarm
moa_swarm = MixtureOfAgents(
    agents=[financial_analyst, market_analyst, risk_analyst],
    aggregator_agent=aggregator,
)

# Run the swarm
recommendation = moa_swarm.run("Should we invest in NVIDIA stock right now?")
print(recommendation)
```

---

### GroupChat

`GroupChat` creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve a problem. You can define the speaking order or let it be determined dynamically. This architecture is ideal for tasks that benefit from debate and multi-perspective reasoning, such as contract negotiation, brainstorming, or complex decision-making.

```python
from swarms import Agent, GroupChat

# Define agents for a debate
tech_optimist = Agent(agent_name="TechOptimist", system_prompt="Argue for the benefits of AI in society.", model_name="gpt-4o-mini")
tech_critic = Agent(agent_name="TechCritic", system_prompt="Argue against the unchecked advancement of AI.", model_name="gpt-4o-mini")

# Create the group chat
chat = GroupChat(
    agents=[tech_optimist, tech_critic],
    max_loops=4, # Limit the number of turns in the conversation
)

# Run the chat with an initial topic
conversation_history = chat.run(
    "Let's discuss the societal impact of artificial intelligence."
)

# Print the full conversation
for message in conversation_history:
    print(f"[{message['agent_name']}]: {message['content']}")
```

--

## Connect With Us

Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights!

| Platform | Description | Link |
|----------|-------------|------|
| Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) |
| Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) |
| Discord | Live chat and community support | [Join Discord](https://discord.gg/EamjgSaEQf) |
| Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) |
| LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) |
| YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyXyitkbU_WSy7bd_41SqQ) |
| Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
| Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |

---



--------------------------------------------------

# File: swarms/structs/interactive_groupchat.md

# InteractiveGroupChat Documentation

The InteractiveGroupChat is a sophisticated multi-agent system that enables interactive conversations between users and AI agents using @mentions. This system allows users to direct tasks to specific agents and facilitates collaborative responses when multiple agents are mentioned.

## Features

| Feature | Description |
|---------|-------------|
| **@mentions Support** | Direct tasks to specific agents using @agent_name syntax |
| **Multi-Agent Collaboration** | Multiple mentioned agents can see and respond to each other's tasks |
| **Enhanced Collaborative Prompts** | Agents are trained to acknowledge, build upon, and synthesize each other's responses |
| **Speaker Functions** | Control the order in which agents respond (round robin, random, priority, custom) |
| **Dynamic Speaker Management** | Change speaker functions and priorities during runtime |
| **Random Dynamic Speaker** | Advanced speaker function that follows @mentions in agent responses |
| **Parallel and Sequential Strategies** | Support for both parallel and sequential agent execution |
| **Callable Function Support** | Supports both Agent instances and callable functions as chat participants |
| **Comprehensive Error Handling** | Custom error classes for different scenarios |
| **Conversation History** | Maintains a complete history of the conversation |
| **Flexible Output Formatting** | Configurable output format for conversation history |
| **Interactive Terminal Mode** | Full REPL interface for real-time chat with agents |

## Installation

```bash
pip install swarms
```

## Methods Reference

### Constructor (`__init__`)

**Description:**  
Initializes a new InteractiveGroupChat instance with the specified configuration.

**Arguments:**

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `id` | str | Unique identifier for the chat | auto-generated key |
| `name` | str | Name of the group chat | "InteractiveGroupChat" |
| `description` | str | Description of the chat's purpose | generic description |
| `agents` | List[Union[Agent, Callable]] | List of participating agents | empty list |
| `max_loops` | int | Maximum conversation turns | 1 |
| `output_type` | str | Type of output format | "string" |
| `interactive` | bool | Whether to enable interactive mode | False |
| `speaker_function` | Union[str, Callable] | Function to determine speaking order | round_robin_speaker |
| `speaker_state` | dict | Initial state for speaker function | {"current_index": 0} |

**Example:**

```python
from swarms import Agent, InteractiveGroupChat

# Create agents
financial_advisor = Agent(
    agent_name="FinancialAdvisor",
    system_prompt="You are a financial advisor specializing in investment strategies.",
    model_name="gpt-4"
)

tax_expert = Agent(
    agent_name="TaxExpert",
    system_prompt="You are a tax expert providing tax-related guidance.",
    model_name="gpt-4"
)

# Initialize group chat with speaker function
from swarms.structs.interactive_groupchat import round_robin_speaker

chat = InteractiveGroupChat(
    id="finance-chat-001",
    name="Financial Advisory Team",
    description="Expert financial guidance team",
    agents=[financial_advisor, tax_expert],
    max_loops=3,
    output_type="string",
    interactive=True,
    speaker_function=round_robin_speaker
)
```

### Run Method (`run`)

**Description:**  
Processes a task and gets responses from mentioned agents. This is the main method for sending tasks in non-interactive mode.

**Arguments:**

- `task` (str): The input task containing @mentions to agents
- `img` (Optional[str]): Optional image for the task
- `imgs` (Optional[List[str]]): Optional list of images for the task

**Returns:**

- str: Formatted conversation history including agent responses

**Example:**
```python
# Single agent interaction
response = chat.run("@FinancialAdvisor what are the best ETFs for 2024?")
print(response)

# Multiple agent collaboration
response = chat.run("@FinancialAdvisor and @TaxExpert, how can I minimize taxes on my investments?")
print(response)

# With image input
response = chat.run("@FinancialAdvisor analyze this chart", img="chart.png")
print(response)
```

### Start Interactive Session (`start_interactive_session`)

**Description:**  
Starts an interactive terminal session for real-time chat with agents. This creates a REPL (Read-Eval-Print Loop) interface.

**Arguments:**
None

**Features:**
- Real-time chat with agents using @mentions
- View available agents and their descriptions
- Change speaker functions during the session
- Built-in help system
- Graceful exit with 'exit' or 'quit' commands

**Example:**

```python
# Initialize chat with interactive mode
chat = InteractiveGroupChat(
    agents=[financial_advisor, tax_expert],
    interactive=True
)

# Start the interactive session
chat.start_interactive_session()
```

**Interactive Session Commands:**
- `@agent_name message` - Mention specific agents
- `help` or `?` - Show help information
- `speaker` - Change speaker function
- `exit` or `quit` - End the session

### Set Speaker Function (`set_speaker_function`)

**Description:**  

Dynamically changes the speaker function and optional state during runtime.

**Arguments:**

- `speaker_function` (Union[str, Callable]): Function that determines speaking order
  - String options: "round-robin-speaker", "random-speaker", "priority-speaker", "random-dynamic-speaker"
  - Callable: Custom function that takes (agents: List[str], **kwargs) -> str
- `speaker_state` (dict, optional): State for the speaker function

**Example:**
```python
from swarms.structs.interactive_groupchat import random_speaker, priority_speaker

# Change to random speaker function
chat.set_speaker_function(random_speaker)

# Change to priority speaker with custom priorities
chat.set_speaker_function(priority_speaker, {"financial_advisor": 3, "tax_expert": 2})

# Change to random dynamic speaker
chat.set_speaker_function("random-dynamic-speaker")
```

### Get Available Speaker Functions (`get_available_speaker_functions`)

**Description:**  

Returns a list of all available built-in speaker function names.

**Arguments:**
None

**Returns:**

- List[str]: List of available speaker function names

**Example:**
```python
available_functions = chat.get_available_speaker_functions()
print(available_functions)
# Output: ['round-robin-speaker', 'random-speaker', 'priority-speaker', 'random-dynamic-speaker']
```

### Get Current Speaker Function (`get_current_speaker_function`)

**Description:**  

Returns the name of the currently active speaker function.

**Arguments:**
None

**Returns:**

- str: Name of the current speaker function, or "custom" if it's a custom function

**Example:**
```python
current_function = chat.get_current_speaker_function()
print(current_function)  # Output: "round-robin-speaker"
```

### Set Priorities (`set_priorities`)

**Description:**  

Sets agent priorities for priority-based speaking order.

**Arguments:**

- `priorities` (dict): Dictionary mapping agent names to priority weights

**Example:**
```python
# Set agent priorities (higher numbers = higher priority)
chat.set_priorities({
    "financial_advisor": 5,
    "tax_expert": 3,
    "investment_analyst": 1
})
```

### Set Dynamic Strategy (`set_dynamic_strategy`)

**Description:**  

Sets the strategy for the random-dynamic-speaker function.

**Arguments:**

- `strategy` (str): Either "sequential" or "parallel"
  - "sequential": Process one agent at a time based on @mentions
  - "parallel": Process all mentioned agents simultaneously

**Example:**
```python
# Set to sequential strategy (one agent at a time)
chat.set_dynamic_strategy("sequential")

# Set to parallel strategy (all mentioned agents respond simultaneously)
chat.set_dynamic_strategy("parallel")
```

### Extract Mentions (`_extract_mentions`)

**Description:**  

Internal method that extracts @mentions from a task. Used by the run method to identify which agents should respond.

**Arguments:**

- `task` (str): The input task to extract mentions from

**Returns:**

- List[str]: List of mentioned agent names

**Example:**
```python
# Internal usage example (not typically called directly)
chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert])
mentions = chat._extract_mentions("@FinancialAdvisor and @TaxExpert, please help")
print(mentions)  # ['FinancialAdvisor', 'TaxExpert']
```

### Validate Initialization (`_validate_initialization`)

**Description:**  

Internal method that validates the group chat configuration during initialization.

**Arguments:**
None

**Example:**

```python
# Internal validation happens automatically during initialization
chat = InteractiveGroupChat(
    agents=[financial_advisor],  # Valid: at least one agent
    max_loops=5  # Valid: positive number
)
```

### Setup Conversation Context (`_setup_conversation_context`)

**Description:**  

Internal method that sets up the initial conversation context with group chat information.

**Arguments:**

None

**Example:**

```python
# Context is automatically set up during initialization
chat = InteractiveGroupChat(
    name="Investment Team",
    description="Expert investment advice",
    agents=[financial_advisor, tax_expert]
)
# The conversation context now includes chat name, description, and agent info
```

### Update Agent Prompts (`_update_agent_prompts`)

**Description:**  

Internal method that updates each agent's system prompt with information about other agents and the group chat. This includes enhanced collaborative instructions that teach agents how to acknowledge, build upon, and synthesize each other's responses.

**Arguments:**

None

**Example:**
```python
# Agent prompts are automatically updated during initialization
chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert])
# Each agent now knows about the other participants and how to collaborate effectively
```

### Get Speaking Order (`_get_speaking_order`)

**Description:**  

Internal method that determines the speaking order using the configured speaker function.

**Arguments:**

- `mentioned_agents` (List[str]): List of agent names that were mentioned

**Returns:**

- List[str]: List of agent names in the order they should speak

**Example:**
```python
# Internal usage (not typically called directly)
mentioned = ["financial_advisor", "tax_expert"]
order = chat._get_speaking_order(mentioned)
print(order)  # Order determined by speaker function
```

## Speaker Functions

InteractiveGroupChat supports various speaker functions that control the order in which agents respond when multiple agents are mentioned.

### Built-in Speaker Functions

#### Round Robin Speaker (`round_robin_speaker`)

Agents speak in a fixed order, cycling through the list in sequence.

```python
from swarms.structs.interactive_groupchat import InteractiveGroupChat, round_robin_speaker

chat = InteractiveGroupChat(
    agents=agents,
    speaker_function=round_robin_speaker,
    interactive=False,
)
```

**Behavior:**

- Agents speak in the order they were mentioned

- Maintains state between calls to continue the cycle

- Predictable and fair distribution of speaking turns

#### Random Speaker (`random_speaker`)

Agents speak in random order each time.

```python
from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_speaker

chat = InteractiveGroupChat(
    agents=agents,
    speaker_function=random_speaker,
    interactive=False,
)
```

**Behavior:**

- Speaking order is randomized for each task

- Provides variety and prevents bias toward first-mentioned agents

- Good for brainstorming sessions

#### Priority Speaker (`priority_speaker`)

Agents speak based on priority weights assigned to each agent.

```python
from swarms.structs.interactive_groupchat import InteractiveGroupChat, priority_speaker

chat = InteractiveGroupChat(
    agents=agents,
    speaker_function=priority_speaker,
    speaker_state={"priorities": {"financial_advisor": 3, "tax_expert": 2, "analyst": 1}},
    interactive=False,
)
```

**Behavior:**

- Higher priority agents speak first

- Uses weighted probability for selection

- Good for hierarchical teams or expert-led discussions

#### Random Dynamic Speaker (`random_dynamic_speaker`)

Advanced speaker function that follows @mentions in agent responses, enabling dynamic conversation flow.

```python
from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_dynamic_speaker

chat = InteractiveGroupChat(
    agents=agents,
    speaker_function=random_dynamic_speaker,
    speaker_state={"strategy": "parallel"},  # or "sequential"
    interactive=False,
)
```

**Behavior:**

- **First Call**: Randomly selects an agent to start the conversation
- **Subsequent Calls**: Extracts @mentions from the previous agent's response and selects the next speaker(s)
- **Two Strategies**:
  - **Sequential**: Processes one agent at a time based on @mentions
  - **Parallel**: Processes all mentioned agents simultaneously

**Example Dynamic Flow:**
```python
# Agent A responds: "I think @AgentB should analyze this data and @AgentC should review the methodology"
# With sequential strategy: Agent B speaks next
# With parallel strategy: Both Agent B and Agent C speak simultaneously
```

**Use Cases:**
- Complex problem-solving where agents need to delegate to specific experts
- Dynamic workflows where the conversation flow depends on agent responses
- Collaborative decision-making processes

### Custom Speaker Functions

You can create your own speaker functions to implement custom logic:

```python
def custom_speaker(agents: List[str], **kwargs) -> str:
    """
    Custom speaker function that selects agents based on specific criteria.
    
    Args:
        agents: List of agent names
        **kwargs: Additional arguments (context, time, etc.)
        
    Returns:
        Selected agent name
    """
    # Your custom logic here
    if "urgent" in kwargs.get("context", ""):
        return "emergency_agent" if "emergency_agent" in agents else agents[0]
    
    # Default to first agent
    return agents[0]

# Use custom speaker function
chat = InteractiveGroupChat(
    agents=agents,
    speaker_function=custom_speaker,
    interactive=False,
)
```

### Dynamic Speaker Function Changes

You can change the speaker function during runtime:

```python
# Start with round robin
chat = InteractiveGroupChat(
    agents=agents,
    speaker_function=round_robin_speaker,
    interactive=False,
)

# Change to random
chat.set_speaker_function(random_speaker)

# Change to priority with custom priorities
chat.set_priorities({"financial_advisor": 5, "tax_expert": 3, "analyst": 1})
chat.set_speaker_function(priority_speaker)

# Change to dynamic speaker with parallel strategy
chat.set_speaker_function("random-dynamic-speaker")
chat.set_dynamic_strategy("parallel")
```

## Enhanced Collaborative Behavior

The InteractiveGroupChat now includes enhanced collaborative prompts that ensure agents work together effectively.

### Collaborative Response Protocol

Every agent receives instructions to:

1. **Read and understand** all previous responses from other agents
2. **Acknowledge** what other agents have said
3. **Build upon** previous insights rather than repeating information
4. **Synthesize** multiple perspectives when possible
5. **Delegate** appropriately using @mentions

### Response Structure

Agents are guided to structure their responses as:

1. **ACKNOWLEDGE**: "I've reviewed the responses from @agent1 and @agent2..."
2. **BUILD**: "Building on @agent1's analysis of the data..."
3. **CONTRIBUTE**: "From my perspective, I would add..."
4. **COLLABORATE**: "To get a complete picture, let me ask @agent3 to..."
5. **SYNTHESIZE**: "Combining our insights, the key findings are..."

### Example Collaborative Response

```python
task = "Analyze our Q3 performance. @analyst @researcher @strategist"

# Expected collaborative behavior:
# Analyst: "Based on the data analysis, I can see clear growth trends in Q3..."
# Researcher: "Building on @analyst's data insights, I can add that market research shows..."
# Strategist: "Synthesizing @analyst's data and @researcher's market insights, I recommend..."
```

## Error Classes

### InteractiveGroupChatError

**Description:**  

Base exception class for InteractiveGroupChat errors.

**Example:**
```python
try:
    # Some operation that might fail
    chat.run("@InvalidAgent hello")
except InteractiveGroupChatError as e:
    print(f"Chat error occurred: {e}")
```

### AgentNotFoundError

**Description:**  

Raised when a mentioned agent is not found in the group.

**Example:**
```python
try:
    chat.run("@NonExistentAgent hello!")
except AgentNotFoundError as e:
    print(f"Agent not found: {e}")
```

### NoMentionedAgentsError

**Description:**  

Raised when no agents are mentioned in the task.

**Example:**

```python
try:
    chat.run("Hello everyone!")  # No @mentions
except NoMentionedAgentsError as e:
    print(f"No agents mentioned: {e}")
```

### InvalidTaskFormatError

**Description:**  

Raised when the task format is invalid.

**Example:**
```python
try:
    chat.run("@Invalid@Format")
except InvalidTaskFormatError as e:
    print(f"Invalid task format: {e}")
```

### InvalidSpeakerFunctionError

**Description:**  

Raised when an invalid speaker function is provided.

**Example:**
```python
def invalid_speaker(agents, **kwargs):
    return 123  # Should return string, not int

try:
    chat = InteractiveGroupChat(
        agents=agents,
        speaker_function=invalid_speaker,
    )
except InvalidSpeakerFunctionError as e:
    print(f"Invalid speaker function: {e}")
```

## Best Practices

| Best Practice | Description | Example |
|--------------|-------------|---------|
| Agent Naming | Use clear, unique names for agents to avoid confusion | `financial_advisor`, `tax_expert` |
| Task Format | Always use @mentions to direct tasks to specific agents | `@financial_advisor What's your investment advice?` |
| Speaker Functions | Choose appropriate speaker functions for your use case | Round robin for fairness, priority for expert-led discussions |
| Dynamic Speaker | Use random-dynamic-speaker for complex workflows with delegation | When agents need to call on specific experts |
| Strategy Selection | Choose sequential for focused discussions, parallel for brainstorming | Sequential for analysis, parallel for idea generation |
| Collaborative Design | Design agents with complementary expertise for better collaboration | Analyst + Researcher + Strategist |
| Error Handling | Implement proper error handling for various scenarios | `try/except` blocks for `AgentNotFoundError` |
| Context Management | Be aware that agents can see the full conversation history | Monitor conversation length and relevance |
| Resource Management | Consider the number of agents and task length to optimize performance | Limit max_loops and task size |
| Dynamic Adaptation | Change speaker functions based on different phases of work | Round robin for brainstorming, priority for decision-making |

## Usage Examples

### Basic Multi-Agent Collaboration

```python
from swarms import Agent
from swarms.structs.interactive_groupchat import InteractiveGroupChat, round_robin_speaker

# Create specialized agents
analyst = Agent(
    agent_name="analyst",
    system_prompt="You are a data analyst specializing in business intelligence.",
    llm="gpt-3.5-turbo",
)

researcher = Agent(
    agent_name="researcher", 
    system_prompt="You are a market researcher with expertise in consumer behavior.",
    llm="gpt-3.5-turbo",
)

strategist = Agent(
    agent_name="strategist",
    system_prompt="You are a strategic consultant who synthesizes insights into actionable recommendations.",
    llm="gpt-3.5-turbo",
)

# Create collaborative group chat
chat = InteractiveGroupChat(
    name="Business Analysis Team",
    description="A collaborative team for comprehensive business analysis",
    agents=[analyst, researcher, strategist],
    speaker_function=round_robin_speaker,
    interactive=False,
)

# Collaborative analysis task
task = """Analyze our company's Q3 performance. We have the following data:
- Revenue: $2.5M (up 15% from Q2)
- Customer acquisition cost: $45 (down 8% from Q2)
- Market share: 3.2% (up 0.5% from Q2)

@analyst @researcher @strategist please provide a comprehensive analysis."""

response = chat.run(task)
print(response)
```

### Priority-Based Expert Consultation

```python
from swarms.structs.interactive_groupchat import InteractiveGroupChat, priority_speaker

# Create expert agents with different priority levels
senior_expert = Agent(
    agent_name="senior_expert",
    system_prompt="You are a senior consultant with 15+ years of experience.",
    llm="gpt-4",
)

junior_expert = Agent(
    agent_name="junior_expert",
    system_prompt="You are a junior consultant with 3 years of experience.",
    llm="gpt-3.5-turbo",
)

assistant = Agent(
    agent_name="assistant",
    system_prompt="You are a research assistant who gathers supporting information.",
    llm="gpt-3.5-turbo",
)

# Create priority-based group chat
chat = InteractiveGroupChat(
    name="Expert Consultation Team",
    description="Expert-led consultation with collaborative input",
    agents=[senior_expert, junior_expert, assistant],
    speaker_function=priority_speaker,
    speaker_state={"priorities": {"senior_expert": 5, "junior_expert": 3, "assistant": 1}},
    interactive=False,
)

# Expert consultation task
task = """We need strategic advice on entering a new market. 
@senior_expert @junior_expert @assistant please provide your insights."""

response = chat.run(task)
print(response)
```

### Dynamic Speaker Function with Delegation

```python
from swarms.structs.interactive_groupchat import InteractiveGroupChat, random_dynamic_speaker

# Create specialized medical agents
cardiologist = Agent(
    agent_name="cardiologist",
    system_prompt="You are a cardiologist specializing in heart conditions.",
    llm="gpt-4",
)

oncologist = Agent(
    agent_name="oncologist",
    system_prompt="You are an oncologist specializing in cancer treatment.",
    llm="gpt-4",
)

endocrinologist = Agent(
    agent_name="endocrinologist",
    system_prompt="You are an endocrinologist specializing in hormone disorders.",
    llm="gpt-4",
)

# Create dynamic group chat
chat = InteractiveGroupChat(
    name="Medical Panel Discussion",
    description="A collaborative panel of medical specialists",
    agents=[cardiologist, oncologist, endocrinologist],
    speaker_function=random_dynamic_speaker,
    speaker_state={"strategy": "sequential"},
    interactive=False,
)

# Complex medical case with dynamic delegation
case = """CASE PRESENTATION:
A 65-year-old male with Type 2 diabetes, hypertension, and recent diagnosis of 
stage 3 colon cancer presents with chest pain and shortness of breath. 
ECG shows ST-segment elevation. Recent blood work shows elevated blood glucose (280 mg/dL) 
and signs of infection (WBC 15,000, CRP elevated).

@cardiologist @oncologist @endocrinologist please provide your assessment and treatment recommendations."""

response = chat.run(case)
print(response)
```

### Dynamic Speaker Function Changes

```python
from swarms.structs.interactive_groupchat import (
    InteractiveGroupChat, 
    round_robin_speaker, 
    random_speaker, 
    priority_speaker,
    random_dynamic_speaker
)

# Create brainstorming agents
creative_agent = Agent(agent_name="creative", system_prompt="You are a creative thinker.")
analytical_agent = Agent(agent_name="analytical", system_prompt="You are an analytical thinker.")
practical_agent = Agent(agent_name="practical", system_prompt="You are a practical implementer.")

chat = InteractiveGroupChat(
    name="Dynamic Team",
    agents=[creative_agent, analytical_agent, practical_agent],
    speaker_function=round_robin_speaker,
    interactive=False,
)

# Phase 1: Brainstorming (random order)
chat.set_speaker_function(random_speaker)
task1 = "Let's brainstorm new product ideas. @creative @analytical @practical"
response1 = chat.run(task1)

# Phase 2: Analysis (priority order)
chat.set_priorities({"analytical": 3, "creative": 2, "practical": 1})
chat.set_speaker_function(priority_speaker)
task2 = "Now let's analyze the feasibility of these ideas. @creative @analytical @practical"
response2 = chat.run(task2)

# Phase 3: Dynamic delegation (agents mention each other)
chat.set_speaker_function(random_dynamic_speaker)
chat.set_dynamic_strategy("sequential")
task3 = "Let's plan implementation with dynamic delegation. @creative @analytical @practical"
response3 = chat.run(task3)

# Phase 4: Final synthesis (round robin for equal input)
chat.set_speaker_function(round_robin_speaker)
task4 = "Finally, let's synthesize our findings. @creative @analytical @practical"
response4 = chat.run(task4)
```

### Custom Speaker Function

```python
def context_aware_speaker(agents: List[str], **kwargs) -> str:
    """Custom speaker function that selects agents based on context."""
    context = kwargs.get("context", "").lower()
    
    if "data" in context or "analysis" in context:
        return "analyst" if "analyst" in agents else agents[0]
    elif "market" in context or "research" in context:
        return "researcher" if "researcher" in agents else agents[0]
    elif "strategy" in context or "planning" in context:
        return "strategist" if "strategist" in agents else agents[0]
    else:
        return agents[0]

# Use custom speaker function
chat = InteractiveGroupChat(
    name="Context-Aware Team",
    agents=[analyst, researcher, strategist],
    speaker_function=context_aware_speaker,
    interactive=False,
)

# The speaker function will automatically select the most appropriate agent
task = "We need to analyze our market position and develop a strategy."
response = chat.run(task)
```

### Interactive Session with Enhanced Collaboration

```python
# Create agents designed for collaboration
data_scientist = Agent(
    agent_name="data_scientist",
    system_prompt="You are a data scientist. When collaborating, always reference specific data points and build upon others' insights with quantitative support.",
    llm="gpt-4",
)

business_analyst = Agent(
    agent_name="business_analyst",
    system_prompt="You are a business analyst. When collaborating, always connect business insights to practical implications and build upon data analysis with business context.",
    llm="gpt-3.5-turbo",
)

product_manager = Agent(
    agent_name="product_manager",
    system_prompt="You are a product manager. When collaborating, always synthesize insights from all team members and provide actionable product recommendations.",
    llm="gpt-3.5-turbo",
)

# Start interactive session
chat = InteractiveGroupChat(
    name="Product Development Team",
    description="A collaborative team for product development decisions",
    agents=[data_scientist, business_analyst, product_manager],
    speaker_function=round_robin_speaker,
    interactive=True,
)

# Start the interactive session
chat.start_interactive_session()
```

## Benefits and Use Cases

### Benefits of Enhanced Collaboration

1. **Reduced Redundancy**: Agents don't repeat what others have already said
2. **Improved Synthesis**: Multiple perspectives are integrated into coherent conclusions
3. **Better Delegation**: Agents naturally delegate to appropriate experts
4. **Enhanced Problem Solving**: Complex problems are addressed systematically
5. **More Natural Interactions**: Agents respond like real team members
6. **Dynamic Workflows**: Conversation flow adapts based on agent responses
7. **Flexible Execution**: Support for both sequential and parallel processing

### Use Cases

| Use Case Category | Specific Use Case | Agent Team Composition | Recommended Speaker Function |
|------------------|-------------------|----------------------|------------------------------|
| **Business Analysis and Strategy** | Data Analysis | Analyst + Researcher + Strategist | Round Robin |
| | Market Research | Multiple experts analyzing different aspects | Random Dynamic |
| | Strategic Planning | Expert-led discussions with collaborative input | Priority |
| **Product Development** | Requirements Gathering | Product Manager + Developer + Designer | Round Robin |
| | Technical Architecture | Senior + Junior developers with different expertise | Priority |
| | User Experience | UX Designer + Product Manager + Developer | Random Dynamic |
| **Research and Development** | Scientific Research | Multiple researchers with different specializations | Random Dynamic |
| | Literature Review | Different experts reviewing various aspects | Round Robin |
| | Experimental Design | Statistician + Domain Expert + Methodologist | Priority |
| **Creative Projects** | Content Creation | Writer + Editor + Designer | Random |
| | Marketing Campaigns | Creative + Analyst + Strategist | Random Dynamic |
| | Design Projects | Designer + Developer + Product Manager | Round Robin |
| **Problem Solving** | Troubleshooting | Technical + Business + User perspective experts | Priority |
| | Crisis Management | Emergency + Communication + Technical teams | Priority |
| | Decision Making | Executive + Analyst + Specialist | Priority |
| **Medical Consultation** | Complex Cases | Multiple specialists (Cardiologist + Oncologist + Endocrinologist) | Random Dynamic |
| | Treatment Planning | Senior + Junior doctors with different expertise | Priority |
| | Research Review | Multiple researchers reviewing different aspects | Round Robin |

### Speaker Function Selection Guide

| Use Case | Recommended Speaker Function | Strategy | Reasoning |
|----------|------------------------------|----------|-----------|
| Team Meetings | Round Robin | N/A | Ensures equal participation |
| Brainstorming | Random | N/A | Prevents bias and encourages creativity |
| Expert Consultation | Priority | N/A | Senior experts speak first |
| Problem Solving | Priority | N/A | Most relevant experts prioritize |
| Creative Sessions | Random | N/A | Encourages diverse perspectives |
| Decision Making | Priority | N/A | Decision makers speak first |
| Research Review | Round Robin | N/A | Equal contribution from all reviewers |
| Complex Workflows | Random Dynamic | Sequential | Follows natural conversation flow |
| Parallel Analysis | Random Dynamic | Parallel | Multiple agents work simultaneously |
| Medical Panels | Random Dynamic | Sequential | Specialists delegate to relevant experts |
| Technical Architecture | Random Dynamic | Sequential | Senior architects guide the discussion |

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

## License

This project is licensed under the Apache License - see the LICENSE file for details. 

--------------------------------------------------

# File: swarms/structs/majorityvoting.md

# MajorityVoting Module Documentation

The `MajorityVoting` module provides a mechanism for performing majority voting among a group of agents. Majority voting is a decision rule that selects the option which has the majority of votes. This is particularly useful in systems where multiple agents provide responses to a query, and the most common response needs to be identified as the final output.

## Architecture

```mermaid
graph TD
    A[MajorityVoting System] --> B[Initialize Agents]
    B --> C[Process Task]
    C --> D{Execution Mode}
    D --> E[Single Task]
    D --> F[Batch Tasks]
    D --> G[Concurrent Tasks]
    D --> H[Async Tasks]
    E --> I[Run Agents]
    F --> I
    G --> I
    H --> I
    I --> J[Collect Responses]
    J --> K[Consensus Analysis]
    K --> L{Consensus Agent?}
    L -->|Yes| M[Use Consensus Agent]
    L -->|No| N[Use Last Agent]
    M --> O[Final Output]
    N --> O
    O --> P[Save Conversation]
```

### Key Concepts

- **Majority Voting**: A method to determine the most common response from a set of answers.
- **Agents**: Entities (e.g., models, algorithms) that provide responses to tasks or queries.
- **Output Parser**: A function that processes the responses from the agents before performing the majority voting.
- **Consensus Agent**: An optional agent that analyzes the responses from all agents to determine the final consensus.
- **Conversation History**: A record of all agent interactions and responses during the voting process.

## Class Definition: `MajorityVoting`

### Parameters

| Parameter         | Type           | Description                                                                 |
|------------------|----------------|-----------------------------------------------------------------------------|
| `name`           | `str`          | Name of the majority voting system. Default is "MajorityVoting".            |
| `description`    | `str`          | Description of the system. Default is "A majority voting system for agents". |
| `agents`         | `List[Agent]`  | A list of agents to be used in the majority voting system.                  |
| `output_parser`  | `Callable`     | Function to parse agent outputs. Default is `majority_voting` function.      |
| `consensus_agent`| `Agent`        | Optional agent for analyzing consensus among responses.                      |
| `autosave`       | `bool`         | Whether to autosave conversations. Default is `False`.                      |
| `verbose`        | `bool`         | Whether to enable verbose logging. Default is `False`.                      |
| `max_loops`      | `int`          | Maximum number of voting loops. Default is 1.                               |

### Methods

#### `run(task: str, correct_answer: str, *args, **kwargs) -> List[Any]`

Runs the majority voting system for a single task.

**Parameters:**
- `task` (str): The task to be performed by the agents
- `correct_answer` (str): The correct answer for evaluation
- `*args`, `**kwargs`: Additional arguments

**Returns:**
- List[Any]: The conversation history as a string, including the majority vote

#### `batch_run(tasks: List[str], *args, **kwargs) -> List[Any]`

Runs multiple tasks in sequence.

**Parameters:**
- `tasks` (List[str]): List of tasks to be performed
- `*args`, `**kwargs`: Additional arguments

**Returns:**
- List[Any]: List of majority votes for each task

#### `run_concurrently(tasks: List[str], *args, **kwargs) -> List[Any]`

Runs multiple tasks concurrently using thread pooling.

**Parameters:**
- `tasks` (List[str]): List of tasks to be performed
- `*args`, `**kwargs`: Additional arguments

**Returns:**
- List[Any]: List of majority votes for each task

#### `run_async(tasks: List[str], *args, **kwargs) -> List[Any]`

Runs multiple tasks asynchronously using asyncio.

**Parameters:**
- `tasks` (List[str]): List of tasks to be performed
- `*args`, `**kwargs`: Additional arguments

**Returns:**
- List[Any]: List of majority votes for each task

## Usage Examples

### Example 1: Basic Single Task Execution with Modern LLMs

```python
from swarms import Agent, MajorityVoting

# Initialize multiple agents with different specialties
agents = [
    Agent(
        agent_name="Financial-Analysis-Agent",
        agent_description="Personal finance advisor focused on market analysis",
        system_prompt="You are a financial advisor specializing in market analysis and investment opportunities.",
        max_loops=1,
        model_name="gpt-4o"
    ),
    Agent(
        agent_name="Risk-Assessment-Agent", 
        agent_description="Risk analysis and portfolio management expert",
        system_prompt="You are a risk assessment expert focused on evaluating investment risks and portfolio diversification.",
        max_loops=1,
        model_name="gpt-4o"
    ),
    Agent(
        agent_name="Tech-Investment-Agent",
        agent_description="Technology sector investment specialist",
        system_prompt="You are a technology investment specialist focused on AI, emerging tech, and growth opportunities.",
        max_loops=1,
        model_name="gpt-4o"
    )
]


consensus_agent = Agent(
    agent_name="Consensus-Agent",
    agent_description="Consensus agent focused on analyzing investment advice",
    system_prompt="You are a consensus agent focused on analyzing investment advice and providing a final answer.",
    max_loops=1,
    model_name="gpt-4o"
)

# Create majority voting system
majority_voting = MajorityVoting(
    name="Investment-Advisory-System",
    description="Multi-agent system for investment advice",
    agents=agents,
    verbose=True,
    consensus_agent=consensus_agent
)

# Run the analysis with majority voting
result = majority_voting.run(
    task="Create a table of super high growth opportunities for AI. I have $40k to invest in ETFs, index funds, and more. Please create a table in markdown.",
    correct_answer=""  # Optional evaluation metric
)

print(result)

```

## Batch Execution

```python
from swarms import Agent, MajorityVoting

# Initialize multiple agents with different specialties
agents = [
    Agent(
        agent_name="Financial-Analysis-Agent",
        agent_description="Personal finance advisor focused on market analysis",
        system_prompt="You are a financial advisor specializing in market analysis and investment opportunities.",
        max_loops=1,
        model_name="gpt-4o"
    ),
    Agent(
        agent_name="Risk-Assessment-Agent", 
        agent_description="Risk analysis and portfolio management expert",
        system_prompt="You are a risk assessment expert focused on evaluating investment risks and portfolio diversification.",
        max_loops=1,
        model_name="gpt-4o"
    ),
    Agent(
        agent_name="Tech-Investment-Agent",
        agent_description="Technology sector investment specialist",
        system_prompt="You are a technology investment specialist focused on AI, emerging tech, and growth opportunities.",
        max_loops=1,
        model_name="gpt-4o"
    )
]


consensus_agent = Agent(
    agent_name="Consensus-Agent",
    agent_description="Consensus agent focused on analyzing investment advice",
    system_prompt="You are a consensus agent focused on analyzing investment advice and providing a final answer.",
    max_loops=1,
    model_name="gpt-4o"
)

# Create majority voting system
majority_voting = MajorityVoting(
    name="Investment-Advisory-System",
    description="Multi-agent system for investment advice",
    agents=agents,
    verbose=True,
    consensus_agent=consensus_agent
)

# Run the analysis with majority voting
result = majority_voting.batch_run(
    task="Create a table of super high growth opportunities for AI. I have $40k to invest in ETFs, index funds, and more. Please create a table in markdown.",
    correct_answer=""  # Optional evaluation metric
)

print(result)


```

--------------------------------------------------

# File: swarms/structs/malt.md

# MALT: Multi-Agent Learning Task Framework

## Overview

MALT (Multi-Agent Learning Task) is a sophisticated orchestration framework that coordinates multiple specialized AI agents to tackle complex tasks through structured conversations. Inspired by the principles outlined in the [MALT research paper](https://arxiv.org/pdf/2412.01928), this implementation provides a reliable, extensible system for multi-agent collaboration.

The framework is designed around a three-agent architecture:

1. **Creator Agent**: Generates initial content or solutions

2. **Verifier Agent**: Critically evaluates the creator's output

3. **Refiner Agent**: Improves the solution based on verifier feedback

This collaborative approach enables high-quality outputs for complex tasks by combining the strengths of multiple specialized agents, each focused on a different aspect of the problem-solving process.

## How It Works

The MALT framework follows a structured workflow:

1. A task is submitted to the system
2. The Creator Agent generates an initial solution
3. Multiple instances of the Verifier Agent independently evaluate the solution
4. Multiple instances of the Refiner Agent improve the solution based on verification feedback
5. The final refined output is returned

This process can be configured to run for multiple iterations, with each cycle potentially improving the quality of the output. The system maintains a conversation history, tracking interactions between agents throughout the workflow.

### Key Components

- **Agent**: Represents an individual AI agent with specific capabilities and responsibilities
- **Conversation**: Manages the interaction history between agents
- **MALT Orchestrator**: Coordinates the workflow and manages agent interactions
- **Concurrency Support**: Enables parallel execution of multiple agent instances

## Architecture Diagram

```mermaid
flowchart TD
    User[User/Client] -->|Submit Task| MALT[MALT Orchestrator]
    
    subgraph MALT Framework
        MALT -->|Task| Creator[Creator Agent]
        Creator -->|Initial Solution| Conversation[Conversation Manager]
        Conversation -->|Solution| VerifierPool[Verifier Agents Pool]
        
        subgraph VerifierPool
            Verifier1[Verifier Agent 1]
            Verifier2[Verifier Agent 2]
            Verifier3[Verifier Agent 3]
        end
        
        VerifierPool -->|Verification Feedback| Conversation
        Conversation -->|Solution + Feedback| RefinerPool[Refiner Agents Pool]
        
        subgraph RefinerPool
            Refiner1[Refiner Agent 1]
            Refiner2[Refiner Agent 2]
            Refiner3[Refiner Agent 3]
        end
        
        RefinerPool -->|Refined Solutions| Conversation
    end
    
    Conversation -->|Final Output| User
```

## Execution Workflow

```mermaid
sequenceDiagram
    participant User
    participant MALT
    participant Creator
    participant Verifiers
    participant Refiners
    participant Conversation
    
    User->>MALT: Submit task
    MALT->>Creator: Process task
    Creator->>Conversation: Add initial solution
    
    par Verification Phase
        Conversation->>Verifiers: Send solution for verification
        Verifiers->>Conversation: Return verification feedback
    end
    
    par Refinement Phase
        Conversation->>Refiners: Send solution + feedback
        Refiners->>Conversation: Return refined solutions
    end
    
    MALT->>Conversation: Request final output
    Conversation->>MALT: Return conversation history
    MALT->>User: Return final result
```

## API Reference

### MALT Class

The core orchestrator that manages the multi-agent interaction process.

#### Constructor Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `main_agent` | `Agent` | `None` | The primary agent (Creator) responsible for generating initial solutions |
| `refiner_agent` | `Agent` | `None` | The agent that refines solutions based on verification feedback |
| `verifier_agent` | `Agent` | `None` | The agent that verifies and evaluates solutions |
| `max_loops` | `int` | `1` | Maximum number of iterations for the task execution |
| `return_list` | `bool` | `False` | Flag to return output as a list |
| `return_dict` | `bool` | `False` | Flag to return output as a dictionary |
| `agents` | `list[Agent]` | `[]` | Alternative list of agents to use in the task |
| `preset_agents` | `bool` | `True` | Use default preset agents for mathematical proofs |

#### Methods

| Method | Parameters | Return Type | Description |
|--------|------------|-------------|-------------|
| `reliability_check` | None | None | Validates agent configuration and parameters |
| `step` | `task: str, img: str = None, *args, **kwargs` | `str` or `list` or `dict` | Executes a single iteration of the MALT workflow |
| `run` | `task: str, img: str = None, *args, **kwargs` | `str` or `list` or `dict` | Executes the complete MALT workflow for a task |
| `run_batched` | `tasks: List[str], *args, **kwargs` | `List[str]` or `List[list]` or `List[dict]` | Sequentially processes multiple tasks |
| `run_concurrently` | `tasks: List[str], *args, **kwargs` | `concurrent.futures.Future` | Processes multiple tasks in parallel using ThreadPoolExecutor |
| `__call__` | `task: str, *args, **kwargs` | Same as `run` | Allows the MALT instance to be called as a function |
| `__str__` | None | `str` | Returns the conversation history as a string |
| `__repr__` | None | `str` | Returns the conversation history as a string |


## Sample Implementations

### Default Mathematical Proof Agents

The MALT framework includes preset agents specialized for mathematical proof generation and refinement:

1. **Proof Creator Agent**: Generates original mathematical theorems and proofs
2. **Proof Verifier Agent**: Critically evaluates and identifies issues in mathematical proofs
3. **Proof Refiner Agent**: Improves proofs based on verification feedback

Each agent has a carefully designed system prompt that guides its behavior and specialization.

## Usage Examples

### Basic Usage

```python
from swarms.structs.agent import Agent
from swarms.structs.multi_agent_exec import MALT

# Initialize with preset mathematical proof agents
malt = MALT(preset_agents=True)

# Run a mathematical proof task
result = malt.run("Develop a theorem and proof related to prime numbers and their distribution.")

print(result)
```

### Custom Agents

```python
from swarms.structs.agent import Agent
from swarms.structs.multi_agent_exec import MALT

# Define custom agents
creator = Agent(
    agent_name="Physics-Creator",
    model_name="gpt-4o-mini",
    max_loops=1,
    system_prompt="You are a theoretical physicist specializing in quantum mechanics..."
)

verifier = Agent(
    agent_name="Physics-Verifier",
    model_name="gpt-4o-mini",
    max_loops=1,
    system_prompt="You are an experimental physicist who verifies theoretical claims..."
)

refiner = Agent(
    agent_name="Physics-Communicator",
    model_name="gpt-4o-mini",
    max_loops=1,
    system_prompt="You excel at explaining complex physics concepts to diverse audiences..."
)

# Initialize MALT with custom agents
malt = MALT(
    main_agent=creator,
    verifier_agent=verifier,
    refiner_agent=refiner,
    preset_agents=False,
    max_loops=1
)

# Run a physics explanation task
result = malt.run("Explain the quantum entanglement phenomenon and its implications.")
```

### Concurrent Processing

```python
from swarms.structs.multi_agent_exec import MALT

# Initialize MALT
malt = MALT()

# Define multiple tasks
tasks = [
    "Prove a theorem related to continuous functions on compact sets.",
    "Develop a theorem about convergence in infinite-dimensional Hilbert spaces.",
    "Create a theorem relating to measure theory and Lebesgue integration."
]

# Process tasks concurrently
futures = malt.run_concurrently(tasks)

# Collect results as they complete
for future in futures:
    result = future.result()
    print(result)
```

## Example: Complex Mathematical Domain

Here's an example of how MALT can generate, verify, and refine a mathematical proof:

### Input

```python
malt = MALT(preset_agents=True)
task = "Develop a theorem and rigorous proof related to the convergence properties of infinite series."
result = malt.run(task)
```

### Output Flow

1. **Creator Agent** generates a theorem and proof about conditions for absolute convergence
2. **Verifier Agents** identify issues:
   - Logical gap in lemma 2
   - Missing justification for uniform convergence claim
   - Imprecise definition of certain terms
3. **Refiner Agents** produce improved versions addressing these concerns
4. The final output contains the refined, rigorous mathematical proof

## Best Practices

1. **Task Specificity**: Provide clear, detailed task descriptions for optimal results
2. **Agent Specialization**: Design agent prompts to focus on specific aspects of the task
3. **Iteration Control**: Adjust `max_loops` based on task complexity
4. **Concurrent Verification**: Use multiple verifier instances for comprehensive evaluation
5. **Custom Agents**: Create domain-specific agents for specialized tasks

## Potential Improvements

- Autonomously create specialized agents based on task requirements
- Implement feedback loops between agents for iterative improvement
- Add support for agent-specific memory and knowledge bases
- Expand concurrency capabilities for improved performance
- Implement learning mechanisms for agent improvement over time

## References

- Original MALT paper: [arXiv:2412.01928](https://arxiv.org/pdf/2412.01928)
- Built on the swarms framework for multi-agent systems

--------------------------------------------------

# File: swarms/structs/matrix_swarm.md

# MatrixSwarm

The `MatrixSwarm` class provides a framework for managing and operating on matrices of AI agents, enabling matrix-like operations similar to linear algebra. This allows for complex agent interactions and parallel processing capabilities.

## Overview

`MatrixSwarm` treats AI agents as elements in a matrix, allowing for operations like addition, multiplication, and transposition. This approach enables sophisticated agent orchestration and parallel processing patterns.

## Installation

```bash
pip3 install -U swarms
```

## Basic Usage

```python
from swarms import Agent
from swarms.matrix import MatrixSwarm

# Create a 2x2 matrix of agents
agents = [
    [Agent(agent_name="Agent-0-0"), Agent(agent_name="Agent-0-1")],
    [Agent(agent_name="Agent-1-0"), Agent(agent_name="Agent-1-1")]
]

# Initialize the matrix
matrix = MatrixSwarm(agents)
```

## Class Constructor

```python
def __init__(self, agents: List[List[Agent]])
```

### Parameters
- `agents` (`List[List[Agent]]`): A 2D list of Agent instances representing the matrix.

### Raises
- `ValueError`: If the input is not a valid 2D list of Agent instances.

## Methods

### transpose()

Transposes the matrix of agents by swapping rows and columns.

```python
def transpose(self) -> MatrixSwarm
```

#### Returns
- `MatrixSwarm`: A new MatrixSwarm instance with transposed dimensions.

---

### add(other)

Performs element-wise addition of two agent matrices.

```python
def add(self, other: MatrixSwarm) -> MatrixSwarm
```

#### Parameters
- `other` (`MatrixSwarm`): Another MatrixSwarm instance to add.

#### Returns
- `MatrixSwarm`: A new MatrixSwarm resulting from the addition.

#### Raises
- `ValueError`: If matrix dimensions are incompatible.

---

### scalar_multiply(scalar)

Scales the matrix by duplicating agents along rows.

```python
def scalar_multiply(self, scalar: int) -> MatrixSwarm
```

#### Parameters
- `scalar` (`int`): The multiplication factor.

#### Returns
- `MatrixSwarm`: A new MatrixSwarm with scaled dimensions.

---

### multiply(other, inputs)

Performs matrix multiplication (dot product) between two agent matrices.

```python
def multiply(self, other: MatrixSwarm, inputs: List[str]) -> List[List[AgentOutput]]
```

#### Parameters
- `other` (`MatrixSwarm`): The second MatrixSwarm for multiplication.
- `inputs` (`List[str]`): Input queries for the agents.

#### Returns
- `List[List[AgentOutput]]`: Matrix of operation results.

#### Raises
- `ValueError`: If matrix dimensions are incompatible for multiplication.

---

### subtract(other)

Performs element-wise subtraction of two agent matrices.

```python
def subtract(self, other: MatrixSwarm) -> MatrixSwarm
```

#### Parameters
- `other` (`MatrixSwarm`): Another MatrixSwarm to subtract.

#### Returns
- `MatrixSwarm`: A new MatrixSwarm resulting from the subtraction.

---

### identity(size)

Creates an identity matrix of agents.

```python
def identity(self, size: int) -> MatrixSwarm
```

#### Parameters
- `size` (`int`): Size of the identity matrix (NxN).

#### Returns
- `MatrixSwarm`: An identity MatrixSwarm.

---

### determinant()

Computes the determinant of a square agent matrix.

```python
def determinant(self) -> Any
```

#### Returns
- `Any`: The determinant result.

#### Raises
- `ValueError`: If the matrix is not square.

---

### save_to_file(path)

Saves the matrix structure and metadata to a JSON file.

```python
def save_to_file(self, path: str) -> None
```

#### Parameters
- `path` (`str`): File path for saving the matrix data.

## Extended Example

Here's a comprehensive example demonstrating various MatrixSwarm operations:

```python
from swarms import Agent
from swarms.matrix import MatrixSwarm

# Create agents with specific configurations
agents = [
    [
        Agent(
            agent_name=f"Agent-{i}-{j}",
            system_prompt="Your system prompt here",
            model_name="gpt-4",
            max_loops=1,
            verbose=True
        ) for j in range(2)
    ] for i in range(2)
]

# Initialize matrix
matrix = MatrixSwarm(agents)

# Example operations
transposed = matrix.transpose()
scaled = matrix.scalar_multiply(2)

# Run operations with inputs
inputs = ["Query 1", "Query 2"]
results = matrix.multiply(transposed, inputs)

# Save results
matrix.save_to_file("matrix_results.json")
```

## Output Schema

The `AgentOutput` class defines the structure for operation results:

```python
class AgentOutput(BaseModel):
    agent_name: str
    input_query: str
    output_result: Any
    metadata: dict
```

## Best Practices

1. **Initialization**
   - Ensure all agents in the matrix are properly configured before initialization
   - Validate matrix dimensions for your use case

2. **Operation Performance**
   - Consider computational costs for large matrices
   - Use appropriate batch sizes for inputs

3. **Error Handling**
   - Implement proper error handling for agent operations
   - Validate inputs before matrix operations

4. **Resource Management**
   - Monitor agent resource usage in large matrices
   - Implement proper cleanup procedures

## Limitations

- Matrix operations are constrained by the underlying agent capabilities
- Performance may vary based on agent configuration and complexity
- Resource usage scales with matrix dimensions

## See Also

- [Swarms Documentation](https://github.com/kyegomez/swarms)
- [Agent Class Reference](https://github.com/kyegomez/swarms/tree/main/swarms)

--------------------------------------------------

# File: swarms/structs/moa.md

# MixtureOfAgents Class Documentation

```mermaid
graph TD
    A[Input Task] --> B[Initialize MixtureOfAgents]
    B --> C[Reliability Check]
    C --> D[Layer 1: Parallel Agent Execution]
    D --> E[Layer 2: Sequential Processing]
    E --> F[Layer 3: Parallel Agent Execution]
    F --> G[Final Aggregator Agent]
    G --> H[Output Response]
    
    subgraph "Agent Layer Details"
        I[Agent 1] --> J[Agent Results]
        K[Agent 2] --> J
        L[Agent N] --> J
    end
    
    subgraph "Processing Flow"
        M[Previous Context] --> N[Current Task]
        N --> O[Agent Processing]
        O --> P[Aggregation]
        P --> M
    end
```


The `MixtureOfAgents` class represents a mixture of agents operating within a swarm. The workflow of the swarm follows a parallel → sequential → parallel → final output agent process. This implementation is inspired by concepts discussed in the paper: [https://arxiv.org/pdf/2406.04692](https://arxiv.org/pdf/2406.04692).

The class is designed to manage a collection of agents, orchestrate their execution in layers, and handle the final aggregation of their outputs through a designated final agent. This architecture facilitates complex, multi-step processing where intermediate results are refined through successive layers of agent interactions.

## Class Definition

### MixtureOfAgents

```python
class MixtureOfAgents(BaseSwarm):
```

### Attributes

| Attribute        | Type         | Description                                                                         | Default                         |
|------------------|--------------|-------------------------------------------------------------------------------------|---------------------------------|
| `agents`         | `List[Agent]`| The list of agents in the swarm.                                                    | `None`                          |
| `flow`           | `str`        | The flow of the swarm.                                                              | `parallel -> sequential -> parallel -> final output agent` |
| `max_loops`      | `int`        | The maximum number of loops to run.                                                 | `1`                             |
| `verbose`        | `bool`       | Flag indicating whether to print verbose output.                                    | `True`                          |
| `layers`         | `int`        | The number of layers in the swarm.                                                  | `3`                             |
| `rules`          | `str`        | The rules for the swarm.                                                            | `None`                          |
| `final_agent`    | `Agent`      | The agent to handle the final output processing.                                    | `None`                          |
| `auto_save`      | `bool`       | Flag indicating whether to auto-save the metadata to a file.                        | `False`                         |
| `saved_file_name`| `str`        | The name of the file where the metadata will be saved.                              | `"moe_swarm.json"`              |

## Methods

### `__init__`

#### Parameters

| Parameter        | Type         | Description                                                                                   | Default                                |
|------------------|--------------|-----------------------------------------------------------------------------------------------|----------------------------------------|
| `name`           | `str`        | The name of the swarm.                                                                        | `"MixtureOfAgents"`                    |
| `description`    | `str`        | A brief description of the swarm.                                                             | `"A swarm of agents that run in parallel and sequentially."` |
| `agents`         | `List[Agent]`| The list of agents in the swarm.                                                              | `None`                                 |
| `max_loops`      | `int`        | The maximum number of loops to run.                                                           | `1`                                    |
| `verbose`        | `bool`       | Flag indicating whether to print verbose output.                                              | `True`                                 |
| `layers`         | `int`        | The number of layers in the swarm.                                                            | `3`                                    |
| `rules`          | `str`        | The rules for the swarm.                                                                      | `None`                                 |
| `final_agent`    | `Agent`      | The agent to handle the final output processing.                                              | `None`                                 |
| `auto_save`      | `bool`       | Flag indicating whether to auto-save the metadata to a file.                                  | `False`                                |
| `saved_file_name`| `str`        | The name of the file where the metadata will be saved.                                        | `"moe_swarm.json"`                     |




#### Description

Initializes the swarm by logging the swarm name, description, and the number of agents.

#### Example Usage

```python
moe_swarm = MixtureOfAgents(agents=[agent1, agent2])
moe_swarm.swarm_initialization()  # Initializes the swarm
```

### `run`

```python
def run(self, task: str = None, *args, **kwargs):
```

#### Parameters

| Parameter | Type   | Description                     | Default |
|-----------|--------|---------------------------------|---------|
| `task`    | `str`  | The task to be performed by the swarm. | `None`  |
| `*args`   | `tuple`| Additional arguments.           | `None`  |
| `**kwargs`| `dict` | Additional keyword arguments.   | `None`  |

#### Returns

| Type  | Description                                 |
|-------|---------------------------------------------|
| `str` | The conversation history as a string.       |

#### Description

Runs the swarm with the given task, orchestrates the execution of agents through the specified layers, and returns the conversation history.

#### Example Usage

```python
moe_swarm = MixtureOfAgents(agents=[agent1, agent2], final_agent=final_agent)
history = moe_swarm.run(task="Solve this problem.")
print(history)
```

### `reliability_check`

```python
def reliability_check(self) -> None:
```

#### Description

Performs validation checks on the Mixture of Agents class to ensure all required components are properly configured. Raises ValueError if any checks fail.

#### Validation Checks:
- Verifies reference agents are provided
- Validates aggregator agent exists
- Checks aggregator system prompt is set
- Ensures layers count is valid (> 0)

### `_get_final_system_prompt`

```python
def _get_final_system_prompt(self, system_prompt: str, results: List[str]) -> str:
```

#### Description

Internal method that constructs a system prompt for subsequent layers by incorporating previous responses.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `system_prompt` | `str` | The initial system prompt |
| `results` | `List[str]` | List of previous responses |

#### Returns

| Type | Description |
|------|-------------|
| `str` | Combined system prompt with previous responses |

### `run_batched`

```python
def run_batched(self, tasks: List[str]) -> List[str]:
```

#### Description

Processes multiple tasks sequentially, returning a list of responses.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `tasks` | `List[str]` | List of tasks to process |

#### Returns

| Type | Description |
|------|-------------|
| `List[str]` | List of responses for each task |

### `run_concurrently`

```python
def run_concurrently(self, tasks: List[str]) -> List[str]:
```

#### Description

Processes multiple tasks concurrently using a ThreadPoolExecutor, optimizing for parallel execution.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `tasks` | `List[str]` | List of tasks to process concurrently |

#### Returns

| Type | Description |
|------|-------------|
| `List[str]` | List of responses for each task |

## Detailed Explanation

### Initialization

The `__init__` method initializes the swarm with the provided parameters, sets up the conversation rules, and invokes the initialization of the swarm. It also ensures the validity of the `agents` and `final_agent` attributes by calling the `agent_check` and `final_agent_check` methods respectively.

### Agent Validation

The `agent_check` method validates whether the `agents` attribute is a list of `Agent` instances, while the `final_agent_check` method validates whether the `final_agent` is an instance of `Agent`. These checks are crucial to ensure that the swarm operates correctly with the appropriate agent types.

### Swarm Initialization

The `swarm_initialization` method logs essential information about the swarm, including its name, description, and the number of agents. This provides a clear starting point for the swarm's operations and facilitates debugging and monitoring.

### Running the Swarm

The `run` method is the core of the `MixtureOfAgents` class. It orchestrates the execution of agents through multiple layers, collects their outputs, and processes the final output using the `final_agent`. The conversation history is maintained and updated throughout this process, allowing for a seamless flow of information and responses.

During each layer, the method iterates over the agents, invokes their `run` method with the current conversation history, and logs the outputs. These outputs are then added to the conversation, and the history is updated for the next layer.

After all layers are completed, the final output agent processes the entire conversation history, and the metadata is created and optionally saved to a file. This metadata includes details about the layers, agent runs, and final output, providing a comprehensive record of the swarm's execution.

## Additional Information and Tips

### Common Issues and Solutions

- **Type Errors**: Ensure that all agents in the `agents` list and the `final_agent` are instances of the `Agent` class. The `agent_check` and `final_agent_check` methods help validate this.
- **Verbose Logging**: Use the `verbose` flag to control the verbosity of the output. This can help with debugging or reduce clutter in the logs.
- **Auto-Save Feature**: Utilize the `auto_save` flag to automatically save the metadata to a file. This can be useful for keeping records of the swarm's operations without manual intervention.

### References and Resources

For further reading and background information on the concepts used in the `MixtureOfAgents` class, refer to the paper: [https://arxiv.org/pdf/2406.04692](https://arxiv.org/pdf/2406.04692).

### Usage Examples

#### Example 1: Basic Initialization and Run

```python
from swarms import MixtureOfAgents, Agent

# Define agents
director = Agent(
    agent_name="Director",
    system_prompt="Directs the tasks for the accountants",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize accountant 1
accountant1 = Agent(
    agent_name="Accountant1",
    system_prompt="Prepares financial statements",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize accountant 2
accountant2 = Agent(
    agent_name="Accountant2",
    system_prompt="Audits financial records",
    model_name="gpt-4.1",
    max_loops=1,
)


# Initialize the MixtureOfAgents
moe_swarm = MixtureOfAgents(agents=[director, accountant1, accountant2], final_agent=director)

# Run the swarm
history = moe_swarm.run(task="Perform task X.")
print(history)
```

#### Example 2: Verbose Output and Auto-Save

```python
from swarms import MixtureOfAgents, Agent

# Define Agents
director = Agent(
    agent_name="Director",
    system_prompt="Directs the tasks for the accountants",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize accountant 1
accountant1 = Agent(
    agent_name="Accountant1",
    system_prompt="Prepares financial statements",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize accountant 2
accountant2 = Agent(
    agent_name="Accountant2",
    system_prompt="Audits financial records",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the MixtureOfAgents with verbose output and auto-save enabled
moe_swarm = MixtureOfAgents(
    agents=[director, accountant1, accountant2],
    final_agent=director,
    verbose=True,
    auto_save=True
)

# Run the swarm
history = moe_swarm.run(task="Analyze data set Y.")
print(history)
```

#### Example 3: Custom Rules and Multiple Layers

```python
from swarms import MixtureOfAgents, Agent


# Define agents
# Initialize the director agent
director = Agent(
    agent_name="Director",
    system_prompt="Directs the tasks for the accountants",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize accountant 1
accountant1 = Agent(
    agent_name="Accountant1",
    system_prompt="Prepares financial statements",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize accountant 2
accountant2 = Agent(
    agent_name="Accountant2",
    system_prompt="Audits financial records",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the MixtureOfAgents with custom rules and multiple layers
moe_swarm = MixtureOfAgents(
    agents=[director, accountant1, accountant2],
    final_agent=director,
    layers=5,
    rules="Custom rules for the swarm"
)

# Run the swarm
history = moe_swarm.run(task="Optimize process Z.")
print(history)
```

This comprehensive documentation provides a detailed understanding of the `MixtureOfAgents` class, its attributes, methods, and usage. The examples illustrate how to initialize and run the swarm, demonstrating its flexibility and capability to handle various tasks and configurations.


# Conclusion

The `MixtureOfAgents` class is a powerful and flexible framework for managing and orchestrating a swarm of agents. By following a structured approach of parallel and sequential processing, it enables the implementation of complex multi-step workflows where intermediate results are refined through multiple layers of agent interactions. This architecture is particularly suitable for tasks that require iterative processing, collaboration among diverse agents, and sophisticated aggregation of outputs.

### Key Takeaways

| Feature                          | Description                                                                                                                                                                                                                 |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Flexible Initialization**       | The class allows for customizable initialization with various parameters, enabling users to tailor the swarm's configuration to their specific needs.                                                                       |
| **Robust Agent Management**       | Built-in validation methods ensure that all agents and the final agent are correctly instantiated, preventing runtime errors and facilitating smooth execution.                                                             |
| **Layered Processing**            | The layered approach to processing allows for intermediate results to be iteratively refined, enhancing the overall output quality.                                                                                        |
| **Verbose Logging and Auto-Save** | Features such as verbose logging and auto-save aid in debugging, monitoring, and record-keeping, providing transparency and ease of management.                                                                             |
| **Comprehensive Documentation**   | Detailed class and method documentation, along with numerous usage examples, provide a clear and thorough understanding of how to leverage the `MixtureOfAgents` class effectively.                                         |

### Practical Applications

The `MixtureOfAgents` class can be applied in various domains, including but not limited to:

- **Natural Language Processing (NLP)**: Managing a swarm of NLP models to process, analyze, and synthesize text.
- **Data Analysis**: Coordinating multiple data analysis agents to process and interpret complex data sets.
- **Optimization Problems**: Running a swarm of optimization algorithms to solve complex problems in fields such as logistics, finance, and engineering.
- **AI Research**: Implementing experimental setups that require the collaboration of multiple AI models or agents to explore new methodologies and approaches.

### Future Extensions

The `MixtureOfAgents` framework provides a solid foundation for further extensions and customizations, including:

- **Dynamic Layer Configuration**: Allowing layers to be added or removed dynamically based on the task requirements or intermediate results.
- **Advanced Agent Communication**: Enhancing the communication protocols between agents to allow for more sophisticated information exchange.
- **Integration with Other Frameworks**: Seamlessly integrating with other machine learning or data processing frameworks to leverage their capabilities within the swarm architecture.

In conclusion, the `MixtureOfAgents` class represents a versatile and efficient solution for orchestrating multi-agent systems, facilitating complex task execution through its structured and layered approach. By harnessing the power of parallel and sequential processing, it opens up new possibilities for tackling intricate problems across various domains.

## Additional Examples

### Example 4: Batch Processing

```python
from swarms import MixtureOfAgents, Agent

# Initialize agents as in previous examples
director = Agent(
    agent_name="Director",
    system_prompt="Directs the tasks for the accountants",
    model_name="gpt-4.1",
    max_loops=1,

)

accountant1 = Agent(
    agent_name="Accountant1",
    system_prompt="Prepares financial statements",
    model_name="gpt-4.1",
    max_loops=1,
)

accountant2 = Agent(
    agent_name="Accountant2",
    system_prompt="Audits financial records",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize MixtureOfAgents
moe_swarm = MixtureOfAgents(
    agents=[director, accountant1, accountant2],
    final_agent=director
)

# Process multiple tasks in batch
tasks = [
    "Analyze Q1 financial statements",
    "Review tax compliance",
    "Prepare budget forecast"
]
results = moe_swarm.run_batched(tasks)
for task, result in zip(tasks, results):
    print(f"Task: {task}\nResult: {result}\n")
```

### Example 5: Concurrent Processing

```python
from swarms import MixtureOfAgents, Agent

# Initialize agents as before
# ... agent initialization code ...

# Initialize MixtureOfAgents
moe_swarm = MixtureOfAgents(
    agents=[director, accountant1, accountant2],
    final_agent=director
)

# Process multiple tasks concurrently
tasks = [
    "Generate monthly report",
    "Audit expense claims",
    "Update financial projections",
    "Review investment portfolio"
]
results = moe_swarm.run_concurrently(tasks)
for task, result in zip(tasks, results):
    print(f"Task: {task}\nResult: {result}\n")
```



--------------------------------------------------

# File: swarms/structs/model_router.md

# ModelRouter Docs

The ModelRouter is an intelligent routing system that automatically selects and executes AI models based on task requirements. It leverages a function-calling architecture to analyze tasks and recommend the optimal model and provider combination for each specific use case.





### Key Features

- Dynamic model selection based on task complexity and requirements
- Multi-provider support (OpenAI, Anthropic, Google, etc.)
- Concurrent and asynchronous execution capabilities
- Batch processing with memory
- Automatic error handling and retries
- Provider-aware routing
- Cost optimization

### Constructor Arguments

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| system_prompt | str | model_router_system_prompt | Custom prompt for guiding model selection behavior |
| max_tokens | int | 4000 | Maximum token limit for model outputs |
| temperature | float | 0.5 | Control parameter for response randomness (0.0-1.0) |
| max_workers | int/str | 10 | Maximum concurrent workers ("auto" for CPU count) |
| api_key | str | None | API key for model access |
| max_loops | int | 1 | Maximum number of refinement iterations |
| *args | Any | None | Additional positional arguments |
| **kwargs | Any | None | Additional keyword arguments |

### Core Methods

#### run(task: str) -> str

Executes a single task through the model router with memory and refinement capabilities.

# Installation

1. Install the latest version of swarms using pip:

```bash
pip3 install -U swarms
```

2. Setup your API Keys in your .env file with the following:

```bash
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key
GOOGLE_API_KEY=your_google_api_key
# Add more API keys as needed following litellm format
```


```python
from swarms import ModelRouter

router = ModelRouter()

# Simple text analysis
result = router.run("Analyze the sentiment and key themes in this customer feedback")

# Complex reasoning task
complex_result = router.run("""
Evaluate the following business proposal:
- Initial investment: $500,000
- Projected ROI: 25% annually
- Market size: $2B
- Competition: 3 major players
Provide detailed analysis and recommendations.
""")
```

#### batch_run(tasks: list) -> list
Executes multiple tasks sequentially with result aggregation.

```python
# Multiple analysis tasks
tasks = [
    "Analyze Q1 financial performance",
    "Predict Q2 market trends",
    "Evaluate competitor strategies",
    "Generate growth recommendations"
]

results = router.batch_run(tasks)

# Process results
for task, result in zip(tasks, results):
    print(f"Task: {task}\nResult: {result}\n")
```

#### concurrent_run(tasks: list) -> list
Parallel execution of multiple tasks using thread pooling.

```python
import asyncio
from typing import List

# Define multiple concurrent tasks
analysis_tasks = [
    "Perform technical analysis of AAPL stock",
    "Analyze market sentiment from social media",
    "Generate trading signals",
    "Calculate risk metrics"
]

# Execute tasks concurrently
results = router.concurrent_run(analysis_tasks)

# Process results with error handling
for task, result in zip(analysis_tasks, results):
    try:
        processed_result = process_analysis(result)
        save_to_database(processed_result)
    except Exception as e:
        log_error(f"Error processing {task}: {str(e)}")
```

#### async_run(task: str) -> asyncio.Task
Asynchronous task execution with coroutine support.

```python
async def process_data_stream():
    tasks = []
    async for data in data_stream:
        task = await router.async_run(f"Process data: {data}")
        tasks.append(task)
    
    results = await asyncio.gather(*tasks)
    return results

# Usage in async context
async def main():
    router = ModelRouter()
    results = await process_data_stream()
```

### Advanced Usage Examples

#### Financial Analysis System

```python
from swarms import ModelRouter
from typing import Dict, List
import pandas as pd

class FinancialAnalysisSystem:
    def __init__(self):
        self.router = ModelRouter(
            temperature=0.3,  # Lower temperature for more deterministic outputs
            max_tokens=8000,  # Higher token limit for detailed analysis
            max_loops=2  # Allow for refinement iteration
        )
    
    def analyze_company_financials(self, financial_data: Dict) -> Dict:
        analysis_task = f"""
        Perform comprehensive financial analysis:
        
        Financial Metrics:
        - Revenue: ${financial_data['revenue']}M
        - EBITDA: ${financial_data['ebitda']}M
        - Debt/Equity: {financial_data['debt_equity']}
        - Working Capital: ${financial_data['working_capital']}M
        
        Required Analysis:
        1. Profitability assessment
        2. Liquidity analysis
        3. Growth projections
        4. Risk evaluation
        5. Investment recommendations
        
        Provide detailed insights and actionable recommendations.
        """
        
        result = self.router.run(analysis_task)
        return self._parse_analysis_result(result)
    
    def _parse_analysis_result(self, result: str) -> Dict:
        # Implementation of result parsing
        pass

# Usage
analyzer = FinancialAnalysisSystem()
company_data = {
    'revenue': 150,
    'ebitda': 45,
    'debt_equity': 0.8,
    'working_capital': 25
}

analysis = analyzer.analyze_company_financials(company_data)
```

#### Healthcare Data Processing Pipeline

```python
from swarms import ModelRouter
import pandas as pd
from typing import List, Dict

class MedicalDataProcessor:
    def __init__(self):
        self.router = ModelRouter(
            max_workers="auto",  # Automatic worker scaling
            temperature=0.2,     # Conservative temperature for medical analysis
            system_prompt="""You are a specialized medical data analyzer focused on:
            1. Clinical terminology interpretation
            2. Patient data analysis
            3. Treatment recommendation review
            4. Medical research synthesis"""
        )
    
    async def process_patient_records(self, records: List[Dict]) -> List[Dict]:
        analysis_tasks = []
        
        for record in records:
            task = f"""
            Analyze patient record:
            - Age: {record['age']}
            - Symptoms: {', '.join(record['symptoms'])}
            - Vital Signs: {record['vitals']}
            - Medications: {', '.join(record['medications'])}
            - Lab Results: {record['lab_results']}
            
            Provide:
            1. Symptom analysis
            2. Medication interaction check
            3. Lab results interpretation
            4. Treatment recommendations
            """
            analysis_tasks.append(task)
        
        results = await asyncio.gather(*[
            self.router.async_run(task) for task in analysis_tasks
        ])
        
        return [self._parse_medical_analysis(r) for r in results]
    
    def _parse_medical_analysis(self, analysis: str) -> Dict:
        # Implementation of medical analysis parsing
        pass

# Usage
async def main():
    processor = MedicalDataProcessor()
    patient_records = [
        {
            'age': 45,
            'symptoms': ['fever', 'cough', 'fatigue'],
            'vitals': {'bp': '120/80', 'temp': '38.5C'},
            'medications': ['lisinopril', 'metformin'],
            'lab_results': 'WBC: 11,000, CRP: 2.5'
        }
        # More records...
    ]
    
    analyses = await processor.process_patient_records(patient_records)
```

#### Natural Language Processing Pipeline

```python
from swarms import ModelRouter
from typing import List, Dict
import asyncio

class NLPPipeline:
    def __init__(self):
        self.router = ModelRouter(
            temperature=0.4,
            max_loops=2
        )
    
    def process_documents(self, documents: List[str]) -> List[Dict]:
        tasks = [self._create_nlp_task(doc) for doc in documents]
        results = self.router.concurrent_run(tasks)
        return [self._parse_nlp_result(r) for r in results]
    
    def _create_nlp_task(self, document: str) -> str:
        return f"""
        Perform comprehensive NLP analysis:
        
        Text: {document}
        
        Required Analysis:
        1. Entity recognition
        2. Sentiment analysis
        3. Topic classification
        4. Key phrase extraction
        5. Intent detection
        
        Provide structured analysis with confidence scores.
        """
    
    def _parse_nlp_result(self, result: str) -> Dict:
        # Implementation of NLP result parsing
        pass

# Usage
pipeline = NLPPipeline()
documents = [
    "We're extremely satisfied with the new product features!",
    "The customer service response time needs improvement.",
    "Looking to upgrade our subscription plan next month."
]

analyses = pipeline.process_documents(documents)
```

### Available Models and Use Cases

| Model | Provider | Optimal Use Cases | Characteristics |
|-------|----------|-------------------|-----------------|
| gpt-4-turbo | OpenAI | Complex reasoning, Code generation, Creative writing | High accuracy, Latest knowledge cutoff |
| claude-3-opus | Anthropic | Research analysis, Technical documentation, Long-form content | Strong reasoning, Detailed outputs |
| gemini-pro | Google | Multimodal tasks, Code generation, Technical analysis | Fast inference, Strong coding abilities |
| mistral-large | Mistral | General tasks, Content generation, Classification | Open source, Good price/performance |
| deepseek-reasoner | DeepSeek | Mathematical analysis, Logic problems, Scientific computing | Specialized reasoning capabilities |

### Provider Capabilities

| Provider | Strengths | Best For | Integration Notes |
|----------|-----------|-----------|------------------|
| OpenAI | Consistent performance, Strong reasoning | Production systems, Complex tasks | Requires API key setup |
| Anthropic | Safety features, Detailed analysis | Research, Technical writing | Claude-specific formatting |
| Google | Technical tasks, Multimodal support | Code generation, Analysis | Vertex AI integration available |
| Groq | High-speed inference | Real-time applications | Optimized for specific models |
| DeepSeek | Specialized reasoning | Scientific computing | Custom API integration |
| Mistral | Open source flexibility | General applications | Self-hosted options available |


### Performance Optimization Tips

1. Token Management
   - Set appropriate max_tokens based on task complexity
   - Monitor token usage for cost optimization
   - Use streaming for long outputs

2. Concurrency Settings
   - Adjust max_workers based on system resources
   - Use "auto" workers for optimal CPU utilization
   - Monitor memory usage with large batch sizes

3. Temperature Tuning
   - Lower (0.1-0.3) for factual/analytical tasks
   - Higher (0.7-0.9) for creative tasks
   - Mid-range (0.4-0.6) for balanced outputs

4. System Prompts
   - Customize for specific domains
   - Include relevant context
   - Define clear output formats

### Dependencies

- asyncio: Asynchronous I/O support
- concurrent.futures: Thread pool execution
- pydantic: Data validation
- litellm: LLM interface standardization


--------------------------------------------------

# File: swarms/structs/multi_agent_collaboration_examples.md

# Multi-Agent Examples


### `SequentialWorkflow`
Sequential Workflow enables you to sequentially execute tasks with `Agent` and then pass the output into the next agent and onwards until you have specified your max loops.

```python
from swarms import Agent, SequentialWorkflow

from swarm_models import Anthropic


# Initialize the language model agent (e.g., GPT-3)
llm = Anthropic()

# Initialize agents for individual tasks
agent1 = Agent(
    agent_name="Blog generator",
    system_prompt="Generate a blog post like stephen king",
    llm=llm,
    max_loops=1,
    dashboard=False,
    tools=[],
)
agent2 = Agent(
    agent_name="summarizer",
    system_prompt="Sumamrize the blog post",
    llm=llm,
    max_loops=1,
    dashboard=False,
    tools=[],
)

# Create the Sequential workflow
workflow = SequentialWorkflow(
    agents=[agent1, agent2], max_loops=1, verbose=False
)

# Run the workflow
workflow.run(
    "Generate a blog post on how swarms of agents can help businesses grow."
)

```

------

## `AgentRearrange`
Inspired by Einops and einsum, this orchestration techniques enables you to map out the relationships between various agents. For example you specify linear and sequential relationships like `a -> a1 -> a2 -> a3` or concurrent relationships where the first agent will send a message to 3 agents all at once: `a -> a1, a2, a3`. You can customize your workflow to mix sequential and concurrent relationships. [Docs Available:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)

```python
from swarms import Agent, AgentRearrange


from swarm_models import Anthropic

# Initialize the director agent

director = Agent(
    agent_name="Director",
    system_prompt="Directs the tasks for the workers",
    llm=Anthropic(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="director.json",
)


# Initialize worker 1

worker1 = Agent(
    agent_name="Worker1",
    system_prompt="Generates a transcript for a youtube video on what swarms are",
    llm=Anthropic(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="worker1.json",
)


# Initialize worker 2
worker2 = Agent(
    agent_name="Worker2",
    system_prompt="Summarizes the transcript generated by Worker1",
    llm=Anthropic(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="worker2.json",
)


# Create a list of agents
agents = [director, worker1, worker2]

# Define the flow pattern
flow = "Director -> Worker1 -> Worker2"

# Using AgentRearrange class
agent_system = AgentRearrange(agents=agents, flow=flow)
output = agent_system.run(
    "Create a format to express and communicate swarms of llms in a structured manner for youtube"
)
print(output)

```

## `HierarhicalSwarm`
Coming soon...


## `GraphSwarm`

```python
from swarms.structs.agent import Agent              
from swarms import Edge, GraphWorkflow, Node, NodeType  


# Initialize two agents with GPT-4o-mini
agent1 = Agent(
    agent_name="agent1",
    system_prompt="You are an autonomous agent executing workflow tasks.",
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=True,
    saved_state_path="agent1_state.json",
    model_name="gpt-4o-mini",
)  

agent2 = Agent(
    agent_name="agent2",
    system_prompt="You are an autonomous agent executing workflow tasks.",
    max_loops=1,
    autosave=True,
    dashboard=False,
    verbose=True,
    saved_state_path="agent2_state.json",
    model_name="gpt-4o-mini",
) 

def sample_task():
    print("Running sample task")
    return "Task completed"

# Build the DAG
wf = GraphWorkflow()
wf.add_node(Node(id="agent1", type=NodeType.AGENT, agent=agent1))
wf.add_node(Node(id="agent2", type=NodeType.AGENT, agent=agent2))
wf.add_node(Node(id="task1",  type=NodeType.TASK, callable=sample_task))  

# Connect agents to the task
wf.add_edge(Edge(source="agent1", target="task1"))
wf.add_edge(Edge(source="agent2", target="task1"))  

wf.set_entry_points(["agent1", "agent2"])
wf.set_end_points(["task1"])  

# Visualize and run
print(wf.visualize())  
results = wf.run()    
print("Execution results:", results)

```

## `MixtureOfAgents`
This is an implementation from the paper: "Mixture-of-Agents Enhances Large Language Model Capabilities" by together.ai, it achieves SOTA on AlpacaEval 2.0, MT-Bench and FLASK, surpassing GPT-4 Omni. Great for tasks that need to be parallelized and then sequentially fed into another loop

```python
from swarms import Agent, OpenAIChat, MixtureOfAgents

# Initialize the director agent
director = Agent(
    agent_name="Director",
    system_prompt="Directs the tasks for the accountants",
    llm=OpenAIChat(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="director.json",
)

# Initialize accountant 1
accountant1 = Agent(
    agent_name="Accountant1",
    system_prompt="Prepares financial statements",
    llm=OpenAIChat(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="accountant1.json",
)

# Initialize accountant 2
accountant2 = Agent(
    agent_name="Accountant2",
    system_prompt="Audits financial records",
    llm=OpenAIChat(),
    max_loops=1,
    dashboard=False,
    streaming_on=True,
    verbose=True,
    stopping_token="<DONE>",
    state_save_file_type="json",
    saved_state_path="accountant2.json",
)

# Create a list of agents
agents = [director, accountant1, accountant2]


# Swarm
swarm = MixtureOfAgents(
    name="Mixture of Accountants",
    agents=agents,
    layers=3,
    final_agent=director,
)


# Run the swarm
out = swarm.run("Prepare financial statements and audit financial records")
print(out)
```


--------------------------------------------------

# File: swarms/structs/multi_agent_orchestration.md

# Multi-Agent Orchestration:
Swarms was designed to faciliate the communication between many different and specialized agents from a vast array of other frameworks such as langchain, autogen, crew, and more.

In traditional swarm theory, there are many types of swarms usually for very specialized use-cases and problem sets. Such as Hiearchical and sequential are great for accounting and sales, because there is usually a boss coordinator agent that distributes a workload to other specialized agents.


| **Name**                      | **Description**                                                                                                                                                         | **Code Link**               | **Use Cases**                                                                                     |
|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|---------------------------------------------------------------------------------------------------|
| Hierarchical Swarms           | A system where agents are organized in a hierarchy, with higher-level agents coordinating lower-level agents to achieve complex tasks.                                   | [Code Link](#)              | Manufacturing process optimization, multi-level sales management, healthcare resource coordination |
| Agent Rearrange               | A setup where agents rearrange themselves dynamically based on the task requirements and environmental conditions.                                                       | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)              | Adaptive manufacturing lines, dynamic sales territory realignment, flexible healthcare staffing  |
| Concurrent Workflows          | Agents perform different tasks simultaneously, coordinating to complete a larger goal.                                                                                  | [Code Link](#)              | Concurrent production lines, parallel sales operations, simultaneous patient care processes       |
| Sequential Coordination       | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next.                                                           | [Code Link](https://docs.swarms.world/en/latest/swarms/structs/sequential_workflow/)              | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows     |
| Parallel Processing           | Agents work on different parts of a task simultaneously to speed up the overall process.                                                                                | [Code Link](#)              | Parallel data processing in manufacturing, simultaneous sales analytics, concurrent medical tests  |




--------------------------------------------------

# File: swarms/structs/multi_agent_router.md

# MultiAgentRouter Documentation

The MultiAgentRouter is a sophisticated task routing system that efficiently delegates tasks to specialized AI agents. It uses a "boss" agent to analyze incoming tasks and route them to the most appropriate specialized agent based on their capabilities and expertise.

## Table of Contents
- [Installation](#installation)
- [Key Components](#key-components)
- [Arguments](#arguments)
- [Methods](#methods)
- [Usage Examples](#usage-examples)
  - [Healthcare](#healthcare-example)
  - [Finance](#finance-example)
  - [Legal](#legal-example)
  - [Research](#research-example)

## Installation

```bash
pip install swarms
```

## Key Components

### Arguments Table

| Argument | Type | Default | Description |
|----------|------|---------|-------------|
| name | str | "swarm-router" | Name identifier for the router instance |
| description | str | "Routes tasks..." | Description of the router's purpose |
| agents | List[Agent] | [] | List of available specialized agents |
| model | str | "gpt-4o-mini" | Base language model for the boss agent |
| temperature | float | 0.1 | Temperature parameter for model outputs |
| shared_memory_system | callable | None | Optional shared memory system |
| output_type | Literal["json", "string"] | "json" | Format of agent outputs |
| execute_task | bool | True | Whether to execute routed tasks |

### Methods Table

| Method | Arguments | Returns | Description |
|--------|-----------|---------|-------------|
| route_task | task: str | dict | Routes a single task to appropriate agent |
| batch_run | tasks: List[str] | List[dict] | Sequentially routes multiple tasks |
| concurrent_batch_run | tasks: List[str] | List[dict] | Concurrently routes multiple tasks |
| query_ragent | task: str | str | Queries the research agent |
| find_agent_in_list | agent_name: str | Optional[Agent] | Finds agent by name |

## Production Examples

### Healthcare Example

```python
from swarms import Agent, MultiAgentRouter

# Define specialized healthcare agents
agents = [
    Agent(
        agent_name="DiagnosisAgent",
        description="Specializes in preliminary symptom analysis and diagnostic suggestions",
        system_prompt="""You are a medical diagnostic assistant. Analyze symptoms and provide 
        evidence-based diagnostic suggestions, always noting this is for informational purposes 
        only and recommending professional medical consultation.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="TreatmentPlanningAgent",
        description="Assists in creating treatment plans and medical documentation",
        system_prompt="""You are a treatment planning assistant. Help create structured 
        treatment plans based on confirmed diagnoses, following medical best practices 
        and guidelines.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="MedicalResearchAgent",
        description="Analyzes medical research papers and clinical studies",
        system_prompt="""You are a medical research analyst. Analyze and summarize medical 
        research papers, clinical trials, and scientific studies, providing evidence-based 
        insights.""",
        model_name="openai/gpt-4o"
    )
]

# Initialize router
healthcare_router = MultiAgentRouter(
    name="Healthcare-Router",
    description="Routes medical and healthcare-related tasks to specialized agents",
    agents=agents,
    model="gpt-4o",
    temperature=0.1
)

# Example usage
try:
    # Process medical case
    case_analysis = healthcare_router.route_task(
        """Patient presents with: 
        - Persistent dry cough for 3 weeks
        - Mild fever (38.1°C)
        - Fatigue
        Analyze symptoms and suggest potential diagnoses for healthcare provider review."""
    )
    
    # Research treatment options
    treatment_research = healthcare_router.route_task(
        """Find recent clinical studies on treatment efficacy for community-acquired 
        pneumonia in adult patients, focusing on outpatient care."""
    )
    
    # Process multiple cases concurrently
    cases = [
        "Case 1: Patient symptoms...",
        "Case 2: Patient symptoms...",
        "Case 3: Patient symptoms..."
    ]
    concurrent_results = healthcare_router.concurrent_batch_run(cases)
    
except Exception as e:
    logger.error(f"Error in healthcare processing: {str(e)}")
```

### Finance Example

```python
# Define specialized finance agents
finance_agents = [
    Agent(
        agent_name="MarketAnalysisAgent",
        description="Analyzes market trends and provides trading insights",
        system_prompt="""You are a financial market analyst. Analyze market data, trends, 
        and indicators to provide evidence-based market insights and trading suggestions.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="RiskAssessmentAgent",
        description="Evaluates financial risks and compliance requirements",
        system_prompt="""You are a risk assessment specialist. Analyze financial data 
        and operations for potential risks, ensuring regulatory compliance and suggesting 
        risk mitigation strategies.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="InvestmentAgent",
        description="Provides investment strategies and portfolio management",
        system_prompt="""You are an investment strategy specialist. Develop and analyze 
        investment strategies, portfolio allocations, and provide long-term financial 
        planning guidance.""",
        model_name="openai/gpt-4o"
    )
]

# Initialize finance router
finance_router = MultiAgentRouter(
    name="Finance-Router",
    description="Routes financial analysis and investment tasks",
    agents=finance_agents
)

# Example tasks
tasks = [
    """Analyze current market conditions for technology sector, focusing on:
    - AI/ML companies
    - Semiconductor manufacturers
    - Cloud service providers
    Provide risk assessment and investment opportunities.""",
    
    """Develop a diversified portfolio strategy for a conservative investor with:
    - Investment horizon: 10 years
    - Risk tolerance: Low to medium
    - Initial investment: $500,000
    - Monthly contribution: $5,000""",
    
    """Conduct risk assessment for a fintech startup's crypto trading platform:
    - Regulatory compliance requirements
    - Security measures
    - Operational risks
    - Market risks"""
]

# Process tasks concurrently
results = finance_router.concurrent_batch_run(tasks)
```

### Legal Example

```python
# Define specialized legal agents
legal_agents = [
    Agent(
        agent_name="ContractAnalysisAgent",
        description="Analyzes legal contracts and documents",
        system_prompt="""You are a legal document analyst. Review contracts and legal 
        documents for key terms, potential issues, and compliance requirements.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="ComplianceAgent",
        description="Ensures regulatory compliance and updates",
        system_prompt="""You are a legal compliance specialist. Monitor and analyze 
        regulatory requirements, ensuring compliance and suggesting necessary updates 
        to policies and procedures.""",
        model_name="openai/gpt-4o"
    ),
    Agent(
        agent_name="LegalResearchAgent",
        description="Conducts legal research and case analysis",
        system_prompt="""You are a legal researcher. Research relevant cases, statutes, 
        and regulations, providing comprehensive legal analysis and citations.""",
        model_name="openai/gpt-4o"
    )
]

# Initialize legal router
legal_router = MultiAgentRouter(
    name="Legal-Router",
    description="Routes legal analysis and compliance tasks",
    agents=legal_agents
)

# Example usage for legal department
contract_analysis = legal_router.route_task(
    """Review the following software licensing agreement:
    [contract text]
    
    Analyze for:
    1. Key terms and conditions
    2. Potential risks and liabilities
    3. Compliance with current regulations
    4. Suggested modifications"""
)
```

## Error Handling and Best Practices

1. Always use try-except blocks for task routing:
```python
try:
    result = router.route_task(task)
except Exception as e:
    logger.error(f"Task routing failed: {str(e)}")
```

2. Monitor agent performance:
```python
if result["execution"]["execution_time"] > 5.0:
    logger.warning(f"Long execution time for task: {result['task']['original']}")
```

3. Implement rate limiting for concurrent tasks:
```python
from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor(max_workers=5) as executor:
    results = router.concurrent_batch_run(tasks)
```

4. Regular agent validation:
```python
for agent in router.agents.values():
    if not agent.validate():
        logger.error(f"Agent validation failed: {agent.name}")
```

## Performance Considerations

1. Task Batching

- Group similar tasks together

- Use concurrent_batch_run for independent tasks

- Monitor memory usage with large batches

2. Model Selection

- Choose appropriate models based on task complexity

- Balance speed vs. accuracy requirements

- Consider cost implications

3. Response Caching

- Implement caching for frequently requested analyses

- Use shared memory system for repeated queries

- Regular cache invalidation for time-sensitive data

## Security Considerations

1. Data Privacy

- Implement data encryption

- Handle sensitive information appropriately

- Regular security audits

2. Access Control

- Implement role-based access

- Audit logging

- Regular permission reviews

## Monitoring and Logging

1. Performance Metrics

- Response times

- Success rates

- Error rates

- Resource utilization

2. Logging

- Use structured logging

- Implement log rotation

- Regular log analysis

3. Alerts

- Set up alerting for critical errors

- Monitor resource usage

- Track API rate limits

--------------------------------------------------

# File: swarms/structs/multi_swarm_orchestration.md

# Hierarchical Agent Orchestration Architectures

Hierarchical agent orchestration involves organizing multiple agents in structured layers to efficiently handle complex tasks. There are several key architectures available, each with distinct characteristics and use cases.

Here are the Hierarchical swarms we support:

| Architecture | Strengths | Weaknesses |
|--------------|-----------|------------|
| HHCS | - Clear task routing<br>- Specialized swarm handling<br>- Parallel processing capability<br>- Good for complex multi-domain tasks | - More complex setup<br>- Overhead in routing<br>- Requires careful swarm design |
| Auto Agent Builder | - Dynamic agent creation<br>- Flexible scaling<br>- Self-organizing<br>- Good for evolving tasks | - Higher resource usage<br>- Potential creation overhead<br>- May create redundant agents |
| SwarmRouter | - Multiple workflow types<br>- Simple configuration<br>- Flexible deployment<br>- Good for varied task types | - Less specialized than HHCS<br>- Limited inter-swarm communication<br>- May require manual type selection |



## Core Architectures

### 1. Hybrid Hierarchical-Cluster Swarm (HHCS)

Hybrid Hierarchical-Cluster Swarm (HHCS) is architecture that uses a Router Agent to analyze and distribute tasks to other swarms.

- Tasks are routed to specialized swarms based on their requirements

- Enables parallel processing through multiple specialized swarms

- Ideal for complex, multi-domain tasks and enterprise-scale operations

- Provides clear task routing but requires more complex setup


```mermaid
flowchart TD
    Start([Task Input]) --> RouterAgent[Router Agent]
    RouterAgent --> Analysis{Task Analysis}
    
    Analysis -->|Analyze Requirements| Selection[Swarm Selection]
    Selection -->|Select Best Swarm| Route[Route Task]
    
    Route --> Swarm1[Specialized Swarm 1]
    Route --> Swarm2[Specialized Swarm 2]
    Route --> SwarmN[Specialized Swarm N]
    
    Swarm1 -->|Process| Result1[Output 1]
    Swarm2 -->|Process| Result2[Output 2]
    SwarmN -->|Process| ResultN[Output N]
    
    Result1 --> Final[Final Output]
    Result2 --> Final
    ResultN --> Final
```

### 2. Auto Agent Builder

Auto Agent Builder is a dynamic agent architecture that creates specialized agents on-demand.

- Analyzes tasks and automatically builds appropriate agents for the job

- Maintains an agent pool that feeds into task orchestration

- Best suited for evolving requirements and dynamic workloads

- Self-organizing but may have higher resource usage

```mermaid
flowchart TD
    Task[Task Input] --> Builder[Agent Builder]
    Builder --> Analysis{Task Analysis}
    
    Analysis --> Create[Create Specialized Agents]
    Create --> Pool[Agent Pool]
    
    Pool --> Agent1[Specialized Agent 1]
    Pool --> Agent2[Specialized Agent 2]
    Pool --> AgentN[Specialized Agent N]
    
    Agent1 --> Orchestration[Task Orchestration]
    Agent2 --> Orchestration
    AgentN --> Orchestration
    
    Orchestration --> Result[Final Result]
```

### 3. SwarmRouter


SwarmRouter is a flexible system supporting multiple swarm architectures through a simple interface:

- Sequential workflows

- Concurrent workflows

- Hierarchical swarms

- Group chat interactions

- Simpler to configure and deploy compared to other architectures

- Best for general-purpose tasks and smaller scale operations

- Recommended for 5-20 agents.

```mermaid
flowchart TD
    Input[Task Input] --> Router[Swarm Router]
    Router --> TypeSelect{Swarm Type Selection}
    
    TypeSelect -->|Sequential| Seq[Sequential Workflow]
    TypeSelect -->|Concurrent| Con[Concurrent Workflow]
    TypeSelect -->|Hierarchical| Hier[Hierarchical Swarm]
    TypeSelect -->|Group| Group[Group Chat]
    
    Seq --> Output[Task Output]
    Con --> Output
    Hier --> Output
    Group --> Output
```

## Use Case Recommendations

### **HHCS**: Best for:
   
- Enterprise-scale operations

- Multi-domain problems

- Complex task routing

- Parallel processing needs

###  **Auto Agent Builder**: Best for:

- Dynamic workloads

- Evolving requirements

- Research and development

- Exploratory tasks

### **SwarmRouter**: Best for:

- General purpose tasks

- Quick deployment

- Mixed workflow types

- Smaller scale operations

## Documentation Links

### HHCS Documentation:

- [Hybrid Hierarchical-Cluster Swarm Documentation](https://docs.swarms.world/en/latest/swarms/structs/hhcs/)

- Covers detailed implementation, constructor arguments, and full examples

### Auto Agent Builder Documentation:
   
- [Agent Builder Documentation](https://docs.swarms.world/en/latest/swarms/structs/auto_agent_builder/)

- Includes enterprise use cases, best practices, and integration patterns

3. SwarmRouter Documentation:

- [SwarmRouter Documentation](https://docs.swarms.world/en/latest/swarms/structs/swarm_router/)

- Provides comprehensive API reference, advanced usage, and use cases

## Best Practices for Selection

### **Evaluate Task Complexity**
   
- Simple tasks → SwarmRouter

- Complex, multi-domain tasks → HHCS

- Dynamic, evolving tasks → Auto Agent Builder

### **Consider Scale**
   
- Small scale → SwarmRouter

- Large scale → HHCS

- Variable scale → Auto Agent Builder

### **Resource Availability**
   
- Limited resources → SwarmRouter

- Abundant resources → HHCS or Auto Agent Builder

- Dynamic resources → Auto Agent Builder

### **Development Time**

- Quick deployment → SwarmRouter

- Complex system → HHCS

- Experimental system → Auto Agent Builder


This documentation provides a high-level overview of the main hierarchical agent orchestration architectures available in the system. Each architecture has its own strengths and ideal use cases, and the choice between them should be based on specific project requirements, scale, and complexity.


--------------------------------------------------

# File: swarms/structs/multi_threaded_workflow.md

# MultiThreadedWorkflow Documentation

The `MultiThreadedWorkflow` class represents a multi-threaded workflow designed to execute tasks concurrently using a thread pool. This class is highly useful in scenarios where tasks need to be executed in parallel to improve performance and efficiency. The workflow ensures that tasks are managed in a priority-based queue, and it includes mechanisms for retrying failed tasks and optionally saving task results automatically.

## Class Definition

### `MultiThreadedWorkflow`

## Parameters

| Parameter     | Type                  | Default | Description                                                   |
|---------------|-----------------------|---------|---------------------------------------------------------------|
| `max_workers` | `int`                 | `5`     | The maximum number of worker threads in the thread pool.      |
| `autosave`    | `bool`                | `True`  | Flag indicating whether to automatically save task results.   |
| `tasks`       | `List[PriorityTask]`  | `None`  | List of priority tasks to be executed.                        |
| `retry_attempts` | `int`             | `3`     | The maximum number of retry attempts for failed tasks.        |
| `*args`       | `tuple`               |         | Variable length argument list.                                |
| `**kwargs`    | `dict`                |         | Arbitrary keyword arguments.                                  |

## Attributes

| Attribute        | Type               | Description                                                    |
|------------------|--------------------|----------------------------------------------------------------|
| `max_workers`    | `int`              | The maximum number of worker threads in the thread pool.       |
| `autosave`       | `bool`             | Flag indicating whether to automatically save task results.    |
| `retry_attempts` | `int`              | The maximum number of retry attempts for failed tasks.         |
| `tasks_queue`    | `PriorityQueue`    | The queue that holds the priority tasks.                       |
| `lock`           | `Lock`             | The lock used for thread synchronization.                      |

## Methods

### `run`


#### Description

The `run` method executes the tasks stored in the priority queue using a thread pool. It handles task completion, retries failed tasks up to a specified number of attempts, and optionally saves the results of tasks if the autosave flag is set.

#### Usage Example

```python
from swarms import MultiThreadedWorkflow, PriorityTask, Task

# Define some tasks
tasks = [PriorityTask(task=Task()), PriorityTask(task=Task())]

# Create a MultiThreadedWorkflow instance
workflow = MultiThreadedWorkflow(max_workers=3, autosave=True, tasks=tasks, retry_attempts=2)

# Run the workflow
results = workflow.run()
print(results)
```

### `_autosave_task_result`

#### Description

The `_autosave_task_result` method is responsible for saving the results of a task. It uses a thread lock to ensure that the autosave operation is thread-safe.

#### Usage Example

This method is intended for internal use and is typically called by the `run` method. However, here is an example of how it might be used directly:

```python
# Create a task and result
task = Task()
result = task.run()

# Autosave the result
workflow = MultiThreadedWorkflow()
workflow._autosave_task_result(task, result)
```

## Detailed Functionality and Usage

### Initialization

When an instance of `MultiThreadedWorkflow` is created, it initializes the following:

- **max_workers**: Sets the maximum number of threads that can run concurrently.
- **autosave**: Determines if the task results should be saved automatically.
- **tasks**: Accepts a list of tasks that need to be executed. If no tasks are provided, an empty list is used.
- **retry_attempts**: Sets the maximum number of retry attempts for failed tasks.
- **tasks_queue**: A priority queue to manage tasks based on their priority.
- **lock**: A threading lock to ensure thread-safe operations.

### Running Tasks

The `run` method performs the following steps:

1. **Initialize Results and Executor**: Creates a list to store results and a `ThreadPoolExecutor` to manage the threads.
2. **Submit Tasks**: Iterates over the tasks in the queue, submitting them to the executor for execution and storing the future objects.
3. **Monitor Completion**: Uses the `wait` function to monitor the completion of tasks. Once a task is completed, it retrieves the result or catches exceptions.
4. **Retry Mechanism**: If a task fails, it checks the number of attempts made and retries the task if the limit is not reached.
5. **Autosave**: If the `autosave` flag is set, the `_autosave_task_result` method is called to save the task results.

### Autosave Task Result

The `_autosave_task_result` method handles the saving of task results. It uses a threading lock to ensure that the save operation is not interrupted by other threads.

## Additional Information and Tips

- **Thread Safety**: The use of threading locks ensures that the operations are thread-safe, preventing race conditions.
- **Logging**: The class uses the logging module to log information about task completion, retries, and failures.
- **Error Handling**: The retry mechanism helps in handling transient errors by attempting to re-execute failed tasks.

## References and Resources

For more information on threading and concurrent execution in Python, refer to the following resources:

- [Python Threading Documentation](https://docs.python.org/3/library/threading.html)
- [Python Concurrent Futures Documentation](https://docs.python.org/3/library/concurrent.futures.html)


--------------------------------------------------

# File: swarms/structs/orchestration_methods.md

# Multi-Agent Orchestration Methods

Swarms provides a comprehensive suite of orchestration methods for coordinating multiple AI agents in structured conversations and decision-making processes. These methods enable sophisticated multi-agent interactions like debates, panel discussions, negotiations, and more.

## Overview


| Method                   | Orchestration Description                                                                 | Use Case                                   |
|--------------------------|------------------------------------------------------------------------------------------|--------------------------------------------|
| OneOnOneDebate           | Turn-based debates between two agents. Structured debates where two agents alternate turns presenting arguments. | Philosophical discussions, arguments       |
| ExpertPanelDiscussion    | Expert panel discussions with a moderator. Multiple experts discuss topics, guided by a moderator. | Professional discussions, expert opinions  |
| RoundTableDiscussion     | Round table discussions with multiple participants. Open discussions among several agents, each contributing equally. | Group discussions, brainstorming           |
| InterviewSeries          | Structured interviews with follow-up questions. One agent interviews another, with dynamic follow-up questions. | Q&A sessions, information gathering        |
| PeerReviewProcess        | Academic peer review processes. Simulated academic review, where agents critique and provide feedback. | Research review, feedback processes        |
| MediationSession         | Mediation sessions for conflict resolution. Agents participate in sessions to resolve disputes, often with a mediator. | Dispute resolution, negotiations           |
| BrainstormingSession     | Brainstorming sessions for idea generation. Collaborative sessions focused on generating new ideas. | Innovation, problem solving                |
| TrialSimulation          | Trial simulations with legal roles. Agents assume legal roles to simulate a courtroom trial. | Legal proceedings, case analysis           |
| CouncilMeeting           | Council meetings with voting procedures. Decision-making meetings where agents vote on proposals. | Governance, voting processes               |
| MentorshipSession        | Mentorship sessions with feedback loops. One or more agents mentor others, providing feedback and guidance. | Learning, guidance                         |
| NegotiationSession       | Complex negotiations between parties. Multi-party negotiations to reach agreements or resolve conflicts. | Business deals, agreements                 |

## OneOnOneDebate

### Description
Simulates a turn-based debate between two agents for a specified number of loops. Each agent takes turns responding to the other's arguments.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| max_loops | int | Number of conversational turns | No | 1 |
| agents | List[Agent] | Two agents for debate | Yes | None |
| img | str | Optional image input | No | None |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes debate between agents |

### Example

Full example: [Philosophy Discussion Example](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/philosophy_discussion_example.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import OneOnOneDebate

# Create debating agents
agent1 = Agent(name="Philosopher1")
agent2 = Agent(name="Philosopher2")

# Initialize debate
debate = OneOnOneDebate(
    max_loops=3,
    agents=[agent1, agent2]
)

# Run debate
result = debate.run("Is artificial intelligence consciousness possible?")
```

## ExpertPanelDiscussion

### Description
Simulates an expert panel discussion with a moderator guiding the conversation. Multiple experts provide insights on a topic with structured rounds.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| max_rounds | int | Number of discussion rounds | No | 3 |
| agents | List[Agent] | Expert panel participants | Yes | None |
| moderator | Agent | Discussion moderator | Yes | None |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes panel discussion |

### Example

Full example: [Healthcare Panel Discussion](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/healthcare_panel_discussion.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import ExpertPanelDiscussion

# Create expert agents
moderator = Agent(name="Moderator")
expert1 = Agent(name="AI_Expert")
expert2 = Agent(name="Ethics_Expert")
expert3 = Agent(name="Neuroscience_Expert")

# Initialize panel
panel = ExpertPanelDiscussion(
    max_rounds=2,
    agents=[expert1, expert2, expert3],
    moderator=moderator
)

# Run panel discussion
result = panel.run("What are the ethical implications of AGI development?")
```

## RoundTableDiscussion

### Description
Simulates a round table where each participant speaks in order, then the cycle repeats. Facilitated discussion with equal participation.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| max_cycles | int | Number of speaking cycles | No | 2 |
| agents | List[Agent] | Round table participants | Yes | None |
| facilitator | Agent | Discussion facilitator | Yes | None |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes round table discussion |

### Example

Full example: [AI Ethics Debate](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/ai_ethics_debate.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import RoundTableDiscussion

# Create participants
facilitator = Agent(name="Facilitator")
participant1 = Agent(name="Participant1")
participant2 = Agent(name="Participant2")
participant3 = Agent(name="Participant3")

# Initialize round table
roundtable = RoundTableDiscussion(
    max_cycles=2,
    agents=[participant1, participant2, participant3],
    facilitator=facilitator
)

# Run discussion
result = roundtable.run("How can we improve renewable energy adoption?")
```

## InterviewSeries

### Description
Conducts a structured interview with follow-up questions. Systematic Q&A with depth through follow-up questions.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| questions | List[str] | Prepared interview questions | No | Default questions |
| interviewer | Agent | Interviewer agent | Yes | None |
| interviewee | Agent | Interviewee agent | Yes | None |
| follow_up_depth | int | Follow-up questions per main question | No | 2 |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes interview series |

### Example

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import InterviewSeries

# Create agents
interviewer = Agent(name="Interviewer")
interviewee = Agent(name="Expert")

# Prepare questions
questions = [
    "What is your background in AI?",
    "How do you see AI evolving in the next decade?",
    "What are the biggest challenges in AI development?"
]

# Initialize interview
interview = InterviewSeries(
    questions=questions,
    interviewer=interviewer,
    interviewee=interviewee,
    follow_up_depth=2
)

# Run interview
result = interview.run("AI Development and Future Prospects")
```

## PeerReviewProcess

### Description
Simulates academic peer review with multiple reviewers and author responses. Structured feedback and revision process.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| reviewers | List[Agent] | Reviewer agents | Yes | None |
| author | Agent | Author agent | Yes | None |
| review_rounds | int | Number of review rounds | No | 2 |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes peer review process |

### Example

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import PeerReviewProcess

# Create agents
author = Agent(name="Author")
reviewer1 = Agent(name="Reviewer1")
reviewer2 = Agent(name="Reviewer2")

# Initialize peer review
review = PeerReviewProcess(
    reviewers=[reviewer1, reviewer2],
    author=author,
    review_rounds=2
)

# Run review process
result = review.run("New Machine Learning Algorithm for Natural Language Processing")
```

## MediationSession

### Description
Simulates a mediation session to resolve conflicts between parties. Facilitated conflict resolution with structured sessions.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| parties | List[Agent] | Disputing parties | Yes | None |
| mediator | Agent | Mediator agent | Yes | None |
| max_sessions | int | Number of mediation sessions | No | 3 |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes mediation session |

### Example

Full example: [Merger Mediation Session](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/merger_mediation_session.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import MediationSession

# Create agents
mediator = Agent(name="Mediator")
party1 = Agent(name="Party1")
party2 = Agent(name="Party2")

# Initialize mediation
mediation = MediationSession(
    parties=[party1, party2],
    mediator=mediator,
    max_sessions=3
)

# Run mediation
result = mediation.run("Resolve intellectual property dispute")
```

## BrainstormingSession

### Description
Simulates a brainstorming session where participants build on each other's ideas. Creative idea generation with collaborative building.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| participants | List[Agent] | Brainstorming participants | Yes | None |
| facilitator | Agent | Session facilitator | Yes | None |
| idea_rounds | int | Number of idea generation rounds | No | 3 |
| build_on_ideas | bool | Whether to build on previous ideas | No | True |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes brainstorming session |

### Example

Full example: [Pharma Research Brainstorm](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/pharma_research_brainstorm.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import BrainstormingSession

# Create agents
facilitator = Agent(name="Facilitator")
participant1 = Agent(name="Creative1")
participant2 = Agent(name="Creative2")
participant3 = Agent(name="Creative3")

# Initialize brainstorming
brainstorm = BrainstormingSession(
    participants=[participant1, participant2, participant3],
    facilitator=facilitator,
    idea_rounds=3,
    build_on_ideas=True
)

# Run brainstorming
result = brainstorm.run("Innovative solutions for urban transportation")
```

## TrialSimulation

### Description
Simulates a legal trial with structured phases and roles. Complete legal proceeding simulation with all participants.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| prosecution | Agent | Prosecution attorney | Yes | None |
| defense | Agent | Defense attorney | Yes | None |
| judge | Agent | Trial judge | Yes | None |
| witnesses | List[Agent] | Trial witnesses | No | None |
| phases | List[str] | Trial phases | No | Default phases |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes trial simulation |

### Example

Full example: [Medical Malpractice Trial](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/medical_malpractice_trial.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import TrialSimulation

# Create agents
judge = Agent(name="Judge")
prosecutor = Agent(name="Prosecutor")
defense = Agent(name="Defense")
witness1 = Agent(name="Witness1")
witness2 = Agent(name="Witness2")

# Initialize trial
trial = TrialSimulation(
    prosecution=prosecutor,
    defense=defense,
    judge=judge,
    witnesses=[witness1, witness2],
    phases=["opening", "testimony", "cross", "closing"]
)

# Run trial
result = trial.run("Patent infringement case")
```

## CouncilMeeting

### Description
Simulates a council meeting with structured discussion and decision-making. Governance process with voting and consensus building.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| council_members | List[Agent] | Council participants | Yes | None |
| chairperson | Agent | Meeting chairperson | Yes | None |
| voting_rounds | int | Number of voting rounds | No | 1 |
| require_consensus | bool | Whether consensus is required | No | False |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes council meeting |

### Example

Full example: [Investment Council Meeting](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/investment_council_meeting.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import CouncilMeeting

# Create agents
chairperson = Agent(name="Chair")
member1 = Agent(name="Member1")
member2 = Agent(name="Member2")
member3 = Agent(name="Member3")

# Initialize council meeting
council = CouncilMeeting(
    council_members=[member1, member2, member3],
    chairperson=chairperson,
    voting_rounds=2,
    require_consensus=True
)

# Run meeting
result = council.run("Vote on new environmental policy")
```

## MentorshipSession

### Description
Simulates a mentorship session with structured learning and feedback. Guided learning process with progress tracking.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| mentor | Agent | Mentor agent | Yes | None |
| mentee | Agent | Mentee agent | Yes | None |
| session_count | int | Number of sessions | No | 3 |
| include_feedback | bool | Whether to include feedback | No | True |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes mentorship session |

### Example

Full example: [Startup Mentorship Program](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/startup_mentorship_program.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import MentorshipSession

# Create agents
mentor = Agent(name="Mentor")
mentee = Agent(name="Mentee")

# Initialize mentorship
mentorship = MentorshipSession(
    mentor=mentor,
    mentee=mentee,
    session_count=3,
    include_feedback=True
)

# Run session
result = mentorship.run("Career development in AI research")
```

## NegotiationSession

### Description
Simulates a negotiation with multiple parties working toward agreement. Complex multi-party negotiation with concessions.

### Parameters

| Parameter | Type | Description | Required | Default |
|-----------|------|-------------|----------|---------|
| parties | List[Agent] | Negotiating parties | Yes | None |
| mediator | Agent | Negotiation mediator | Yes | None |
| negotiation_rounds | int | Number of rounds | No | 5 |
| include_concessions | bool | Whether to allow concessions | No | True |
| output_type | str | Format for conversation history | No | "str-all-except-first" |

### Run Method

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| run | task: str | list | Executes negotiation session |

### Example

Full example: [NVIDIA-AMD Executive Negotiation](https://github.com/kyegomez/swarms/blob/master/examples/multi_agent/orchestration_examples/nvidia_amd_executive_negotiation.py)

```python
from swarms.agents import Agent
from swarms.structs.multi_agent_debates import NegotiationSession

# Create agents
mediator = Agent(name="Mediator")
party1 = Agent(name="Company1")
party2 = Agent(name="Company2")

# Initialize negotiation
negotiation = NegotiationSession(
    parties=[party1, party2],
    mediator=mediator,
    negotiation_rounds=4,
    include_concessions=True
)

# Run negotiation
result = negotiation.run("Merger terms negotiation")
```

## Conclusion

The multi-agent orchestration methods in Swarms provide powerful frameworks for structuring complex interactions between AI agents. Key benefits include:

1. Structured Communication: Each method provides a clear framework for organizing multi-agent interactions
2. Role-Based Interactions: Agents can take on specific roles with defined responsibilities
3. Flexible Configuration: Customizable parameters for controlling interaction flow
4. Scalable Architecture: Support for various numbers of participants and interaction rounds
5. Comprehensive Coverage: Methods for different use cases from debates to negotiations
6. Professional Output: Consistent formatting and organization of conversation history
7. Easy Integration: Simple API for incorporating into larger applications 

--------------------------------------------------

# File: swarms/structs/overview.md

# Multi-Agent Architectures Overview

This page provides a comprehensive overview of all available multi-agent architectures in Swarms, their use cases, and functionality.

## Architecture Comparison

=== "Core Architectures"
    | Architecture | Use Case | Key Functionality | Documentation |
    |-------------|----------|-------------------|---------------|
    | MajorityVoting | Decision making through consensus | Combines multiple agent opinions and selects the most common answer | [Docs](majorityvoting.md) |
    | AgentRearrange | Optimizing agent order | Dynamically reorders agents based on task requirements | [Docs](agent_rearrange.md) |
    | RoundRobin | Equal task distribution | Cycles through agents in a fixed order | [Docs](round_robin_swarm.md) |
    | Mixture of Agents | Complex problem solving | Combines diverse expert agents for comprehensive analysis | [Docs](moa.md) |
    | GroupChat | Collaborative discussions | Simulates group discussions with multiple agents | [Docs](group_chat.md) |
    | AgentRegistry | Agent management | Central registry for managing and accessing agents | [Docs](agent_registry.md) |
    | SpreadSheetSwarm | Data processing | Collaborative data processing and analysis | [Docs](spreadsheet_swarm.md) |
    | ForestSwarm | Hierarchical decision making | Tree-like structure for complex decision processes | [Docs](forest_swarm.md) |
    | SwarmRouter | Task routing | Routes tasks to appropriate agents based on requirements | [Docs](swarm_router.md) |
    | TaskQueueSwarm | Task management | Manages and prioritizes tasks in a queue | [Docs](taskqueue_swarm.md) |
    | SwarmRearrange | Dynamic swarm optimization | Optimizes swarm configurations for specific tasks | [Docs](swarm_rearrange.md) |
    | MultiAgentRouter | Advanced task routing | Routes tasks to specialized agents based on capabilities | [Docs](multi_agent_router.md) |
    | MatrixSwarm | Parallel processing | Matrix-based organization for parallel task execution | [Docs](matrix_swarm.md) |
    | ModelRouter | Model selection | Routes tasks to appropriate AI models | [Docs](model_router.md) |
    | MALT | Multi-agent learning | Enables agents to learn from each other | [Docs](malt.md) |
    | Deep Research Swarm | Research automation | Conducts comprehensive research across multiple domains | [Docs](deep_research_swarm.md) |
    | Swarm Matcher | Agent matching | Matches tasks with appropriate agent combinations | [Docs](swarm_matcher.md) |

=== "Workflow Architectures"
    | Architecture | Use Case | Key Functionality | Documentation |
    |-------------|----------|-------------------|---------------|
    | ConcurrentWorkflow | Parallel task execution | Executes multiple tasks simultaneously | [Docs](concurrentworkflow.md) |
    | SequentialWorkflow | Step-by-step processing | Executes tasks in a specific sequence | [Docs](sequential_workflow.md) |
    | GraphWorkflow | Complex task dependencies | Manages tasks with complex dependencies | [Docs](graph_workflow.md) |

=== "Hierarchical Architectures"
    | Architecture | Use Case | Key Functionality | Documentation |
    |-------------|----------|-------------------|---------------|
    | HierarchicalSwarm | Hierarchical task orchestration | Director agent coordinates specialized worker agents | [Docs](hierarchical_swarm.md) |
    | Auto Agent Builder | Automated agent creation | Automatically creates and configures agents | [Docs](auto_agent_builder.md) |
    | Hybrid Hierarchical-Cluster Swarm | Complex organization | Combines hierarchical and cluster-based organization | [Docs](hhcs.md) |
    | Auto Swarm Builder | Automated swarm creation | Automatically creates and configures swarms | [Docs](auto_swarm_builder.md) |

## Communication Structure

!!! note "Communication Protocols"
    The [Conversation](conversation.md) documentation details the communication protocols and structures used between agents in these architectures.

## Choosing the Right Architecture

When selecting a multi-agent architecture, consider the following factors:

!!! tip "Task Complexity"
    Simple tasks may only need basic architectures like RoundRobin, while complex tasks might require Hierarchical or Graph-based approaches.

!!! tip "Parallelization Needs"
    If tasks can be executed in parallel, consider ConcurrentWorkflow or MatrixSwarm.

!!! tip "Decision Making Requirements"
    For consensus-based decisions, MajorityVoting is ideal.

!!! tip "Resource Optimization"
    If you need to optimize agent usage, consider SwarmRouter or TaskQueueSwarm.

!!! tip "Learning Requirements"
    If agents need to learn from each other, MALT is the appropriate choice.

!!! tip "Dynamic Adaptation"
    For tasks requiring dynamic adaptation, consider SwarmRearrange or Auto Swarm Builder.

For more detailed information about each architecture, please refer to their respective documentation pages.


--------------------------------------------------

# File: swarms/structs/round_robin_swarm.md

# RoundRobin: Round-Robin Task Execution in a Swarm

The `RoundRobinSwarm` class is designed to manage and execute tasks among multiple agents in a round-robin fashion. This approach ensures that each agent in a swarm receives an equal opportunity to execute tasks, which promotes fairness and efficiency in distributed systems. It is particularly useful in environments where collaborative, sequential task execution is needed among various agents.

## What is Round-Robin?

Round-robin is a scheduling technique commonly used in computing for managing processes in shared systems. It involves assigning a fixed time slot to each process and cycling through all processes in a circular order without prioritization. In the context of swarms of agents, this method ensures equitable distribution of tasks and resource usage among all agents.

## Application in Swarms

In swarms, `RoundRobinSwarm` utilizes the round-robin scheduling to manage tasks among agents like software components, autonomous robots, or virtual entities. This strategy is beneficial where tasks are interdependent or require sequential processing.

## Class Attributes

- `agents (List[Agent])`: List of agents participating in the swarm.
- `verbose (bool)`: Enables or disables detailed logging of swarm operations.
- `max_loops (int)`: Limits the number of times the swarm cycles through all agents.
- `index (int)`: Maintains the current position in the agent list to ensure round-robin execution.

## Methods

### `__init__`

Initializes the swarm with the provided list of agents, verbosity setting, and operational parameters.

**Parameters:**
| Parameter   | Type                | Description                                         |
|-------------|---------------------|-----------------------------------------------------|
| agents      | List[Agent], optional | List of agents in the swarm.                        |
| verbose     | bool                | Boolean flag for detailed logging.                  |
| max_loops   | int                 | Maximum number of execution cycles.                 |
| callback    | Callable, optional  | Function called after each loop.                    |

### `run`

Executes a specified task across all agents in a round-robin manner, cycling through each agent repeatedly for the number of specified loops.

**Conceptual Behavior:**

| Step | Description |
|------|-------------|
| 1    | Distribute the task sequentially among all agents starting from the current index. |
| 2    | Each agent processes the task and potentially modifies it or produces new output. |
| 3    | After an agent completes its part of the task, the index moves to the next agent. |
| 4    | This cycle continues until the specified maximum number of loops is completed. |
| 5    | Optionally, a callback function can be invoked after each loop to handle intermediate results or perform additional actions. |

## Examples

In this example, `RoundRobinSwarm` is used to distribute network requests evenly among a group of servers. This is common in scenarios where load balancing is crucial for maintaining system responsiveness and scalability.

```python
from swarms import Agent, RoundRobinSwarm

# Define sales agents
sales_agent1 = Agent(
    agent_name="Sales Agent 1 - Automation Specialist",
    system_prompt="You're Sales Agent 1, your purpose is to generate sales for a company by focusing on the benefits of automating accounting processes!",
    agent_description="Generate sales by focusing on the benefits of automation!",
    model_name="gpt-4.1",
    max_loops=1,
)

sales_agent2 = Agent(
    agent_name="Sales Agent 2 - Cost Saving Specialist",
    system_prompt="You're Sales Agent 2, your purpose is to generate sales for a company by emphasizing the cost savings of using swarms of agents!",
    agent_description="Generate sales by emphasizing cost savings!",
    model_name="gpt-4.1",
    max_loops=1,
)

sales_agent3 = Agent(
    agent_name="Sales Agent 3 - Efficiency Specialist",
    system_prompt="You're Sales Agent 3, your purpose is to generate sales for a company by highlighting the efficiency and accuracy of our swarms of agents in accounting processes!",
    agent_description="Generate sales by highlighting efficiency and accuracy!",
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the swarm with sales agents
sales_swarm = RoundRobinSwarm(agents=[sales_agent1, sales_agent2, sales_agent3], verbose=True)

# Define a sales task
task = "Generate a sales email for an accountant firm executive to sell swarms of agents to automate their accounting processes."

out = sales_swarm.run(task)
print(out)
```


## Conclusion

The RoundRobinSwarm class provides a robust and flexible framework for managing tasks among multiple agents in a fair and efficient manner. This class is especially useful in environments where tasks need to be distributed evenly among a group of agents, ensuring that all tasks are handled timely and effectively. Through the round-robin algorithm, each agent in the swarm is guaranteed an equal opportunity to contribute to the overall task, promoting efficiency and collaboration.


--------------------------------------------------

# File: swarms/structs/sequential_workflow.md

# SequentialWorkflow Documentation

**Overview:**
A Sequential Swarm architecture processes tasks in a linear sequence. Each agent completes its task before passing the result to the next agent in the chain. This architecture ensures orderly processing and is useful when tasks have dependencies. The system now includes **sequential awareness** features that allow agents to know about the agents ahead and behind them in the workflow, significantly enhancing coordination and context understanding. [Learn more here in the docs:](https://docs.swarms.world/en/latest/swarms/structs/agent_rearrange/)

**Use-Cases:**

- Workflows where each step depends on the previous one, such as assembly lines or sequential data processing.
- Scenarios requiring strict order of operations.
- **NEW**: Enhanced workflows where agents need context about their position in the sequence for better coordination.

```mermaid
graph TD
    A[First Agent] --> B[Second Agent]
    B --> C[Third Agent]
    C --> D[Fourth Agent]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    
    A -.->|"Awareness: None (first)"| A
    B -.->|"Awareness: Ahead: A, Behind: C"| B
    C -.->|"Awareness: Ahead: B, Behind: D"| C
    D -.->|"Awareness: Ahead: C, Behind: None (last)"| D
```

## **Sequential Awareness Feature**

The SequentialWorkflow now includes a powerful **sequential awareness** feature that automatically provides each agent with context about their position in the workflow:

### What Agents Know Automatically

- **Agent ahead**: The agent that completed their task before them
- **Agent behind**: The agent that will receive their output next
- **Workflow position**: Their step number and role in the sequence

### Benefits

1. **Better Coordination**: Agents can reference previous work and prepare output for the next step
2. **Context Understanding**: Each agent knows their role in the larger workflow
3. **Improved Quality**: Output is tailored for the next agent in the sequence
4. **Enhanced Logging**: Better tracking of agent interactions and workflow progress

## Attributes

| Attribute        | Type          | Description                                      |
|------------------|---------------|--------------------------------------------------|
| `agents`         | `List[Agent]` | The list of agents in the workflow.              |
| `flow`           | `str`         | A string representing the order of agents.       |
| `agent_rearrange`| `AgentRearrange` | Manages the dynamic execution of agents with sequential awareness. |
| `team_awareness` | `bool`        | **NEW**: Enables sequential awareness features. Defaults to `False`. |
| `time_enabled`   | `bool`        | **NEW**: Enables timestamps in conversation. Defaults to `False`. |
| `message_id_on`  | `bool`        | **NEW**: Enables message IDs in conversation. Defaults to `False`. |

## Methods

### `__init__(self, agents: List[Agent] = None, max_loops: int = 1, team_awareness: bool = False, time_enabled: bool = False, message_id_on: bool = False, *args, **kwargs)`

The constructor initializes the `SequentialWorkflow` object with enhanced sequential awareness capabilities.

- **Parameters:**
  - `agents` (`List[Agent]`, optional): The list of agents in the workflow. Defaults to `None`.
  - `max_loops` (`int`, optional): The maximum number of loops to execute the workflow. Defaults to `1`.
  - `team_awareness` (`bool`, optional): **NEW**: Enables sequential awareness features. Defaults to `False`.
  - `time_enabled` (`bool`, optional): **NEW**: Enables timestamps in conversation. Defaults to `False`.
  - `message_id_on` (`bool`, optional): **NEW**: Enables message IDs in conversation. Defaults to `False`.
  - `*args`: Variable length argument list.
  - `**kwargs`: Arbitrary keyword arguments.

### `run(self, task: str) -> str`

Runs the specified task through the agents in the dynamically constructed flow with enhanced sequential awareness.

- **Parameters:**
  - `task` (`str`): The task for the agents to execute.

- **Returns:**
  - `str`: The final result after processing through all agents.

### **NEW: Sequential Awareness Methods**

#### `get_agent_sequential_awareness(self, agent_name: str) -> str`

Gets the sequential awareness information for a specific agent, showing which agents come before and after in the sequence.

- **Parameters:**
  - `agent_name` (`str`): The name of the agent to get awareness for.

- **Returns:**
  - `str`: A string describing the agents ahead and behind in the sequence.

#### `get_sequential_flow_structure(self) -> str`

Gets the overall sequential flow structure information showing the complete workflow with relationships between agents.

- **Returns:**
  - `str`: A string describing the complete sequential flow structure.

## **Usage Example with Sequential Awareness:**

```python
from swarms import Agent, SequentialWorkflow

# Initialize agents for individual tasks
agent1 = Agent(
  agent_name="ICD-10 Code Analyzer",
  system_prompt="Analyze medical data and provide relevant ICD-10 codes.",
  model_name="gpt-4o",
  max_loops=1,
)
agent2 = Agent(
  agent_name="ICD-10 Code Summarizer",
  system_prompt="Summarize the findings and suggest ICD-10 codes.",
  model_name="gpt-4o",
  max_loops=1,
)
agent3 = Agent(
  agent_name="ICD-10 Code Validator",
  system_prompt="Validate and finalize the ICD-10 code recommendations.",
  model_name="gpt-4o",
  max_loops=1,
)

# Create the Sequential workflow with enhanced awareness
workflow = SequentialWorkflow(
  agents=[agent1, agent2, agent3], 
  max_loops=1, 
  verbose=False,
  team_awareness=True,    # Enable sequential awareness
  time_enabled=True,      # Enable timestamps
  message_id_on=True      # Enable message IDs
)

# Get workflow structure information
flow_structure = workflow.get_sequential_flow_structure()
print("Workflow Structure:")
print(flow_structure)

# Get awareness for specific agents
analyzer_awareness = workflow.get_agent_sequential_awareness("ICD-10 Code Analyzer")
summarizer_awareness = workflow.get_agent_sequential_awareness("ICD-10 Code Summarizer")
validator_awareness = workflow.get_agent_sequential_awareness("ICD-10 Code Validator")

print(f"\nAnalyzer Awareness: {analyzer_awareness}")
print(f"Summarizer Awareness: {summarizer_awareness}")
print(f"Validator Awareness: {validator_awareness}")

# Run the workflow
result = workflow.run(
  "Analyze the medical report and provide the appropriate ICD-10 codes."
)
print(f"\nFinal Result: {result}")
```

**Expected Output:**
```
Workflow Structure:
Sequential Flow Structure:
Step 1: ICD-10 Code Analyzer
Step 2: ICD-10 Code Summarizer (follows: ICD-10 Code Analyzer) (leads to: ICD-10 Code Validator)
Step 3: ICD-10 Code Validator (follows: ICD-10 Code Summarizer)

Analyzer Awareness: 
Summarizer Awareness: Sequential awareness: Agent ahead: ICD-10 Code Analyzer | Agent behind: ICD-10 Code Validator
Validator Awareness: Sequential awareness: Agent ahead: ICD-10 Code Summarizer
```

## **How Sequential Awareness Works**

### 1. **Automatic Context Injection**
When `team_awareness=True`, the system automatically adds awareness information to each agent's conversation context before they run:

- **First Agent**: No awareness info (starts the workflow)
- **Middle Agents**: Receive info about both the agent ahead and behind
- **Last Agent**: Receives info about the agent ahead only

### 2. **Enhanced Agent Prompts**
Each agent receives context like:
```
Sequential awareness: Agent ahead: ICD-10 Code Analyzer | Agent behind: ICD-10 Code Validator
```

### 3. **Improved Coordination**
Agents can now:
- Reference previous work more effectively
- Prepare output specifically for the next agent
- Understand their role in the larger workflow
- Provide better context for subsequent steps

## **Advanced Usage Examples**

### **Example 1: Research → Analysis → Report Workflow**
```python
# Create specialized agents
researcher = Agent(
    agent_name="Researcher",
    system_prompt="Conduct thorough research on the given topic."
)

analyzer = Agent(
    agent_name="Data Analyzer", 
    system_prompt="Analyze research data and identify key insights."
)

reporter = Agent(
    agent_name="Report Writer",
    system_prompt="Write comprehensive reports based on analysis."
)

# Create workflow with awareness
workflow = SequentialWorkflow(
    agents=[researcher, analyzer, reporter],
    team_awareness=True,
    time_enabled=True
)

# Run with enhanced coordination
result = workflow.run("Research and analyze the impact of AI on healthcare")
```

### **Example 2: Code Review Workflow**
```python
# Create code review agents
linter = Agent(
    agent_name="Code Linter",
    system_prompt="Check code for syntax errors and style violations."
)

reviewer = Agent(
    agent_name="Code Reviewer",
    system_prompt="Review code quality and suggest improvements."
)

tester = Agent(
    agent_name="Code Tester",
    system_prompt="Write and run tests for the reviewed code."
)

# Create workflow
workflow = SequentialWorkflow(
    agents=[linter, reviewer, tester],
    team_awareness=True
)

# Run code review process
result = workflow.run("Review and test the authentication module")
```

## **Notes:**

- **Enhanced Logging**: The workflow now logs sequential awareness information for better debugging and monitoring.
- **Automatic Context**: No manual configuration needed - awareness is automatically provided when `team_awareness=True`.
- **Backward Compatibility**: Existing workflows continue to work without changes.
- **Performance**: Sequential awareness adds minimal overhead while significantly improving coordination.

### Logging and Error Handling

The `run` method now includes enhanced logging to track the sequential awareness flow and captures detailed information about agent interactions:

```bash
2023-05-08 10:30:15.456 | INFO | SequentialWorkflow:run:45 - Starting sequential workflow execution
2023-05-08 10:30:15.457 | INFO | SequentialWorkflow:run:52 - Added sequential awareness for ICD-10 Code Summarizer: Sequential awareness: Agent ahead: ICD-10 Code Analyzer | Agent behind: ICD-10 Code Validator
2023-05-08 10:30:15.458 | INFO | SequentialWorkflow:run:52 - Added sequential awareness for ICD-10 Code Validator: Sequential awareness: Agent ahead: ICD-10 Code Summarizer
```

## Additional Tips

- **Enable Team Awareness**: Set `team_awareness=True` to unlock the full potential of sequential coordination.
- **Use Descriptive Agent Names**: Clear agent names make the awareness information more useful.
- **Monitor Logs**: Enhanced logging provides insights into how agents are coordinating.
- **Iterative Improvement**: Use the awareness features to refine agent prompts and improve workflow quality.

## **Benefits of Sequential Awareness**

1. **Improved Quality**: Agents produce better output when they understand their context
2. **Better Coordination**: Reduced redundancy and improved handoffs between agents
3. **Enhanced Debugging**: Clear visibility into agent interactions and workflow progress
4. **Scalable Workflows**: Easy to add new agents while maintaining coordination
5. **Professional Workflows**: Mimics real-world team collaboration patterns

The SequentialWorkflow with sequential awareness represents a significant advancement in multi-agent coordination, enabling more sophisticated and professional workflows that closely mirror human team collaboration patterns.


--------------------------------------------------

# File: swarms/structs/spreadsheet_swarm.md

# SpreadSheetSwarm Documentation



## Class Definition

```python
class SpreadSheetSwarm:
```

## Full Path

```python
from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm
```

### Attributes

The `SpreadSheetSwarm` class contains several attributes that define its behavior and configuration. These attributes are initialized in the constructor (`__init__` method) and are used throughout the class to manage the swarm's operations.

| Attribute          | Type                              | Description                                                                                 |
|--------------------|-----------------------------------|---------------------------------------------------------------------------------------------|
| `name`             | `str`                             | The name of the swarm.                                                                      |
| `description`      | `str`                             | A description of the swarm's purpose.                                                       |
| `agents`           | `Union[Agent, List[Agent]]`       | The agents participating in the swarm. Can be a single agent or a list of agents.           |
| `autosave_on`      | `bool`                            | Flag indicating whether autosave is enabled.                                                |
| `save_file_path`   | `str`                             | The file path where the swarm data will be saved.                                           |
| `task_queue`       | `queue.Queue`                     | The queue that stores tasks to be processed by the agents.                                  |
| `lock`             | `threading.Lock`                  | A lock used for thread synchronization to prevent race conditions.                          |
| `metadata`         | `SwarmRunMetadata`                | Metadata for the swarm run, including start time, end time, tasks completed, and outputs.   |
| `run_all_agents`   | `bool`                            | Flag indicating whether to run all agents or just one.                                      |
| `max_loops`     | `int`                             | The number of times to repeat the task.                                                     |
| `workspace_dir`    | `str`                             | The directory where the workspace is located, retrieved from environment variables.         |

### Parameters

- **`name`** (`str`, optional): The name of the swarm. Default is `"Spreadsheet-Swarm"`.
- **`description`** (`str`, optional): A brief description of the swarm. Default is `"A swarm that processes tasks from a queue using multiple agents on different threads."`.
- **`agents`** (`Union[Agent, List[Agent]]`, optional): The agents participating in the swarm. Default is an empty list.
- **`autosave_on`** (`bool`, optional): A flag to indicate if autosave is enabled. Default is `True`.
- **`save_file_path`** (`str`, optional): The file path where swarm data will be saved. Default is `"spreedsheet_swarm.csv"`.
- **`run_all_agents`** (`bool`, optional): Flag to determine if all agents should run. Default is `True`.
- **`max_loops`** (`int`, optional): The number of times to repeat the task. Default is `1`.
- **`workspace_dir`** (`str`, optional): The directory where the workspace is located. Default is retrieved from environment variable `WORKSPACE_DIR`.

### Constructor (`__init__`)

The constructor initializes the `SpreadSheetSwarm` with the provided parameters. It sets up the task queue, locks for thread synchronization, and initializes the metadata.

---

## Methods

### `reliability_check`

```python
def reliability_check(self):
```

#### Description

The `reliability_check` method performs a series of checks to ensure that the swarm is properly configured before it begins processing tasks. It verifies that there are agents available and that a valid file path is provided for saving the swarm's data. If any of these checks fail, an exception is raised.

#### Raises

- **`ValueError`**: Raised if no agents are provided or if no save file path is specified.

#### Example

```python
swarm = SpreadSheetSwarm(agents=[agent1, agent2])
swarm.reliability_check()
```

---

### `run`

```python
def run(self, task: str, *args, **kwargs):
```

#### Description

The `run` method starts the task processing using the swarm. Depending on the configuration, it can either run all agents or a specific subset of them. The method tracks the start and end times of the task, executes the task multiple times if specified, and logs the results.

#### Parameters

- **`task`** (`str`): The task to be executed by the swarm.
- **`*args`**: Additional positional arguments to pass to the agents.
- **`**kwargs`**: Additional keyword arguments to pass to the agents.

#### Example

```python
swarm = SpreadSheetSwarm(agents=[agent1, agent2])
swarm.run("Process Data")
```

---

### `export_to_json`

```python
def export_to_json(self):
```

#### Description

The `export_to_json` method generates a JSON representation of the swarm's metadata. This can be useful for exporting the results to an external system or for logging purposes.

#### Returns

- **`str`**: The JSON representation of the swarm's metadata.

#### Example

```python
json_data = swarm.export_to_json()
print(json_data)
```

---

### `data_to_json_file`

```python
def data_to_json_file(self):
```

#### Description

The `data_to_json_file` method saves the swarm's metadata as a JSON file in the specified workspace directory. The file name is generated using the swarm's name and run ID.

#### Example

```python
swarm.data_to_json_file()
```

---

### `_track_output`

```python
def _track_output(self, agent: Agent, task: str, result: str):
```

#### Description

The `_track_output` method is used internally to record the results of tasks executed by the agents. It updates the metadata with the completed tasks and their results.

#### Parameters

- **`agent`** (`Agent`): The agent that executed the task.
- **`task`** (`str`): The task that was executed.
- **`result`** (`str`): The result of the task execution.

#### Example

```python
swarm._track_output(agent1, "Process Data", "Success")
```

---

### `_save_to_csv`

```python
def _save_to_csv(self):
```

#### Description

The `_save_to_csv` method saves the swarm's metadata to a CSV file. It logs each task and its result before writing them to the file. The file is saved in the location specified by `save_file_path`.

#### Example

```python
swarm._save_to_csv()
```

---

## Usage Examples

### Example 1: Basic Swarm Initialization

```python
import os

from swarms import Agent, SpreadSheetSwarm
from swarms.prompts.finance_agent_sys_prompt import (
    FINANCIAL_AGENT_SYS_PROMPT,
)


# Initialize your agents (assuming the Agent class and model are already defined)
agents = [
    Agent(
        agent_name=f"Financial-Analysis-Agent-spreesheet-swarm:{i}",
        system_prompt=FINANCIAL_AGENT_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="finance_agent.json",
        user_name="swarms_corp",
        retry_attempts=1,
    )
    for i in range(10)
]

# Create a Swarm with the list of agents
swarm = SpreadSheetSwarm(
    name="Finance-Spreadsheet-Swarm",
    description="A swarm that processes tasks from a queue using multiple agents on different threads.",
    agents=agents,
    autosave_on=True,
    save_file_path="financial_spreed_sheet_swarm_demo.csv",
    run_all_agents=False,
    max_loops=1,
)

# Run the swarm
swarm.run(
    task="Analyze the states with the least taxes for LLCs. Provide an overview of all tax rates and add them with a comprehensive analysis"
)

```

### Example 2: QR Code Generator

```python
import os
from swarms import Agent, SpreadSheetSwarm

# Define custom system prompts for QR code generation
QR_CODE_AGENT_1_SYS_PROMPT = """
You are a Python coding expert. Your task is to write a Python script to generate a QR code for the link: https://lu.ma/jjc1b2bo. The code should save the QR code as an image file.
"""

QR_CODE_AGENT_2_SYS_PROMPT = """
You are a Python coding expert. Your task is to write a Python script to generate a QR code for the link: https://github.com/The-Swarm-Corporation/Cookbook. The code should save the QR code as an image file.
"""


# Initialize your agents for QR code generation
agents = [
    Agent(
        agent_name="QR-Code-Generator-Agent-Luma",
        system_prompt=QR_CODE_AGENT_1_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="qr_code_agent_luma.json",
        user_name="swarms_corp",
        retry_attempts=1,
    ),
    Agent(
        agent_name="QR-Code-Generator-Agent-Cookbook",
        system_prompt=QR_CODE_AGENT_2_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="qr_code_agent_cookbook.json",
        user_name="swarms_corp",
        retry_attempts=1,
    ),
]

# Create a Swarm with the list of agents
swarm = SpreadSheetSwarm(
    name="QR-Code-Generation-Swarm",
    description="A swarm that generates Python scripts to create QR codes for specific links.",
    agents=agents,
    autosave_on=True,
    save_file_path="qr_code_generation_results.csv",
    run_all_agents=False,
    max_loops=1,
)

# Run the swarm
swarm.run(
    task="Generate Python scripts to create QR codes for the provided links and save them as image files."
)
```


## Example 3: Social Media Marketing

```python

import os
from swarms import Agent, SpreadSheetSwarm

# Define custom system prompts for each social media platform
TWITTER_AGENT_SYS_PROMPT = """
You are a Twitter marketing expert. Your task is to create engaging, concise tweets and analyze trends to maximize engagement. Consider hashtags, timing, and content relevance.
"""

INSTAGRAM_AGENT_SYS_PROMPT = """
You are an Instagram marketing expert. Your task is to create visually appealing and engaging content, including captions and hashtags, tailored to a specific audience.
"""

FACEBOOK_AGENT_SYS_PROMPT = """
You are a Facebook marketing expert. Your task is to craft posts that are optimized for engagement and reach on Facebook, including using images, links, and targeted messaging.
"""

EMAIL_AGENT_SYS_PROMPT = """
You are an Email marketing expert. Your task is to write compelling email campaigns that drive conversions, focusing on subject lines, personalization, and call-to-action strategies.
"""

# Example usage:
api_key = os.getenv("OPENAI_API_KEY")

# Model
model = OpenAIChat(
    openai_api_key=api_key, model_name="gpt-4o-mini", temperature=0.1
)

# Initialize your agents for different social media platforms
agents = [
    Agent(
        agent_name="Twitter-Marketing-Agent",
        system_prompt=TWITTER_AGENT_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="twitter_agent.json",
        user_name="swarms_corp",
        retry_attempts=1,
    ),
    Agent(
        agent_name="Instagram-Marketing-Agent",
        system_prompt=INSTAGRAM_AGENT_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="instagram_agent.json",
        user_name="swarms_corp",
        retry_attempts=1,
    ),
    Agent(
        agent_name="Facebook-Marketing-Agent",
        system_prompt=FACEBOOK_AGENT_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="facebook_agent.json",
        user_name="swarms_corp",
        retry_attempts=1,
    ),
    Agent(
        agent_name="Email-Marketing-Agent",
        system_prompt=EMAIL_AGENT_SYS_PROMPT,
        model_name="gpt-4.1",
        max_loops=1,
        dynamic_temperature_enabled=True,
        saved_state_path="email_agent.json",
        user_name="swarms_corp",
        retry_attempts=1,
    ),
]

# Create a Swarm with the list of agents
swarm = SpreadSheetSwarm(
    name="Social-Media-Marketing-Swarm",
    description="A swarm that processes social media marketing tasks using multiple agents on different threads.",
    agents=agents,
    autosave_on=True,
    save_file_path="social_media_marketing_spreadsheet.csv",
    run_all_agents=False,
    max_loops=2,
)

# Run the swarm
swarm.run(
    task="Create posts to promote hack nights in miami beach for developers, engineers, and tech enthusiasts. Include relevant hashtags, images, and engaging captions."
)
```

---

## Additional Information and Tips

| Tip/Feature            | Description                                                                                                                                                                                                                 |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Thread Synchronization** | When working with multiple agents in a concurrent environment, it's crucial to ensure that access to shared resources is properly synchronized using locks to avoid race conditions.                                      |
| **Autosave Feature**       | If you enable the `autosave_on` flag, ensure that the file path provided is correct and writable. This feature is handy for long-running tasks where you want to periodically save the state.                            |
| **Error Handling**         | Implementing proper error handling within your agents can prevent the swarm from crashing during execution. Consider catching exceptions in the `run` method and logging errors appropriately.                            |
| **Custom Agents**          | You can extend the `Agent` class to create custom agents that perform specific tasks tailored to your application's needs.                                                                                               |

---


--------------------------------------------------

# File: swarms/structs/swarm_matcher.md

# SwarmMatcher

SwarmMatcher is a tool for automatically matching tasks to the most appropriate swarm type based on their semantic similarity.

## Overview

The SwarmMatcher utilizes transformer-based embeddings to determine the best swarm architecture for a given task. By analyzing the semantic meaning of task descriptions and comparing them to known swarm types, it can intelligently select the optimal swarm configuration for any task.

## Workflow

```mermaid
flowchart TD
    A[Task Description] --> B[Generate Task Embedding]
    C[Swarm Type Descriptions] --> D[Generate Swarm Type Embeddings]
    B --> E[Calculate Similarity Scores]
    D --> E
    E --> F[Select Best Matching Swarm Type]
    F --> G[Return Selected Swarm Type]
    
    subgraph Initialization
        H[Define Swarm Types] --> I[Load Transformer Model]
        I --> J[Pre-compute Swarm Type Embeddings]
    end
    
    subgraph Matching Process
        A --> B --> E --> F --> G
    end
```

## Installation

SwarmMatcher is included in the Swarms package. To use it, simply import it from the library:

```python
from swarms.structs.swarm_matcher import SwarmMatcher, SwarmMatcherConfig, SwarmType
```

## Basic Usage

```python
from swarms.structs.swarm_matcher import swarm_matcher

# Use the simplified function to match a task to a swarm type
swarm_type = swarm_matcher("Analyze this dataset and create visualizations")
print(f"Selected swarm type: {swarm_type}")
```

## Advanced Usage

For more control over the matching process, you can create and configure your own SwarmMatcher instance:

```python
from swarms.structs.swarm_matcher import SwarmMatcher, SwarmMatcherConfig, SwarmType, initialize_swarm_types

# Create a configuration
config = SwarmMatcherConfig(
    model_name="sentence-transformers/all-MiniLM-L6-v2",
    embedding_dim=512
)

# Initialize the matcher
matcher = SwarmMatcher(config)

# Add default swarm types
initialize_swarm_types(matcher)

# Add a custom swarm type
custom_swarm = SwarmType(
    name="CustomSwarm",
    description="A specialized swarm for handling specific domain tasks with expert knowledge."
)
matcher.add_swarm_type(custom_swarm)

# Find the best match for a task
best_match, score = matcher.find_best_match("Process natural language and extract key insights")
print(f"Best match: {best_match}, Score: {score}")

# Auto-select a swarm type
selected_swarm = matcher.auto_select_swarm("Create data visualizations from this CSV file")
print(f"Selected swarm: {selected_swarm}")
```

## Available Swarm Types

SwarmMatcher comes with several pre-defined swarm types:

| Swarm Type | Description |
| ---------- | ----------- |
| AgentRearrange | Optimize agent order and rearrange flow for multi-step tasks, ensuring efficient task allocation and minimizing bottlenecks. |
| MixtureOfAgents | Combine diverse expert agents for comprehensive analysis, fostering a collaborative approach to problem-solving and leveraging individual strengths. |
| SpreadSheetSwarm | Collaborative data processing and analysis in a spreadsheet-like environment, facilitating real-time data sharing and visualization. |
| SequentialWorkflow | Execute tasks in a step-by-step, sequential process workflow, ensuring a logical and methodical approach to task execution. |
| ConcurrentWorkflow | Process multiple tasks or data sources concurrently in parallel, maximizing productivity and reducing processing time. |

## API Reference

### SwarmType

A class representing a type of swarm with its name and description.


| Parameter | Type | Description |
| --------- | ---- | ----------- |
| name | str | The name of the swarm type |
| description | str | A detailed description of the swarm type's capabilities and ideal use cases |
| embedding | Optional[List[float]] | The generated embedding vector for this swarm type (auto-populated) |

### SwarmMatcherConfig

Configuration settings for the SwarmMatcher.


| Parameter | Type | Default | Description |
| --------- | ---- | ------- | ----------- |
| model_name | str | "sentence-transformers/all-MiniLM-L6-v2" | The transformer model to use for embeddings |
| embedding_dim | int | 512 | The dimension of the embedding vectors |

### SwarmMatcher

The main class for matching tasks to swarm types.


#### Methods

##### `__init__(config: SwarmMatcherConfig)`

Initializes the SwarmMatcher with a configuration.

##### `get_embedding(text: str) -> np.ndarray`

Generates an embedding vector for a given text using the configured model.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| text | str | The text to embed |
| Returns | np.ndarray | The embedding vector |

##### `add_swarm_type(swarm_type: SwarmType)`

Adds a swarm type to the matcher, generating an embedding for its description.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| swarm_type | SwarmType | The swarm type to add |

##### `find_best_match(task: str) -> Tuple[str, float]`

Finds the best matching swarm type for a given task.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| task | str | The task description |
| Returns | Tuple[str, float] | The name of the best matching swarm type and the similarity score |

##### `auto_select_swarm(task: str) -> str`

Automatically selects the best swarm type for a given task.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| task | str | The task description |
| Returns | str | The name of the selected swarm type |

##### `run_multiple(tasks: List[str]) -> List[str]`

Matches multiple tasks to swarm types in batch.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| tasks | List[str] | A list of task descriptions |
| Returns | List[str] | A list of selected swarm type names |

##### `save_swarm_types(filename: str)`

Saves the registered swarm types to a JSON file.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| filename | str | Path where the swarm types will be saved |

##### `load_swarm_types(filename: str)`

Loads swarm types from a JSON file.

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| filename | str | Path to the JSON file containing swarm types |

## Examples

### Simple Matching

```python
from swarms.structs.swarm_matcher import swarm_matcher

# Match tasks to swarm types
tasks = [
    "Analyze this dataset and create visualizations",
    "Coordinate multiple agents to tackle different aspects of a problem",
    "Process these 10 PDF files in sequence",
    "Handle these data processing tasks in parallel"
]

for task in tasks:
    swarm_type = swarm_matcher(task)
    print(f"Task: {task}")
    print(f"Selected swarm: {swarm_type}\n")
```

### Custom Swarm Types

```python
from swarms.structs.swarm_matcher import SwarmMatcher, SwarmMatcherConfig, SwarmType

# Create configuration and matcher
config = SwarmMatcherConfig()
matcher = SwarmMatcher(config)

# Define custom swarm types
swarm_types = [
    SwarmType(
        name="DataAnalysisSwarm",
        description="Specialized in processing and analyzing large datasets, performing statistical analysis, and extracting insights from complex data."
    ),
    SwarmType(
        name="CreativeWritingSwarm",
        description="Optimized for creative content generation, storytelling, and producing engaging written material with consistent style and tone."
    ),
    SwarmType(
        name="ResearchSwarm",
        description="Focused on deep research tasks, synthesizing information from multiple sources, and producing comprehensive reports on complex topics."
    )
]

# Add swarm types
for swarm_type in swarm_types:
    matcher.add_swarm_type(swarm_type)

# Save the swarm types for future use
matcher.save_swarm_types("custom_swarm_types.json")

# Use the matcher
task = "Research quantum computing advances in the last 5 years"
best_match = matcher.auto_select_swarm(task)
print(f"Selected swarm type: {best_match}")
```

## How It Works

SwarmMatcher uses a transformer-based model to generate embeddings (vector representations) of both the task descriptions and the swarm type descriptions. It then calculates the similarity between these embeddings to determine which swarm type is most semantically similar to the given task.

```mermaid
sequenceDiagram
    participant User
    participant SwarmMatcher
    participant TransformerModel
    
    User->>SwarmMatcher: task = "Analyze this dataset"
    Note over SwarmMatcher: Initialization already complete
    
    SwarmMatcher->>TransformerModel: get_embedding(task)
    TransformerModel-->>SwarmMatcher: task_embedding
    
    loop For each swarm type
        SwarmMatcher->>SwarmMatcher: Calculate similarity score
        Note over SwarmMatcher: score = dot_product(task_embedding, swarm_type.embedding)
    end
    
    SwarmMatcher->>SwarmMatcher: Find best score
    SwarmMatcher-->>User: "SpreadSheetSwarm"
```

The matching process follows these steps:

1. The task description is converted to an embedding vector
2. Each swarm type's description is converted to an embedding vector
3. The similarity between the task embedding and each swarm type embedding is calculated
4. The swarm type with the highest similarity score is selected

This approach ensures that the matcher can understand the semantic meaning of tasks, not just keyword matching, resulting in more accurate swarm type selection.


--------------------------------------------------

# File: swarms/structs/swarm_network.md

# SwarmNetwork [WIP]

The `SwarmNetwork` class is a powerful tool for managing a pool of agents, orchestrating task distribution, and scaling resources based on workload. It is designed to handle tasks efficiently by dynamically adjusting the number of agents according to the current demand. This class also provides an optional API for interacting with the agent pool, making it accessible for integration with other systems.

### Key Features
- **Agent Pool Management**: Dynamically manage a pool of agents.
- **Task Queue Management**: Handle tasks through a queue system.
- **Agent Health Monitoring**: Monitor the health of agents.
- **Agent Pool Scaling**: Scale the agent pool up or down based on workload.
- **API**: Interact with the agent pool and task queue through a simple API.
- **Agent Deployment Options**: Run agents on threads, processes, containers, machines, or clusters.

### Parameters

| Parameter       | Type               | Default Value | Description                                                                 |
|-----------------|--------------------|---------------|-----------------------------------------------------------------------------|
| name            | str                | None          | The name of the swarm network.                                              |
| description     | str                | None          | A description of the swarm network.                                         |
| agents          | List[Agent]        | None          | A list of agents in the pool.                                               |
| idle_threshold  | float              | 0.2           | The idle threshold for the agents.                                          |
| busy_threshold  | float              | 0.7           | The busy threshold for the agents.                                          |
| api_enabled     | Optional[bool]     | False         | A flag to enable/disable the API.                                           |
| logging_enabled | Optional[bool]     | False         | A flag to enable/disable logging.                                           |
| api_on          | Optional[bool]     | False         | A flag to enable/disable the FastAPI instance.                              |
| host            | str                | "0.0.0.0"     | The host address for the FastAPI instance.                                  |
| port            | int                | 8000          | The port number for the FastAPI instance.                                   |
| swarm_callable  | Optional[callable] | None          | A callable to be executed by the swarm network.                             |
| *args           | tuple              |               | Additional positional arguments.                                            |
| **kwargs        | dict               |               | Additional keyword arguments.                                               |

### Attributes

| Attribute        | Type               | Description                                                    |
|------------------|--------------------|----------------------------------------------------------------|
| task_queue       | queue.Queue        | A queue for storing tasks.                                     |
| idle_threshold   | float              | The idle threshold for the agents.                             |
| busy_threshold   | float              | The busy threshold for the agents.                             |
| agents           | List[Agent]        | A list of agents in the pool.                                  |
| api_enabled      | bool               | A flag to enable/disable the API.                              |
| logging_enabled  | bool               | A flag to enable/disable logging.                              |
| host             | str                | The host address for the FastAPI instance.                     |
| port             | int                | The port number for the FastAPI instance.                      |
| swarm_callable   | Optional[callable] | A callable to be executed by the swarm network.                |
| agent_dict       | dict               | A dictionary of agents for easy access.                        |
| lock             | threading.Lock     | A lock for synchronizing access to shared resources.           |

## Methods

#### Description
Initializes a new instance of the `SwarmNetwork` class.

#### Parameters
- `name` (str): The name of the swarm network.
- `description` (str): A description of the swarm network.
- `agents` (List[Agent]): A list of agents in the pool.
- `idle_threshold` (float): The idle threshold for the agents.
- `busy_threshold` (float): The busy threshold for the agents.
- `api_enabled` (Optional[bool]): A flag to enable/disable the API.
- `logging_enabled` (Optional[bool]): A flag to enable/disable logging.
- `api_on` (Optional[bool]): A flag to enable/disable the FastAPI instance.
- `host` (str): The host address for the FastAPI instance.
- `port` (int): The port number for the FastAPI instance.
- `swarm_callable` (Optional[callable]): A callable to be executed by the swarm network.
- `*args`: Additional positional arguments.
- `**kwargs`: Additional keyword arguments.

### `add_task`

```python
def add_task(self, task)
```

#### Description
Adds a task to the task queue.

#### Parameters
- `task` (_type_): The task to be added to the queue.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.add_task("task")
```

### `async_add_task`

```python
async def async_add_task(self, task)
```

#### Description
Adds a task to the task queue asynchronously.

#### Parameters
- `task` (_type_): The task to be added to the queue.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

agent = Agent()
swarm = SwarmNetwork(agents=[agent])
await swarm.async_add_task("task")
```

### `run_single_agent`

```python
def run_single_agent(self, agent_id, task: Optional[str], *args, **kwargs)
```

#### Description
Runs a task on a specific agent by ID.

#### Parameters
- `agent_id` (_type_): The ID of the agent.
- `task` (str, optional): The task to be executed by the agent.
- `*args`: Additional positional arguments.
- `**kwargs`: Additional keyword arguments.

#### Returns
- `_type_`: The output of the agent running the task.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[agent])
result = swarm.run_single_agent(agent.id, "task")
```

### `run_many_agents`

```python
def run_many_agents(self, task: Optional[str] = None, *args, **kwargs) -> List
```

#### Description
Runs a task on all agents in the pool.

#### Parameters
- `task` (str, optional): The task to be executed by the agents.
- `*args`: Additional positional arguments.
- `**kwargs`: Additional keyword arguments.

#### Returns
- `List`: The output of all agents running the task.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)


swarm = SwarmNetwork(agents=[agent1, agent2])
results = swarm.run_many_agents("task")
```

### `list_agents`

```python
def list_agents(self)
```

#### Description
Lists all agents in the pool.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[agent])
swarm.list_agents()
```

### `get_agent`

```python
def get_agent(self, agent_id)
```

#### Description
Gets an agent by ID.

#### Parameters
- `agent_id` (_type_): The ID of the agent to retrieve.

#### Returns
- `_type_`: The agent with the specified ID.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[agent])
retrieved_agent = swarm.get_agent(agent.id)
```

### `add_agent`

```python
def add_agent(self, agent: Agent)
```

#### Description
Adds an agent to the agent pool.

#### Parameters
- `agent` (_type_): The agent to be added to the pool.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[])
swarm.add_agent(agent)
```

### `remove_agent`

```python
def remove_agent(self, agent_id)
```

#### Description
Removes an agent from the agent pool.

#### Parameters
- `agent_id` (_type_): The ID of the agent to be removed.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[agent])
swarm.remove_agent(agent.id)
```

### `

async_remove_agent`

```python
async def async_remove_agent(self, agent_id)
```

#### Description
Removes an agent from the agent pool asynchronously.

#### Parameters
- `agent_id` (_type_): The ID of the agent to be removed.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[agent])
await swarm.async_remove_agent(agent.id)
```

### `scale_up`

```python
def scale_up(self, num_agents: int = 1)
```

#### Description
Scales up the agent pool by adding new agents.

#### Parameters
- `num_agents` (int, optional): The number of agents to add. Defaults to 1.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)

swarm = SwarmNetwork(agents=[agent])
swarm.scale_up(2)
```

### `scale_down`

```python
def scale_down(self, num_agents: int = 1)
```

#### Description
Scales down the agent pool by removing agents.

#### Parameters
- `num_agents` (int, optional): The number of agents to remove. Defaults to 1.

#### Example

```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork

# Initialize the agent
agent2 = Agent(
    agent_name="ROTH-IRA-AGENT",
    system_prompt=ESTATE_PLANNING_AGENT_SYS_PROMPT,
    llm=model,
    max_loops="auto",
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    interactive=True,
    # interactive=True, # Set to False to disable interactive mode
    saved_state_path="finance_agent.json",
    # tools=[Add your functions here# ],
    # stopping_token="Stop!",
    # interactive=True,
    # docs_folder="docs", # Enter your folder name
    # pdf_path="docs/finance_agent.pdf",
    # sop="Calculate the profit for a company.",
    # sop_list=["Calculate the profit for a company."],
    user_name="swarms_corp",
    # # docs=
    # # docs_folder="docs",
    retry_attempts=3,
    # context_length=1000,
    # tool_schema = dict
    context_length=200000,
    # agent_ops_on=True,
    # long_term_memory=ChromaDB(docs_folder="artifacts"),
)


swarm = SwarmNetwork(agents=[agent])
swarm.scale_down(1)
```

### `run`

#### Description
Runs the swarm network, starting the FastAPI application.

#### Example

```python

import os

from dotenv import load_dotenv

# Import the OpenAIChat model and the Agent struct
from swarms import Agent, OpenAIChat, SwarmNetwork

# Load the environment variables
load_dotenv()

# Get the API key from the environment
api_key = os.environ.get("OPENAI_API_KEY")

# Initialize the language model
llm = OpenAIChat(
    temperature=0.5,
    openai_api_key=api_key,
)

## Initialize the workflow
agent = Agent(llm=llm, max_loops=1, agent_name="Social Media Manager")
agent2 = Agent(llm=llm, max_loops=1, agent_name=" Product Manager")
agent3 = Agent(llm=llm, max_loops=1, agent_name="SEO Manager")


# Load the swarmnet with the agents
swarmnet = SwarmNetwork(
    agents=[agent, agent2, agent3],
)

# List the agents in the swarm network
out = swarmnet.list_agents()
print(out)

# Run the workflow on a task
out = swarmnet.run_single_agent(
    agent2.id, "Generate a 10,000 word blog on health and wellness."
)
print(out)


# Run all the agents in the swarm network on a task
out = swarmnet.run_many_agents("Generate a 10,000 word blog on health and wellness.")
print(out)
```

## Additional Information and Tips

- **Error Handling**: Make use of try-except blocks to handle potential errors when adding tasks, running tasks, and managing agents.
- **Logging**: Enable logging to track the activity and status of the swarm network.
- **API**: The provided API allows for easy interaction with the swarm network and can be extended as needed.
- **Asynchronous Operations**: Utilize the asynchronous methods for non-blocking operations, especially in a production environment.
- **Scaling**: Adjust the scaling thresholds (`idle_threshold` and `busy_threshold`) based on the specific needs and workload patterns.

## References and Resources

- [Python Queue Documentation](https://docs.python.org/3/library/queue.html)
- [Threading in Python](https://docs.python.org/3/library/threading.html)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Tenacity Documentation](https://tenacity.readthedocs.io/en/latest/)

By following this documentation, users can effectively manage and utilize the `SwarmNetwork` class to handle dynamic workloads and maintain an efficient pool of agents.


--------------------------------------------------

# File: swarms/structs/swarm_rearrange.md

# SwarmRearrange Documentation

SwarmRearrange is a class for orchestrating multiple swarms in a sequential or parallel flow pattern. It provides thread-safe operations for managing swarm execution, history tracking, and flow validation.

Full Path: `from swarms.structs.swarm_rearrange import SwarmRearrange`

## Constructor Arguments

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| id | str | UUID | Unique identifier for the swarm arrangement |
| name | str | "SwarmRearrange" | Name of the swarm arrangement |
| description | str | "A swarm of swarms..." | Description of the arrangement |
| swarms | List[Any] | [] | List of swarm objects to be managed |
| flow | str | None | Flow pattern for swarm execution |
| max_loops | int | 1 | Maximum number of execution loops |
| verbose | bool | True | Enable detailed logging |
| human_in_the_loop | bool | False | Enable human intervention |
| custom_human_in_the_loop | Callable | None | Custom function for human interaction |
| return_json | bool | False | Return results in JSON format |

## Methods

### add_swarm(swarm: Any)
Adds a single swarm to the arrangement.

### remove_swarm(swarm_name: str) 
Removes a swarm by name from the arrangement.

### add_swarms(swarms: List[Any])
Adds multiple swarms to the arrangement.

### validate_flow()
Validates the flow pattern syntax and swarm names.

### run(task: str = None, img: str = None, custom_tasks: Dict[str, str] = None)
Executes the swarm arrangement according to the flow pattern.

## Flow Pattern Syntax
The flow pattern uses arrow notation (`->`) to define execution order:

- Sequential: `"SwarmA -> SwarmB -> SwarmC"`

- Parallel: `"SwarmA, SwarmB -> SwarmC"`

- Human intervention: Use `"H"` in the flow

## Examples

### Basic Sequential Flow

```python
import os
from swarms import Agent, AgentRearrange, SwarmRearrange

# model = Anthropic(anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"))
company = "TGSC"


# Initialize the Managing Director agent
managing_director = Agent(
    agent_name="Managing-Director",
    system_prompt=f"""
    As the Managing Director at Blackstone, your role is to oversee the entire investment analysis process for potential acquisitions. 
    Your responsibilities include:
    1. Setting the overall strategy and direction for the analysis
    2. Coordinating the efforts of the various team members and ensuring a comprehensive evaluation
    3. Reviewing the findings and recommendations from each team member
    4. Making the final decision on whether to proceed with the acquisition
    
    For the current potential acquisition of {company}, direct the tasks for the team to thoroughly analyze all aspects of the company, including its financials, industry position, technology, market potential, and regulatory compliance. Provide guidance and feedback as needed to ensure a rigorous and unbiased assessment.
    """,
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the Vice President of Finance
vp_finance = Agent(
    agent_name="VP-Finance",
    system_prompt=f"""
    As the Vice President of Finance at Blackstone, your role is to lead the financial analysis of potential acquisitions. 
    For the current potential acquisition of {company}, your tasks include:
    1. Conducting a thorough review of {company}' financial statements, including income statements, balance sheets, and cash flow statements
    2. Analyzing key financial metrics such as revenue growth, profitability margins, liquidity ratios, and debt levels
    3. Assessing the company's historical financial performance and projecting future performance based on assumptions and market conditions
    4. Identifying any financial risks or red flags that could impact the acquisition decision
    5. Providing a detailed report on your findings and recommendations to the Managing Director

    Be sure to consider factors such as the sustainability of {company}' business model, the strength of its customer base, and its ability to generate consistent cash flows. Your analysis should be data-driven, objective, and aligned with Blackstone's investment criteria.
    """,
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the Industry Analyst
industry_analyst = Agent(
    agent_name="Industry-Analyst",
    system_prompt=f"""
    As the Industry Analyst at Blackstone, your role is to provide in-depth research and analysis on the industries and markets relevant to potential acquisitions.
    For the current potential acquisition of {company}, your tasks include:
    1. Conducting a comprehensive analysis of the industrial robotics and automation solutions industry, including market size, growth rates, key trends, and future prospects
    2. Identifying the major players in the industry and assessing their market share, competitive strengths and weaknesses, and strategic positioning 
    3. Evaluating {company}' competitive position within the industry, including its market share, differentiation, and competitive advantages
    4. Analyzing the key drivers and restraints for the industry, such as technological advancements, labor costs, regulatory changes, and economic conditions
    5. Identifying potential risks and opportunities for {company} based on the industry analysis, such as disruptive technologies, emerging markets, or shifts in customer preferences  
    
    Your analysis should provide a clear and objective assessment of the attractiveness and future potential of the industrial robotics industry, as well as {company}' positioning within it. Consider both short-term and long-term factors, and provide evidence-based insights to inform the investment decision.
    """,
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the Technology Expert
tech_expert = Agent(
    agent_name="Tech-Expert",
    system_prompt=f"""
    As the Technology Expert at Blackstone, your role is to assess the technological capabilities, competitive advantages, and potential risks of companies being considered for acquisition.
    For the current potential acquisition of {company}, your tasks include:
    1. Conducting a deep dive into {company}' proprietary technologies, including its robotics platforms, automation software, and AI capabilities 
    2. Assessing the uniqueness, scalability, and defensibility of {company}' technology stack and intellectual property
    3. Comparing {company}' technologies to those of its competitors and identifying any key differentiators or technology gaps
    4. Evaluating {company}' research and development capabilities, including its innovation pipeline, engineering talent, and R&D investments
    5. Identifying any potential technology risks or disruptive threats that could impact {company}' long-term competitiveness, such as emerging technologies or expiring patents
    
    Your analysis should provide a comprehensive assessment of {company}' technological strengths and weaknesses, as well as the sustainability of its competitive advantages. Consider both the current state of its technology and its future potential in light of industry trends and advancements.
    """,
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the Market Researcher
market_researcher = Agent(
    agent_name="Market-Researcher",
    system_prompt=f"""
    As the Market Researcher at Blackstone, your role is to analyze the target company's customer base, market share, and growth potential to assess the commercial viability and attractiveness of the potential acquisition.
    For the current potential acquisition of {company}, your tasks include:
    1. Analyzing {company}' current customer base, including customer segmentation, concentration risk, and retention rates
    2. Assessing {company}' market share within its target markets and identifying key factors driving its market position
    3. Conducting a detailed market sizing and segmentation analysis for the industrial robotics and automation markets, including identifying high-growth segments and emerging opportunities
    4. Evaluating the demand drivers and sales cycles for {company}' products and services, and identifying any potential risks or limitations to adoption
    5. Developing financial projections and estimates for {company}' revenue growth potential based on the market analysis and assumptions around market share and penetration
    
    Your analysis should provide a data-driven assessment of the market opportunity for {company} and the feasibility of achieving our investment return targets. Consider both bottom-up and top-down market perspectives, and identify any key sensitivities or assumptions in your projections.
    """,
    model_name="gpt-4.1",
    max_loops=1,

)

# Initialize the Regulatory Specialist
regulatory_specialist = Agent(
    agent_name="Regulatory-Specialist",
    system_prompt=f"""
    As the Regulatory Specialist at Blackstone, your role is to identify and assess any regulatory risks, compliance requirements, and potential legal liabilities associated with potential acquisitions.
    For the current potential acquisition of {company}, your tasks include:  
    1. Identifying all relevant regulatory bodies and laws that govern the operations of {company}, including industry-specific regulations, labor laws, and environmental regulations
    2. Reviewing {company}' current compliance policies, procedures, and track record to identify any potential gaps or areas of non-compliance
    3. Assessing the potential impact of any pending or proposed changes to relevant regulations that could affect {company}' business or create additional compliance burdens
    4. Evaluating the potential legal liabilities and risks associated with {company}' products, services, and operations, including product liability, intellectual property, and customer contracts
    5. Providing recommendations on any regulatory or legal due diligence steps that should be taken as part of the acquisition process, as well as any post-acquisition integration considerations
    
    Your analysis should provide a comprehensive assessment of the regulatory and legal landscape surrounding {company}, and identify any material risks or potential deal-breakers. Consider both the current state and future outlook, and provide practical recommendations to mitigate identified risks.
    """,
    model_name="gpt-4.1",
    max_loops=1,
)

# Create a list of agents
agents = [
    managing_director,
    vp_finance,
    industry_analyst,
    tech_expert,
    market_researcher,
    regulatory_specialist,
]

# Define multiple flow patterns
flows = [
    "Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Managing-Director -> VP-Finance",
    "Managing-Director -> VP-Finance -> Industry-Analyst -> Tech-Expert -> Market-Researcher -> Regulatory-Specialist",
    "Tech-Expert -> Market-Researcher -> Regulatory-Specialist -> Industry-Analyst -> Managing-Director -> VP-Finance",
]

# Create instances of AgentRearrange for each flow pattern
blackstone_acquisition_analysis = AgentRearrange(
    name="Blackstone-Acquisition-Analysis",
    description="A system for analyzing potential acquisitions",
    agents=agents,
    flow=flows[0],
)

blackstone_investment_strategy = AgentRearrange(
    name="Blackstone-Investment-Strategy",
    description="A system for evaluating investment opportunities",
    agents=agents,
    flow=flows[1],
)

blackstone_market_analysis = AgentRearrange(
    name="Blackstone-Market-Analysis",
    description="A system for analyzing market trends and opportunities",
    agents=agents,
    flow=flows[2],
)

swarm_arrange = SwarmRearrange(
    swarms=[
        blackstone_acquisition_analysis,
        blackstone_investment_strategy,
        blackstone_market_analysis,
    ],
    flow=f"{blackstone_acquisition_analysis.name} -> {blackstone_investment_strategy.name} -> {blackstone_market_analysis.name}",
)

print(
    swarm_arrange.run(
        "Analyze swarms, 150k revenue with 45m+ agents build, with 1.4m downloads since march 2024"
    )
)

```

### Human-in-the-Loop

```python
def custom_human_input(task):
    return input(f"Review {task} and provide feedback: ")

# Create arrangement with human intervention
arrangement = SwarmRearrange(
    name="HumanAugmented",
    swarms=[swarm1, swarm2],
    flow="SwarmA -> H -> SwarmB",
    human_in_the_loop=True,
    custom_human_in_the_loop=custom_human_input
)

# Execute with human intervention
result = arrangement.run("Initial task")
```


## Best Practices

| Best Practice           | Description                                                                                   |
|------------------------|-----------------------------------------------------------------------------------------------|
| **Flow Validation**    | Always validate flows before execution                                                        |
| **Error Handling**     | Implement try-catch blocks around `run()` calls                                               |
| **History Tracking**   | Use `track_history()` for monitoring swarm execution                                          |
| **Resource Management**| Set appropriate `max_loops` to prevent infinite execution                                     |
| **Logging**            | Enable verbose mode during development for detailed logging                                   |


--------------------------------------------------

# File: swarms/structs/swarm_router.md

# SwarmRouter Documentation

The `SwarmRouter` class is a flexible routing system designed to manage different types of swarms for task execution. It provides a unified interface to interact with various swarm types.

Full Path: `from swarms.structs.swarm_router`


## Initialization Parameters

Main class for routing tasks to different swarm types.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | str | Name of the SwarmRouter instance |
| `description` | str | Description of the SwarmRouter's purpose |
| `max_loops` | int | Maximum number of loops to perform |
| `agents` | List[Union[Agent, Callable]] | List of Agent objects or callable functions |
| `swarm_type` | SwarmType | Type of swarm to be used |
| `autosave` | bool | Flag to enable/disable autosave |
| `rearrange_flow` | str | The flow for the AgentRearrange swarm type |
| `return_json` | bool | Flag to enable/disable returning the result in JSON format |
| `auto_generate_prompts` | bool | Flag to enable/disable auto generation of prompts |
| `shared_memory_system` | Any | Shared memory system for agents |
| `rules` | str | Rules to inject into every agent |
| `documents` | List[str] | List of document file paths |
| `output_type` | OutputType | Output format type (e.g., "string", "dict", "list", "json", "yaml", "xml") |
| `no_cluster_ops` | bool | Flag to disable cluster operations |
| `speaker_fn` | callable | Speaker function for GroupChat swarm type |
| `load_agents_from_csv` | bool | Flag to enable/disable loading agents from CSV |
| `csv_file_path` | str | Path to the CSV file for loading agents |
| `return_entire_history` | bool | Flag to enable/disable returning the entire conversation history |
| `multi_agent_collab_prompt` | bool | Whether to enable multi-agent collaboration prompts |

#### Methods:

| Method | Parameters | Description |
| --- | --- | --- |
| `__init__` | `name: str = "swarm-router", description: str = "Routes your task to the desired swarm", max_loops: int = 1, agents: List[Union[Agent, Callable]] = [], swarm_type: SwarmType = "SequentialWorkflow", autosave: bool = False, rearrange_flow: str = None, return_json: bool = False, auto_generate_prompts: bool = False, shared_memory_system: Any = None, rules: str = None, documents: List[str] = [], output_type: OutputType = "dict", no_cluster_ops: bool = False, speaker_fn: callable = None, load_agents_from_csv: bool = False, csv_file_path: str = None, return_entire_history: bool = True, multi_agent_collab_prompt: bool = True` | Initialize the SwarmRouter |
| `setup` | None | Set up the SwarmRouter by activating APE and handling shared memory and rules |
| `activate_shared_memory` | None | Activate shared memory with all agents |
| `handle_rules` | None | Inject rules to every agent |
| `activate_ape` | None | Activate automatic prompt engineering for agents that support it |
| `reliability_check` | None | Perform reliability checks on the SwarmRouter configuration |
| `_create_swarm` | `task: str = None, *args, **kwargs` | Create and return the specified swarm type |
| `update_system_prompt_for_agent_in_swarm` | None | Update system prompts for all agents with collaboration prompts |
| `_log` | `level: str, message: str, task: str = "", metadata: Dict[str, Any] = None` | Create a log entry |
| `_run` | `task: str, img: Optional[str] = None, model_response: Optional[str] = None, *args, **kwargs` | Run the specified task on the selected swarm type |
| `run` | `task: str, img: Optional[str] = None, model_response: Optional[str] = None, *args, **kwargs` | Execute a task on the selected swarm type |
| `__call__` | `task: str, *args, **kwargs` | Make the SwarmRouter instance callable |
| `batch_run` | `tasks: List[str], *args, **kwargs` | Execute multiple tasks in sequence |
| `async_run` | `task: str, *args, **kwargs` | Execute a task asynchronously |
| `get_logs` | None | Retrieve all logged entries |
| `concurrent_run` | `task: str, *args, **kwargs` | Execute a task using concurrent execution |
| `concurrent_batch_run` | `tasks: List[str], *args, **kwargs` | Execute multiple tasks concurrently |


## Available Swarm Types

The `SwarmRouter` supports many various multi-agent architectures for various applications.

| Swarm Type | Description |
|------------|-------------|
| `AgentRearrange` | Optimizes agent arrangement for task execution |
| `MixtureOfAgents` | Combines multiple agent types for diverse tasks |
| `SpreadSheetSwarm` | Uses spreadsheet-like operations for task management |
| `SequentialWorkflow` | Executes tasks sequentially |
| `ConcurrentWorkflow` | Executes tasks in parallel |
| `GroupChat` | Facilitates communication among agents in a group chat format |
| `MultiAgentRouter` | Routes tasks between multiple agents |
| `AutoSwarmBuilder` | Automatically builds swarm structure |
| `HiearchicalSwarm` | Hierarchical organization of agents |
| `MajorityVoting` | Uses majority voting for decision making |
| `MALT` | Multi-Agent Language Tasks |
| `CouncilAsAJudge` | Council-based judgment system |
| `InteractiveGroupChat` | Interactive group chat with user participation |
| `auto` | Automatically selects best swarm type via embedding search |



## Basic Usage

```python
import os
from dotenv import load_dotenv
from swarms import Agent, SwarmRouter, SwarmType

# Define specialized system prompts for each agent
DATA_EXTRACTOR_PROMPT = """You are a highly specialized private equity agent focused on data extraction from various documents. Your expertise includes:
1. Extracting key financial metrics (revenue, EBITDA, growth rates, etc.) from financial statements and reports
2. Identifying and extracting important contract terms from legal documents
3. Pulling out relevant market data from industry reports and analyses
4. Extracting operational KPIs from management presentations and internal reports
5. Identifying and extracting key personnel information from organizational charts and bios
Provide accurate, structured data extracted from various document types to support investment analysis."""

SUMMARIZER_PROMPT = """You are an expert private equity agent specializing in summarizing complex documents. Your core competencies include:
1. Distilling lengthy financial reports into concise executive summaries
2. Summarizing legal documents, highlighting key terms and potential risks
3. Condensing industry reports to capture essential market trends and competitive dynamics
4. Summarizing management presentations to highlight key strategic initiatives and projections
5. Creating brief overviews of technical documents, emphasizing critical points for non-technical stakeholders
Deliver clear, concise summaries that capture the essence of various documents while highlighting information crucial for investment decisions."""

# Initialize specialized agents
data_extractor_agent = Agent(
    agent_name="Data-Extractor",
    system_prompt=DATA_EXTRACTOR_PROMPT,
    model_name="gpt-4.1",
    max_loops=1,
)

summarizer_agent = Agent(
    agent_name="Document-Summarizer",
    system_prompt=SUMMARIZER_PROMPT,
    model_name="gpt-4.1",
    max_loops=1,
)

# Initialize the SwarmRouter
router = SwarmRouter(
    name="pe-document-analysis-swarm",
    description="Analyze documents for private equity due diligence and investment decision-making",
    max_loops=1,
    agents=[data_extractor_agent, summarizer_agent],
    swarm_type="ConcurrentWorkflow",
)

# Example usage
if __name__ == "__main__":
    # Run a comprehensive private equity document analysis task
    result = router.run(
        "Where is the best place to find template term sheets for series A startups? Provide links and references"
    )
    print(result)
```

## Advanced Usage

### Changing Swarm Types

You can create multiple SwarmRouter instances with different swarm types:

```python
sequential_router = SwarmRouter(
    name="SequentialRouter",
    agents=[agent1, agent2],
    swarm_type="SequentialWorkflow"
)

concurrent_router = SwarmRouter(
    name="ConcurrentRouter",
    agents=[agent1, agent2],
    swarm_type="ConcurrentWorkflow"
)
```

### Automatic Swarm Type Selection

You can let the SwarmRouter automatically select the best swarm type for a given task:

```python
auto_router = SwarmRouter(
    name="AutoRouter",
    agents=[agent1, agent2],
    swarm_type="auto"
)

result = auto_router.run("Analyze and summarize the quarterly financial report")
```

### Injecting Rules to All Agents

To inject common rules into all agents:

```python
rules = """
1. Always provide sources for your information
2. Check your calculations twice
3. Explain your reasoning clearly
4. Highlight uncertainties and assumptions
"""

rules_router = SwarmRouter(
    name="RulesRouter",
    agents=[agent1, agent2],
    rules=rules,
    swarm_type="SequentialWorkflow"
)

result = rules_router.run("Analyze the investment opportunity")
```

## Use Cases

### AgentRearrange

Use Case: Optimizing agent order for complex multi-step tasks.

```python
rearrange_router = SwarmRouter(
    name="TaskOptimizer",
    description="Optimize agent order for multi-step tasks",
    max_loops=3,
    agents=[data_extractor, analyzer, summarizer],
    swarm_type="AgentRearrange",
    rearrange_flow=f"{data_extractor.name} -> {analyzer.name} -> {summarizer.name}"
)

result = rearrange_router.run("Analyze and summarize the quarterly financial report")
```

### MixtureOfAgents

Use Case: Combining diverse expert agents for comprehensive analysis.

```python
mixture_router = SwarmRouter(
    name="ExpertPanel",
    description="Combine insights from various expert agents",
    max_loops=1,
    agents=[financial_expert, market_analyst, tech_specialist, aggregator],
    swarm_type="MixtureOfAgents"
)

result = mixture_router.run("Evaluate the potential acquisition of TechStartup Inc.")
```

### SpreadSheetSwarm

Use Case: Collaborative data processing and analysis.

```python
spreadsheet_router = SwarmRouter(
    name="DataProcessor",
    description="Collaborative data processing and analysis",
    max_loops=1,
    agents=[data_cleaner, statistical_analyzer, visualizer],
    swarm_type="SpreadSheetSwarm"
)

result = spreadsheet_router.run("Process and visualize customer churn data")
```

### SequentialWorkflow

Use Case: Step-by-step document analysis and report generation.

```python
sequential_router = SwarmRouter(
    name="ReportGenerator",
    description="Generate comprehensive reports sequentially",
    max_loops=1,
    agents=[data_extractor, analyzer, writer, reviewer],
    swarm_type="SequentialWorkflow",
    return_entire_history=True
)

result = sequential_router.run("Create a due diligence report for Project Alpha")
```

### ConcurrentWorkflow

Use Case: Parallel processing of multiple data sources.

```python
concurrent_router = SwarmRouter(
    name="MultiSourceAnalyzer",
    description="Analyze multiple data sources concurrently",
    max_loops=1,
    agents=[financial_analyst, market_researcher, competitor_analyst],
    swarm_type="ConcurrentWorkflow",
    output_type="string"
)

result = concurrent_router.run("Conduct a comprehensive market analysis for Product X")
```

### GroupChat

Use Case: Simulating a group discussion with multiple agents.

```python
group_chat_router = SwarmRouter(
    name="GroupChat",
    description="Simulate a group discussion with multiple agents",
    max_loops=10,
    agents=[financial_analyst, market_researcher, competitor_analyst],
    swarm_type="GroupChat",
    speaker_fn=custom_speaker_function
)

result = group_chat_router.run("Discuss the pros and cons of expanding into the Asian market")
```

### MultiAgentRouter

Use Case: Routing tasks to the most appropriate agent.

```python
multi_agent_router = SwarmRouter(
    name="MultiAgentRouter",
    description="Route tasks to specialized agents",
    max_loops=1,
    agents=[financial_analyst, market_researcher, competitor_analyst],
    swarm_type="MultiAgentRouter",
    shared_memory_system=memory_system
)

result = multi_agent_router.run("Analyze the competitive landscape for our new product")
```

See [MultiAgentRouter Minimal Example](../examples/multi_agent_router_minimal.md) for a lightweight demonstration.

### HierarchicalSwarm

Use Case: Creating a hierarchical structure of agents with a director.

```python
hierarchical_router = SwarmRouter(
    name="HierarchicalSwarm",
    description="Hierarchical organization of agents with a director",
    max_loops=3,
    agents=[director, analyst1, analyst2, researcher],
    swarm_type="HiearchicalSwarm",
    return_all_history=True
)

result = hierarchical_router.run("Develop a comprehensive market entry strategy")
```

### MajorityVoting

Use Case: Using consensus among multiple agents for decision-making.

```python
voting_router = SwarmRouter(
    name="MajorityVoting",
    description="Make decisions using consensus among agents",
    max_loops=1,
    agents=[analyst1, analyst2, analyst3, consensus_agent],
    swarm_type="MajorityVoting"
)

result = voting_router.run("Should we invest in Company X based on the available data?")
```

### Auto Select (Experimental)

Autonomously selects the right swarm by conducting vector search on your input task or name or description or all 3.

```python
auto_router = SwarmRouter(
    name="MultiSourceAnalyzer",
    description="Analyze multiple data sources concurrently",
    max_loops=1,
    agents=[financial_analyst, market_researcher, competitor_analyst],
    swarm_type="auto" # Set this to 'auto' for it to auto select your swarm. It's match words like concurrently multiple -> "ConcurrentWorkflow"
)

result = auto_router.run("Conduct a comprehensive market analysis for Product X")
```

### InteractiveGroupChat

Use Case: Interactive group discussions with user participation.

```python
interactive_chat_router = SwarmRouter(
    name="InteractiveGroupChat",
    description="Interactive group chat with user participation",
    max_loops=10,
    agents=[financial_analyst, market_researcher, competitor_analyst],
    swarm_type="InteractiveGroupChat",
    output_type="string"
)

result = interactive_chat_router.run("Discuss the market trends and provide interactive analysis")
```

The InteractiveGroupChat allows for dynamic interaction between agents and users, enabling real-time participation in group discussions and decision-making processes. This is particularly useful for scenarios requiring human input or validation during the conversation flow.

## Advanced Features

### Processing Documents

To process documents with the SwarmRouter:

```python
document_router = SwarmRouter(
    name="DocumentProcessor",
    agents=[document_analyzer, summarizer],
    documents=["report.pdf", "contract.docx", "data.csv"],
    swarm_type="SequentialWorkflow"
)

result = document_router.run("Extract key information from the provided documents")
```

### Batch Processing

To process multiple tasks in a batch:

```python
tasks = ["Analyze Q1 report", "Summarize competitor landscape", "Evaluate market trends"]
results = router.batch_run(tasks)
```

### Asynchronous Execution

For asynchronous task execution:

```python
result = await router.async_run("Generate financial projections")
```

### Concurrent Execution

To run a single task concurrently:

```python
result = router.concurrent_run("Analyze multiple data streams")
```

### Concurrent Batch Processing

To process multiple tasks concurrently:

```python
tasks = ["Task 1", "Task 2", "Task 3"]
results = router.concurrent_batch_run(tasks)
```

### Using the SwarmRouter as a Callable

You can use the SwarmRouter instance directly as a callable:

```python
router = SwarmRouter(
    name="CallableRouter",
    agents=[agent1, agent2],
    swarm_type="SequentialWorkflow"
)

result = router("Analyze the market data")  # Equivalent to router.run("Analyze the market data")
```


--------------------------------------------------

# File: swarms/structs/task.md

# Task Class Documentation

The `Task` class is a pivotal component designed for managing tasks in a sequential workflow. This class allows for the execution of tasks using various agents, which can be callable objects or specific instances of the `Agent` class. It supports the scheduling of tasks, handling their dependencies, and setting conditions and actions that govern their execution.

Key features of the `Task` class include:
- Executing tasks with specified agents and handling their results.
- Scheduling tasks to run at specified times.
- Setting triggers, actions, and conditions for tasks.
- Managing task dependencies and priorities.
- Providing a history of task executions for tracking purposes.

## Class Definition

The `Task` class is defined as follows:


### Attributes

| Attribute      | Type                        | Description                                                                           |
|----------------|-----------------------------|---------------------------------------------------------------------------------------|
| `agent`        | `Union[Callable, Agent]`    | The agent or callable object to run the task.                                         |
| `description`  | `str`                       | Description of the task.                                                              |
| `result`       | `Any`                       | Result of the task.                                                                   |
| `history`      | `List[Any]`                 | History of the task.                                                                  |
| `schedule_time`| `datetime`                  | Time to schedule the task.                                                            |
| `scheduler`    | `sched.scheduler`           | Scheduler to schedule the task.                                                       |
| `trigger`      | `Callable`                  | Trigger to run the task.                                                              |
| `action`       | `Callable`                  | Action to run the task.                                                               |
| `condition`    | `Callable`                  | Condition to run the task.                                                            |
| `priority`     | `int`                       | Priority of the task.                                                                 |
| `dependencies` | `List[Task]`                | List of tasks that need to be completed before this task can be executed.             |
| `args`         | `List[Any]`                 | Arguments to pass to the agent or callable object.                                    |
| `kwargs`       | `Dict[str, Any]`            | Keyword arguments to pass to the agent or callable object.                            |

## Methods

### `execute(self, *args, **kwargs)`

Executes the task by calling the agent or model with the specified arguments and keyword arguments. If a condition is set, the task will only execute if the condition returns `True`.

#### Parameters
- `args`: Arguments to pass to the agent or callable object.
- `kwargs`: Keyword arguments to pass to the agent or callable object.

#### Examples

```python
>>> from swarms.structs import Task, Agent
>>> from swarm_models import OpenAIChat
>>> agent = Agent(llm=OpenAIChat(openai_api_key=""), max_loops=1, dashboard=False)
>>> task = Task(description="What's the weather in Miami?", agent=agent)
>>> task.run()
>>> task.result
```

### `handle_scheduled_task(self)`

Handles the execution of a scheduled task. If the schedule time is not set or has already passed, the task is executed immediately. Otherwise, the task is scheduled to be executed at the specified schedule time.

#### Examples

```python
>>> task.schedule_time = datetime.now() + timedelta(seconds=10)
>>> task.handle_scheduled_task()
```

### `set_trigger(self, trigger: Callable)`

Sets the trigger for the task.

#### Parameters
- `trigger` (`Callable`): The trigger to set.

#### Examples

```python
>>> def my_trigger():
>>>     print("Trigger executed")
>>> task.set_trigger(my_trigger)
```

### `set_action(self, action: Callable)`

Sets the action for the task.

#### Parameters
- `action` (`Callable`): The action to set.

#### Examples

```python
>>> def my_action():
>>>     print("Action executed")
>>> task.set_action(my_action)
```

### `set_condition(self, condition: Callable)`

Sets the condition for the task.

#### Parameters
- `condition` (`Callable`): The condition to set.

#### Examples

```python
>>> def my_condition():
>>>     print("Condition checked")
>>>     return True
>>> task.set_condition(my_condition)
```

### `is_completed(self)`

Checks whether the task has been completed.

#### Returns
- `bool`: `True` if the task has been completed, `False` otherwise.

#### Examples

```python
>>> task.is_completed()
```

### `add_dependency(self, task)`

Adds a task to the list of dependencies.

#### Parameters
- `task` (`Task`): The task to add as a dependency.

#### Examples

```python
>>> dependent_task = Task(description="Dependent Task")
>>> task.add_dependency(dependent_task)
```

### `set_priority(self, priority: int)`

Sets the priority of the task.

#### Parameters
- `priority` (`int`): The priority to set.

#### Examples

```python
>>> task.set_priority(5)
```

### `check_dependency_completion(self)`

Checks whether all the dependencies have been completed.

#### Returns
- `bool`: `True` if all the dependencies have been completed, `False` otherwise.

#### Examples

```python
>>> task.check_dependency_completion()
```

### `context(self, task: "Task" = None, context: List["Task"] = None, *args, **kwargs)`

Sets the context for the task. For a sequential workflow, it sequentially adds the context of the previous task in the list.

#### Parameters
- `task` (`Task`, optional): The task whose context is to be set.
- `context` (`List[Task]`, optional): The list of tasks to set the context.

#### Examples

```python
>>> task1 = Task(description="Task 1")
>>> task2 = Task(description="Task 2")
>>> task2.context(context=[task1])
```

## Usage Examples

### Basic Usage

```python
import os
from dotenv import load_dotenv
from swarms import Agent, OpenAIChat, Task

# Load the environment variables
load_dotenv()

# Define a function to be used as the action
def my_action():
    print("Action executed")

# Define a function to be used as the condition
def my_condition():
    print("Condition checked")
    return True

# Create an agent
agent = Agent(
    llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]),
    max_loops=1,
    dashboard=False,
)

# Create a task
task = Task(
    description="Generate a report on the top 3 biggest expenses for small businesses and how businesses can save 20%",
    agent=agent,
)

# Set the action and condition
task.set_action(my_action)
task.set_condition(my_condition)

# Execute the task
print("Executing task...")
task.run()

# Check if the task is completed
if task.is_completed():
    print("Task completed")
else:
    print("Task not completed")

# Output the result of the task
print(f"Task result: {task.result}")
```

### Scheduled Task Execution

```python
from datetime import datetime, timedelta
import os
from dotenv import load_dotenv
from swarms import Agent, OpenAIChat, Task

# Load the environment variables
load_dotenv()

# Create an agent
agent = Agent(
    llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]),
    max_loops=1,
    dashboard=False,
)

# Create a task
task = Task(
    description="Scheduled task example",
    agent=agent,
    schedule_time=datetime.now() + timedelta(seconds=10)
)

# Handle scheduled task
task.handle_scheduled_task()
```

### Task with Dependencies

```python
import os
from dotenv import load_dotenv
from swarms import Agent, OpenAIChat, Task

# Load the environment variables
load_dotenv()

# Create agents
agent1 = Agent(
    llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]),
    max_loops=1,
    dashboard=False,
)
agent2 = Agent(
    llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]),
    max_loops=1,
    dashboard=False,
)

# Create tasks
task1 = Task(description="First task", agent=agent1)
task2 = Task(description="Second task", agent=agent2)

# Add dependency
task2.add_dependency(task1)

# Execute tasks
print("Executing first task...")
task1.run()

print("Executing second task...")
task2.run()

# Check if tasks are completed
print(f"Task 1 completed: {task1.is_completed()}")
print(f"Task 2 completed: {task2.is_completed()}")
```

### Task Context

```python
import os
from dotenv import load_dotenv
from swarms import Agent, OpenAIChat, Task

# Load the environment variables
load_dotenv()

# Create an agent
agent = Agent(
    llm=OpenAIChat(openai_api_key=os.environ["OPENAI_API_KEY"]),
    max_loops

=1,
    dashboard=False,
)

# Create tasks
task1 = Task(description="First task", agent=agent)
task2 = Task(description="Second task", agent=agent)

# Set context for the second task
task2.context(context=[task1])

# Execute tasks
print("Executing first task...")
task1.run()

print("Executing second task...")
task2.run()

# Output the context of the second task
print(f"Task 2 context: {task2.history}")
```


--------------------------------------------------

# File: swarms/structs/taskqueue_swarm.md

# TaskQueueSwarm Documentation

The `TaskQueueSwarm` class is designed to manage and execute tasks using multiple agents concurrently. This class allows for the orchestration of multiple agents processing tasks from a shared queue, facilitating complex workflows where tasks can be distributed and processed in parallel by different agents.

## Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `agents` | `List[Agent]` | The list of agents in the swarm. |
| `task_queue` | `queue.Queue` | A queue to store tasks for processing. |
| `lock` | `threading.Lock` | A lock for thread synchronization. |
| `autosave_on` | `bool` | Whether to automatically save the swarm metadata. |
| `save_file_path` | `str` | The file path for saving swarm metadata. |
| `workspace_dir` | `str` | The directory path of the workspace. |
| `return_metadata_on` | `bool` | Whether to return the swarm metadata after running. |
| `max_loops` | `int` | The maximum number of loops to run the swarm. |
| `metadata` | `SwarmRunMetadata` | Metadata about the swarm run. |

## Methods

### `__init__(self, agents: List[Agent], name: str = "Task-Queue-Swarm", description: str = "A swarm that processes tasks from a queue using multiple agents on different threads.", autosave_on: bool = True, save_file_path: str = "swarm_run_metadata.json", workspace_dir: str = os.getenv("WORKSPACE_DIR"), return_metadata_on: bool = False, max_loops: int = 1, *args, **kwargs)`

The constructor initializes the `TaskQueueSwarm` object.

- **Parameters:**
  - `agents` (`List[Agent]`): The list of agents in the swarm.
  - `name` (`str`, optional): The name of the swarm. Defaults to "Task-Queue-Swarm".
  - `description` (`str`, optional): The description of the swarm. Defaults to "A swarm that processes tasks from a queue using multiple agents on different threads.".
  - `autosave_on` (`bool`, optional): Whether to automatically save the swarm metadata. Defaults to True.
  - `save_file_path` (`str`, optional): The file path to save the swarm metadata. Defaults to "swarm_run_metadata.json".
  - `workspace_dir` (`str`, optional): The directory path of the workspace. Defaults to os.getenv("WORKSPACE_DIR").
  - `return_metadata_on` (`bool`, optional): Whether to return the swarm metadata after running. Defaults to False.
  - `max_loops` (`int`, optional): The maximum number of loops to run the swarm. Defaults to 1.
  - `*args`: Variable length argument list.
  - `**kwargs`: Arbitrary keyword arguments.

### `add_task(self, task: str)`

Adds a task to the queue.

- **Parameters:**
  - `task` (`str`): The task to be added to the queue.

### `run(self)`

Runs the swarm by having agents pick up tasks from the queue.

- **Returns:**
  - `str`: JSON string of the swarm run metadata if `return_metadata_on` is True.

- **Usage Example:**
  ```python
  from swarms import Agent, TaskQueueSwarm


  # Initialize agents
  agent1 = Agent(agent_name="Agent1", model_name="gpt-4o")
  agent2 = Agent(agent_name="Agent2", model_name="gpt-4o")

  # Create the TaskQueueSwarm
  swarm = TaskQueueSwarm(agents=[agent1, agent2], max_loops=5)

  # Add tasks to the swarm
  swarm.add_task("Analyze the latest market trends")
  swarm.add_task("Generate a summary report")

  # Run the swarm
  result = swarm.run()
  print(result)  # Prints the swarm run metadata
  ```

  This example initializes a `TaskQueueSwarm` with two agents, adds tasks to the queue, and runs the swarm.

### `save_json_to_file(self)`

Saves the swarm run metadata to a JSON file.

### `export_metadata(self)`

Exports the swarm run metadata as a JSON string.

- **Returns:**
  - `str`: JSON string of the swarm run metadata.

## Additional Notes

- The `TaskQueueSwarm` uses threading to process tasks concurrently, which can significantly improve performance for I/O-bound tasks.
- The `reliability_checks` method ensures that the swarm is properly configured before running.
- The swarm automatically handles task distribution among agents and provides detailed metadata about the run.
- Error handling and logging are implemented to track the execution flow and capture any issues during task processing.


--------------------------------------------------

# File: swarms/structs/various_execution_methods.md

# Concurrent Agents API Reference

This documentation covers the API for running multiple agents concurrently using various execution strategies. The implementation uses `asyncio` with `uvloop` for enhanced performance and `ThreadPoolExecutor` for handling CPU-bound operations.

## Table of Contents
- [Core Functions](#core-functions)
- [Advanced Functions](#advanced-functions)
- [Utility Functions](#utility-functions)
- [Resource Monitoring](#resource-monitoring)
- [Usage Examples](#usage-examples)

## Core Functions

### run_agents_concurrently()

Primary function for running multiple agents concurrently with optimized performance using both uvloop and ThreadPoolExecutor.

#### Arguments

| Parameter    | Type           | Required | Default        | Description |
|-------------|----------------|----------|----------------|-------------|
| agents      | List[AgentType]| Yes      | -              | List of Agent instances to run concurrently |
| task        | str            | Yes      | -              | Task string to execute |
| batch_size  | int           | No       | CPU count      | Number of agents to run in parallel in each batch |
| max_workers | int           | No       | CPU count * 2  | Maximum number of threads in the executor |

#### Returns
`List[Any]`: List of outputs from each agent

#### Flow Diagram

```mermaid
graph TD
    A[Start] --> B[Initialize ThreadPoolExecutor]
    B --> C[Split Agents into Batches]
    C --> D[Process Batch]
    D --> E{More Batches?}
    E -->|Yes| D
    E -->|No| F[Combine Results]
    F --> G[Return Results]
    
    subgraph "Batch Processing"
    D --> H[Run Agents Async]
    H --> I[Wait for Completion]
    I --> J[Collect Batch Results]
    end
```

### run_agents_sequentially()

Runs multiple agents sequentially for baseline comparison or simple use cases.

#### Arguments

| Parameter | Type           | Required | Default | Description |
|-----------|----------------|----------|---------|-------------|
| agents    | List[AgentType]| Yes      | -       | List of Agent instances to run |
| task      | str            | Yes      | -       | Task string to execute |

#### Returns
`List[Any]`: List of outputs from each agent

## Advanced Functions

### run_agents_with_different_tasks()

Runs multiple agents with different tasks concurrently.

#### Arguments

| Parameter        | Type                          | Required | Default        | Description |
|-----------------|-------------------------------|----------|----------------|-------------|
| agent_task_pairs| List[tuple[AgentType, str]]   | Yes      | -              | List of (agent, task) tuples |
| batch_size      | int                           | No       | CPU count      | Number of agents to run in parallel |
| max_workers     | int                           | No       | CPU count * 2  | Maximum number of threads |

### run_agents_with_timeout()

Runs multiple agents concurrently with timeout limits.

#### Arguments

| Parameter    | Type           | Required | Default        | Description |
|-------------|----------------|----------|----------------|-------------|
| agents      | List[AgentType]| Yes      | -              | List of Agent instances |
| task        | str            | Yes      | -              | Task string to execute |
| timeout     | float          | Yes      | -              | Timeout in seconds for each agent |
| batch_size  | int           | No       | CPU count      | Number of agents to run in parallel |
| max_workers | int           | No       | CPU count * 2  | Maximum number of threads |

## Usage Examples

```python
from swarms.structs.agent import Agent
from swarms.structs.multi_agent_exec import (
    run_agents_concurrently,
    run_agents_with_timeout,
    run_agents_with_different_tasks
)

# Initialize agents using only the built-in model_name parameter
agents = [
    Agent(
        agent_name=f"Analysis-Agent-{i}",
        system_prompt="You are a financial analysis expert",
        model_name="gpt-4o-mini",
        max_loops=1
    )
    for i in range(5)
]

# Basic concurrent execution
task = "Analyze the impact of rising interest rates on tech stocks"
outputs = run_agents_concurrently(agents, task)

# Running with timeout
outputs_with_timeout = run_agents_with_timeout(
    agents=agents,
    task=task,
    timeout=30.0,
    batch_size=2
)

# Running different tasks
task_pairs = [
    (agents[0], "Analyze tech stocks"),
    (agents[1], "Analyze energy stocks"),
    (agents[2], "Analyze retail stocks")
]
different_outputs = run_agents_with_different_tasks(task_pairs)
```

## Resource Monitoring

### ResourceMetrics

A dataclass for system resource metrics.

#### Properties

| Property        | Type  | Description |
|----------------|-------|-------------|
| cpu_percent    | float | Current CPU usage percentage |
| memory_percent | float | Current memory usage percentage |
| active_threads | int   | Number of active threads |

### run_agents_with_resource_monitoring()

Runs agents with system resource monitoring and adaptive batch sizing.

#### Arguments

| Parameter         | Type           | Required | Default | Description |
|------------------|----------------|----------|---------|-------------|
| agents           | List[AgentType]| Yes      | -       | List of Agent instances |
| task             | str            | Yes      | -       | Task string to execute |
| cpu_threshold    | float          | No       | 90.0    | Max CPU usage percentage |
| memory_threshold | float          | No       | 90.0    | Max memory usage percentage |
| check_interval   | float          | No       | 1.0     | Resource check interval in seconds |

## Performance Considerations

- Default batch sizes and worker counts are optimized based on CPU cores
- Resource monitoring helps prevent system overload
- Using `uvloop` provides better performance than standard `asyncio`

## Error Handling

- Functions handle asyncio event loop creation/retrieval
- Timeout mechanism prevents infinite waiting
- Resource monitoring allows for adaptive performance adjustment

--------------------------------------------------

# File: swarms/structs/yaml_model.md

# YamlModel: A Pydantic Model for YAML Data

The `YamlModel` class, derived from `BaseModel` in Pydantic, offers a convenient way to work with YAML data in your Python applications. It provides methods for serialization (converting to YAML), deserialization (creating an instance from YAML), and schema generation. This documentation will delve into the functionalities of `YamlModel` and guide you through its usage with illustrative examples.

### Purpose and Functionality

The primary purpose of `YamlModel` is to streamline the interaction between your Python code and YAML data. It accomplishes this by:

* **Serialization:** Transforming a `YamlModel` instance into a YAML string representation using the `to_yaml()` method.
* **Deserialization:** Constructing a `YamlModel` instance from a provided YAML string using the `from_yaml()` class method.
* **JSON to YAML Conversion:** Facilitating the conversion of JSON data to YAML format through the `json_to_yaml()` static method.
* **Saving to YAML File:** Enabling the storage of `YamlModel` instances as YAML files using the `save_to_yaml()` method.
* (Future Implementation) **Schema Generation:** The `create_yaml_schema()` class method (not yet implemented but included for future reference) will generate a YAML schema that reflects the structure of the `YamlModel` class and its fields.

### Class Definition and Arguments

The `YamlModel` class inherits from Pydantic's `BaseModel` class. You can define your custom YAML models by creating subclasses of `YamlModel` and specifying your data fields within the class definition. Here's the breakdown of the `YamlModel` class and its methods:

```python
class YamlModel(BaseModel):
    """
    A Pydantic model class for working with YAML data.
    """

    def to_yaml(self):
        """
        Serialize the Pydantic model instance to a YAML string.
        """
        return yaml.safe_dump(self.dict(), sort_keys=False)

    @classmethod
    def from_yaml(cls, yaml_str: str):
        """
        Create an instance of the class from a YAML string.

        Args:
            yaml_str (str): The YAML string to parse.

        Returns:
            cls: An instance of the class with attributes populated from the YAML data.
                 Returns None if there was an error loading the YAML data.
        """
        # ...

    @staticmethod
    def json_to_yaml(json_str: str):
        """
        Convert a JSON string to a YAML string.
        """
        # ...

    def save_to_yaml(self, filename: str):
        """
        Save the Pydantic model instance as a YAML file.
        """
        # ...

    # TODO: Implement a method to create a YAML schema from the model fields
    # @classmethod
    # def create_yaml_schema(cls):
    #     # ...
    """
```

**Arguments:**

* `self` (implicit): Refers to the current instance of the `YamlModel` class.
* `yaml_str` (str): The YAML string used for deserialization in the `from_yaml()` method.
* `json_str` (str): The JSON string used for conversion to YAML in the `json_to_yaml()` method.
* `filename` (str): The filename (including path) for saving the YAML model instance in the `save_to_yaml()` method.

### Detailed Method Descriptions

**1. to_yaml()**

This method transforms an instance of the `YamlModel` class into a YAML string representation. It utilizes the `yaml.safe_dump()` function from the `PyYAML` library to ensure secure YAML data generation. The `sort_keys=False` argument guarantees that the order of keys in the resulting YAML string remains consistent with the order of fields defined in your `YamlModel` subclass.

**Example:**

```python
class User(YamlModel):
    name: str
    age: int
    is_active: bool

user = User(name="Bob", age=30, is_active=True)
yaml_string = user.to_yaml()
print(yaml_string)
```

This code will output a YAML string representation of the `user` object, resembling:

```yaml
name: Bob
age: 30
is_active: true
```

### Detailed Method Descriptions 

**2. from_yaml(cls, yaml_str)** (Class Method)

The `from_yaml()` class method is responsible for constructing a `YamlModel` instance from a provided YAML string. 

* **Arguments:**
    * `cls` (class): The class representing the desired YAML model (the subclass of `YamlModel` that matches the structure of the YAML data).
    * `yaml_str` (str): The YAML string containing the data to be parsed and used for creating the model instance.

* **Returns:**
    * `cls` (instance): An instance of the specified class (`cls`) populated with the data extracted from the YAML string. If an error occurs during parsing, it returns `None`.

* **Error Handling:**

The `from_yaml()` method employs `yaml.safe_load()` for secure YAML parsing. It incorporates a `try-except` block to handle potential `ValueError` exceptions that might arise during the parsing process. If an error is encountered, it logs the error message and returns `None`.

**Example:**

```python
class User(YamlModel):
    name: str
    age: int
    is_active: bool

yaml_string = """
name: Alice
age: 25
is_active: false
"""

user = User.from_yaml(yaml_string)
print(user.name)  # Output: Alice
```

**3. json_to_yaml(json_str)** (Static Method)

This static method in the `YamlModel` class serves the purpose of converting a JSON string into a YAML string representation.

* **Arguments:**
    * `json_str` (str): The JSON string that needs to be converted to YAML format.

* **Returns:**
    * `str`: The converted YAML string representation of the provided JSON data.

* **Functionality:**

The `json_to_yaml()` method leverages the `json.loads()` function to parse the JSON string into a Python dictionary. Subsequently, it utilizes `yaml.dump()` to generate the corresponding YAML string representation from the parsed dictionary.

**Example:**

```python
json_string = '{"name": "Charlie", "age": 42, "is_active": true}'
yaml_string = YamlModel.json_to_yaml(json_string)
print(yaml_string)
```

This code snippet will convert the JSON data to a YAML string, likely resembling:

```yaml
name: Charlie
age: 42
is_active: true
```

**4. save_to_yaml(self, filename)**

The `save_to_yaml()` method facilitates the storage of a `YamlModel` instance as a YAML file.

* **Arguments:**
    * `self` (implicit): Refers to the current instance of the `YamlModel` class that you intend to save.
    * `filename` (str): The desired filename (including path) for the YAML file.

* **Functionality:**

The `save_to_yaml()` method employs the previously explained `to_yaml()` method to generate a YAML string representation of the `self` instance. It then opens the specified file in write mode (`"w"`) and writes the YAML string content to the file.

**Example:**

```python
class Employee(YamlModel):
    name: str
    department: str
    salary: float

employee = Employee(name="David", department="Engineering", salary=95000.00)
employee.save_to_yaml("employee.yaml")
```

This code will create a YAML file named "employee.yaml" containing the serialized representation of the `employee` object.


### More Usage Examples ++ 

```python
class User(YamlModel):
    name: str
    age: int
    is_active: bool

# Create an instance of the User model
user = User(name="Alice", age=30, is_active=True)

# Serialize the User instance to YAML and print it
yaml_string = user.to_yaml()
print(yaml_string)
```

This code snippet demonstrates the creation of a `User` instance and its subsequent serialization to a YAML string using the `to_yaml()` method. The printed output will likely resemble:

```yaml
name: Alice
age: 30
is_active: true
```

### Converting JSON to YAML

```python
# Convert JSON string to YAML and print
json_string = '{"name": "Bob", "age": 25, "is_active": false}'
yaml_string = YamlModel.json_to_yaml(json_string)
print(yaml_string)
```

This example showcases the conversion of a JSON string containing user data into a YAML string representation using the `json_to_yaml()` static method. The resulting YAML string might look like:

```yaml
name: Bob
age: 25
is_active: false
```

### Saving User Instance to YAML File

```python
# Save the User instance to a YAML file
user.save_to_yaml("user.yaml")
```

This code demonstrates the utilization of the `save_to_yaml()` method to store the `user` instance as a YAML file named "user.yaml". The contents of the file will mirror the serialized YAML string representation of the user object.

## Additional Considerations

* Ensure you have the `PyYAML` library installed (`pip install pyyaml`) to leverage the YAML parsing and serialization functionalities within `YamlModel`.
* Remember that the `create_yaml_schema()` method is not yet implemented but serves as a placeholder for future enhancements.
* For complex data structures within your YAML models, consider leveraging Pydantic's data validation and nested model capabilities for robust data management.

## Conclusion

The `YamlModel` class in Pydantic offers a streamlined approach to working with YAML data in your Python projects. By employing the provided methods (`to_yaml()`, `from_yaml()`, `json_to_yaml()`, and `save_to_yaml()`), you can efficiently convert between Python objects and YAML representations, facilitating data persistence and exchange. This comprehensive documentation empowers you to effectively utilize `YamlModel` for your YAML data processing requirements.

--------------------------------------------------

# File: swarms/support.md

# Technical Support

*Getting Help with the Swarms Multi-Agent Framework*

---

## **Getting Started with Support**

The Swarms team is committed to providing exceptional technical support to help you build production-grade multi-agent systems. Whether you're experiencing bugs, need implementation guidance, or want to request new features, we have multiple channels to ensure you get the help you need quickly and efficiently.

---

## **Support Channels Overview**

| **Support Type** | **Best For** | **Response Time** | **Channel** |
|------------------|--------------|-------------------|-------------|
| **Bug Reports** | Code issues, errors, unexpected behavior | < 24 hours | [GitHub Issues](https://github.com/kyegomez/swarms/issues) |
| **Major Features (SIPs)** | New agent types, core changes, integrations | 1-2 weeks | [SIP Guidelines](protocol/sip.md) |
| **Minor Features** | Small enhancements, straightforward additions | < 48 hours | [GitHub Issues](https://github.com/kyegomez/swarms/issues) |
| **Private Issues** | Security concerns, enterprise consulting | < 4 hours | [Book Support Call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) |
| **Real-time Help** | Quick questions, community discussions | Immediate | [Discord Community](https://discord.gg/EamjgSaEQf) |
| **Documentation** | Usage guides, examples, tutorials | Self-service | [docs.swarms.world](https://docs.swarms.world) |

---

## **Reporting Bugs & Technical Issues**

### **When to Use GitHub Issues**

Use GitHub Issues for:

- Code bugs and errors

- Installation problems

- Documentation issues

- Performance problems

- API inconsistencies

- Public technical discussions

### **How to Create an Effective Bug Report**

1. **Visit our Issues page**: [https://github.com/kyegomez/swarms/issues](https://github.com/kyegomez/swarms/issues)

2. **Search existing issues** to avoid duplicates

3. **Click "New Issue"** and select the appropriate template

4. **Include the following information**:

## Bug Description

A clear description of what the bug is.

## Environment

- Swarms version: [e.g., 5.9.2]

- Python version: [e.g., 3.9.0]

- Operating System: [e.g., Ubuntu 20.04, macOS 14, Windows 11]

- Model provider: [e.g., OpenAI, Anthropic, Groq]


## Steps to Reproduce

1. Step one
2. Step two
3. Step three

## Expected Behavior

What you expected to happen.

## Actual Behavior

What actually happened.

## Code Sample

```python
# Minimal code that reproduces the issue
from swarms import Agent

agent = Agent(model_name="gpt-4o-mini")
result = agent.run("Your task here")
```

## Error Messages

Paste any error messages or stack traces here


## Additional Context

Any other context, screenshots, or logs that might help.

### **Issue Templates Available**

| Template | Use Case |
|----------|----------|
| **Bug Report** | Standard bug reporting template |
| **Documentation** | Issues with docs, guides, examples |
| **Feature Request** | Suggesting new functionality |
| **Question** | General questions about usage |
| **Enterprise** | Enterprise-specific issues |

---

## **Private & Enterprise Support**

### **When to Book a Private Support Call**

Book a private consultation for:

- Security vulnerabilities or concerns

- Enterprise deployment guidance

- Custom implementation consulting

- Architecture review sessions

- Performance optimization

- Integration troubleshooting

- Strategic technical planning


### **How to Schedule Support**

1. **Visit our booking page**: [https://cal.com/swarms/swarms-technical-support?overlayCalendar=true](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true)

2. **Select an available time** that works for your timezone

3. **Provide details** about your issue or requirements

4. **Prepare for the call**:
   - Have your code/environment ready

   - Prepare specific questions

   - Include relevant error messages or logs

   - Share your use case and goals


### **What to Expect**

- **Direct access** to Swarms core team members

- **Screen sharing** for live debugging

- **Custom solutions** tailored to your needs

- **Follow-up resources** and documentation

- **Priority support** for implementation


---

## **Real-Time Community Support**

### **Join Our Discord Community**

Get instant help from our active community of developers and core team members.

**Discord Benefits:**

- **24/7 availability** - Someone is always online

- **Instant responses** - Get help in real-time

- **Community wisdom** - Learn from other developers

- **Specialized channels** - Find the right help quickly

- **Latest updates** - Stay informed about new releases


### **Discord Channels Guide**

| Channel | Purpose |
|---------|---------|
| **#general** | General discussions and introductions |
| **#technical-support** | Technical questions and troubleshooting |
| **#showcase** | Share your Swarms projects and demos |
| **#feature-requests** | Discuss potential new features |
| **#announcements** | Official updates and releases |
| **#resources** | Helpful links, tutorials, and guides |

### **Getting Help on Discord**

1. **Join here**: [https://discord.gg/EamjgSaEQf](https://discord.gg/EamjgSaEQf)

2. **Read the rules** and introduce yourself in #general

3. **Use the right channel** for your question type

4. **Provide context** when asking questions:
   ```
   Python version: 3.9
   Swarms version: 5.9.2
   OS: macOS 14
   Question: How do I implement custom tools with MCP?
   What I tried: [paste your code]
   Error: [paste error message]
   ```

5. **Be patient and respectful** - our community loves helping!


---

## **Feature Requests & Enhancement Suggestions**

### **Swarms Improvement Proposals (SIPs)**

The primary way to propose new features and significant enhancements to the Swarms framework is through the **Swarms Improvement Proposal (SIP)** process. SIPs are design documents that describe new features, enhancements, or changes to the framework.

**When to Submit a SIP:**

- New agent types or behaviors
- Core framework changes
- New integrations with external services
- Breaking changes
- Complex features requiring community discussion

**SIP Process Overview:**

1. **Discuss First**: Share your idea in [GitHub Discussions](https://github.com/kyegomez/swarms/discussions)
2. **Create SIP**: Submit as GitHub Issue with `SIP` and `proposal` labels
3. **Community Review**: Engage with feedback and iterate on the proposal
4. **Implementation**: Once accepted, work on the implementation

For detailed guidelines on creating and submitting SIPs, visit our [SIP Guidelines](protocol/sip.md).

### **Other Feature Requests**

For smaller enhancements or straightforward additions that don't require a full SIP, you can:

**Use GitHub Issues:**
- Visit [GitHub Issues](https://github.com/kyegomez/swarms/issues)
- Select the "Feature Request" template
- Provide detailed description and use cases

**Contact Direct Support:**
For enterprise-specific features or private discussions:
- **Email**: [kye@swarms.world](mailto:kye@swarms.world)
- **Subject Format**: `[FEATURE REQUEST] Brief description`

### **Feature Request Process**

1. **Email submission** with detailed requirements
2. **Initial review** within 48 hours
3. **Technical feasibility** assessment
4. **Community feedback** gathering (if applicable)
5. **Roadmap planning** and timeline estimation
6. **Development** and testing
7. **Release** with documentation

---

## **Self-Service Resources**

Before reaching out for support, check these resources:

### **Documentation**

- **[Complete Documentation](https://docs.swarms.world)** - Comprehensive guides and API reference

- **[Installation Guide](https://docs.swarms.world/en/latest/swarms/install/install/)** - Setup and configuration

- **[Quick Start](https://docs.swarms.world/en/latest/quickstart/)** - Get up and running fast

- **[Examples Gallery](https://docs.swarms.world/en/latest/examples/)** - Real-world use cases


### **Common Solutions**

| Issue | Solution |
|-------|----------|
| **Installation fails** | Check [Environment Setup](https://docs.swarms.world/en/latest/swarms/install/env/) |
| **Model not responding** | Verify API keys in environment variables |
| **Import errors** | Ensure latest version: `pip install -U swarms` |
| **Memory issues** | Review [Performance Guide](https://docs.swarms.world/en/latest/swarms/framework/test/) |
| **Agent not working** | Check [Basic Agent Example](https://docs.swarms.world/en/latest/swarms/examples/basic_agent/) |

### **Video Tutorials**

- **[YouTube Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ)** - Step-by-step tutorials

- **[Live Coding Sessions](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ)** - Real-world implementations


---

## **Support Checklist**

Before requesting support, please:

- [ ] **Check the documentation** for existing solutions

- [ ] **Search GitHub issues** for similar problems

- [ ] **Update to latest version**: `pip install -U swarms`

- [ ] **Verify environment setup** and API keys

- [ ] **Test with minimal code** to isolate the issue

- [ ] **Gather error messages** and relevant logs

- [ ] **Note your environment** (OS, Python version, Swarms version)


---

## **Support Best Practices**

### **For Faster Resolution**

1. **Be Specific**: Provide exact error messages and steps to reproduce
2. **Include Code**: Share minimal, runnable examples
3. **Environment Details**: Always include version information
4. **Search First**: Check if your issue has been addressed before
5. **One Issue Per Report**: Don't combine multiple problems
6. **Follow Up**: Respond promptly to requests for additional information

### **Response Time Expectations**

| Priority | Response Time | Resolution Time |
|----------|---------------|-----------------|
| **Critical** (Production down) | < 2 hours | < 24 hours |
| **High** (Major functionality blocked) | < 8 hours | < 48 hours |
| **Medium** (Feature issues) | < 24 hours | < 1 week |
| **Low** (Documentation, enhancements) | < 48 hours | Next release |

---

## **Contributing Back**

Help improve support for everyone:

- **Answer questions** in Discord or GitHub

- **Improve documentation** with your learnings

- **Share examples** of successful implementations

- **Report bugs** you discover

- **Suggest improvements** to this support process


**Your contributions make Swarms better for everyone.**

---

## **Support Channel Summary**

| Urgency | Best Channel |
|---------|-------------|
| **Emergency** | [Book Immediate Call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) |
| **Urgent** | [Discord #technical-support](https://discord.gg/EamjgSaEQf) |
| **Standard** | [GitHub Issues](https://github.com/kyegomez/swarms/issues) |
| **Major Features** | [SIP Guidelines](protocol/sip.md) |
| **Minor Features** | [GitHub Issues](https://github.com/kyegomez/swarms/issues) |

**We're here to help you succeed with Swarms.**


--------------------------------------------------

# File: swarms/tools/base_tool.md

# BaseTool Class Documentation

## Overview

The `BaseTool` class is a comprehensive tool management system for function calling, schema conversion, and execution. It provides a unified interface for converting Python functions to OpenAI function calling schemas, managing Pydantic models, executing tools with proper error handling, and supporting multiple AI provider formats (OpenAI, Anthropic, etc.).

**Key Features:**

- Convert Python functions to OpenAI function calling schemas

- Manage Pydantic models and their schemas  

- Execute tools with proper error handling and validation

- Support for parallel and sequential function execution

- Schema validation for multiple AI providers

- Automatic tool execution from API responses

- Caching for improved performance

## Initialization Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `verbose` | `Optional[bool]` | `None` | Enable detailed logging output |
| `base_models` | `Optional[List[type[BaseModel]]]` | `None` | List of Pydantic models to manage |
| `autocheck` | `Optional[bool]` | `None` | Enable automatic validation checks |
| `auto_execute_tool` | `Optional[bool]` | `None` | Enable automatic tool execution |
| `tools` | `Optional[List[Callable[..., Any]]]` | `None` | List of callable functions to manage |
| `tool_system_prompt` | `Optional[str]` | `None` | System prompt for tool operations |
| `function_map` | `Optional[Dict[str, Callable]]` | `None` | Mapping of function names to callables |
| `list_of_dicts` | `Optional[List[Dict[str, Any]]]` | `None` | List of dictionary representations |

## Methods Overview

| Method | Description |
|--------|-------------|
| `func_to_dict` | Convert a callable function to OpenAI function calling schema |
| `load_params_from_func_for_pybasemodel` | Load function parameters for Pydantic BaseModel integration |
| `base_model_to_dict` | Convert Pydantic BaseModel to OpenAI schema dictionary |
| `multi_base_models_to_dict` | Convert multiple Pydantic BaseModels to OpenAI schema |
| `dict_to_openai_schema_str` | Convert dictionary to OpenAI schema string |
| `multi_dict_to_openai_schema_str` | Convert multiple dictionaries to OpenAI schema string |
| `get_docs_from_callable` | Extract documentation from callable items |
| `execute_tool` | Execute a tool based on response string |
| `detect_tool_input_type` | Detect the type of tool input |
| `dynamic_run` | Execute dynamic run with automatic type detection |
| `execute_tool_by_name` | Search for and execute tool by name |
| `execute_tool_from_text` | Execute tool from JSON-formatted string |
| `check_str_for_functions_valid` | Check if output is valid JSON with matching function |
| `convert_funcs_into_tools` | Convert all functions in tools list to OpenAI format |
| `convert_tool_into_openai_schema` | Convert tools into OpenAI function calling schema |
| `check_func_if_have_docs` | Check if function has proper documentation |
| `check_func_if_have_type_hints` | Check if function has proper type hints |
| `find_function_name` | Find function by name in tools list |
| `function_to_dict` | Convert function to dictionary representation |
| `multiple_functions_to_dict` | Convert multiple functions to dictionary representations |
| `execute_function_with_dict` | Execute function using dictionary of parameters |
| `execute_multiple_functions_with_dict` | Execute multiple functions with parameter dictionaries |
| `validate_function_schema` | Validate function schema for different AI providers |
| `get_schema_provider_format` | Get detected provider format of schema |
| `convert_schema_between_providers` | Convert schema between provider formats |
| `execute_function_calls_from_api_response` | Execute function calls from API responses |
| `detect_api_response_format` | Detect the format of API response |

---

## Detailed Method Documentation

### `func_to_dict`

**Description:** Convert a callable function to OpenAI function calling schema dictionary.

**Arguments:**
- `function` (Callable[..., Any], optional): The function to convert

**Returns:** `Dict[str, Any]` - OpenAI function calling schema dictionary

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def add_numbers(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

# Create BaseTool instance
tool = BaseTool(verbose=True)

# Convert function to OpenAI schema
schema = tool.func_to_dict(add_numbers)
print(schema)
# Output: {'type': 'function', 'function': {'name': 'add_numbers', 'description': 'Add two numbers together.', 'parameters': {...}}}
```

### `load_params_from_func_for_pybasemodel`

**Description:** Load and process function parameters for Pydantic BaseModel integration.

**Arguments:**

- `func` (Callable[..., Any]): The function to process

- `*args`: Additional positional arguments

- `**kwargs`: Additional keyword arguments

**Returns:** `Callable[..., Any]` - Processed function with loaded parameters

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def calculate_area(length: float, width: float) -> float:
    """Calculate area of a rectangle."""
    return length * width

tool = BaseTool()
processed_func = tool.load_params_from_func_for_pybasemodel(calculate_area)
```

### `base_model_to_dict`

**Description:** Convert a Pydantic BaseModel to OpenAI function calling schema dictionary.

**Arguments:**

- `pydantic_type` (type[BaseModel]): The Pydantic model class to convert

- `*args`: Additional positional arguments

- `**kwargs`: Additional keyword arguments

**Returns:** `dict[str, Any]` - OpenAI function calling schema dictionary

**Example:**
```python
from pydantic import BaseModel
from swarms.tools.base_tool import BaseTool

class UserInfo(BaseModel):
    name: str
    age: int
    email: str

tool = BaseTool()
schema = tool.base_model_to_dict(UserInfo)
print(schema)
```

### `multi_base_models_to_dict`

**Description:** Convert multiple Pydantic BaseModels to OpenAI function calling schema.

**Arguments:**
- `base_models` (List[BaseModel]): List of Pydantic models to convert

**Returns:** `dict[str, Any]` - Combined OpenAI function calling schema

**Example:**
```python
from pydantic import BaseModel
from swarms.tools.base_tool import BaseTool

class User(BaseModel):
    name: str
    age: int

class Product(BaseModel):
    name: str
    price: float

tool = BaseTool()
schemas = tool.multi_base_models_to_dict([User, Product])
print(schemas)
```

### `dict_to_openai_schema_str`

**Description:** Convert a dictionary to OpenAI function calling schema string.

**Arguments:**

- `dict` (dict[str, Any]): Dictionary to convert

**Returns:** `str` - OpenAI schema string representation

**Example:**
```python
from swarms.tools.base_tool import BaseTool

my_dict = {
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get weather information",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
    }
}

tool = BaseTool()
schema_str = tool.dict_to_openai_schema_str(my_dict)
print(schema_str)
```

### `multi_dict_to_openai_schema_str`

**Description:** Convert multiple dictionaries to OpenAI function calling schema string.

**Arguments:**

- `dicts` (list[dict[str, Any]]): List of dictionaries to convert

**Returns:** `str` - Combined OpenAI schema string representation

**Example:**
```python
from swarms.tools.base_tool import BaseTool

dict1 = {"type": "function", "function": {"name": "func1", "description": "Function 1"}}
dict2 = {"type": "function", "function": {"name": "func2", "description": "Function 2"}}

tool = BaseTool()
schema_str = tool.multi_dict_to_openai_schema_str([dict1, dict2])
print(schema_str)
```

### `get_docs_from_callable`

**Description:** Extract documentation from a callable item.

**Arguments:**

- `item`: The callable item to extract documentation from

**Returns:** Processed documentation

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def example_function():
    """This is an example function with documentation."""
    pass

tool = BaseTool()
docs = tool.get_docs_from_callable(example_function)
print(docs)
```

### `execute_tool`

**Description:** Execute a tool based on a response string.

**Arguments:**
- `response` (str): JSON response string containing tool execution details

- `*args`: Additional positional arguments

- `**kwargs`: Additional keyword arguments

**Returns:** `Callable` - Result of the tool execution

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

tool = BaseTool(tools=[greet])
response = '{"name": "greet", "parameters": {"name": "Alice"}}'
result = tool.execute_tool(response)
print(result)  # Output: "Hello, Alice!"
```

### `detect_tool_input_type`

**Description:** Detect the type of tool input for appropriate processing.

**Arguments:**

- `input` (ToolType): The input to analyze

**Returns:** `str` - Type of the input ("Pydantic", "Dictionary", "Function", or "Unknown")

**Example:**
```python
from swarms.tools.base_tool import BaseTool
from pydantic import BaseModel

class MyModel(BaseModel):
    value: int

def my_function():
    pass

tool = BaseTool()
print(tool.detect_tool_input_type(MyModel))  # "Pydantic"
print(tool.detect_tool_input_type(my_function))  # "Function"
print(tool.detect_tool_input_type({"key": "value"}))  # "Dictionary"
```

### `dynamic_run`

**Description:** Execute a dynamic run based on the input type with automatic type detection.

**Arguments:**
- `input` (Any): The input to be processed (Pydantic model, dict, or function)

**Returns:** `str` - The result of the dynamic run (schema string or execution result)

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def multiply(x: int, y: int) -> int:
    """Multiply two numbers."""
    return x * y

tool = BaseTool(auto_execute_tool=False)
result = tool.dynamic_run(multiply)
print(result)  # Returns OpenAI schema string
```

### `execute_tool_by_name`

**Description:** Search for a tool by name and execute it with the provided response.

**Arguments:**
- `tool_name` (str): The name of the tool to execute

- `response` (str): JSON response string containing execution parameters

**Returns:** `Any` - The result of executing the tool

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def calculate_sum(a: int, b: int) -> int:
    """Calculate sum of two numbers."""
    return a + b

tool = BaseTool(function_map={"calculate_sum": calculate_sum})
result = tool.execute_tool_by_name("calculate_sum", '{"a": 5, "b": 3}')
print(result)  # Output: 8
```

### `execute_tool_from_text`

**Description:** Convert a JSON-formatted string into a tool dictionary and execute the tool.

**Arguments:**
- `text` (str): A JSON-formatted string representing a tool call with 'name' and 'parameters' keys

**Returns:** `Any` - The result of executing the tool

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def divide(x: float, y: float) -> float:
    """Divide x by y."""
    return x / y

tool = BaseTool(function_map={"divide": divide})
text = '{"name": "divide", "parameters": {"x": 10, "y": 2}}'
result = tool.execute_tool_from_text(text)
print(result)  # Output: 5.0
```

### `check_str_for_functions_valid`

**Description:** Check if the output is a valid JSON string with a function name that matches the function map.

**Arguments:**
- `output` (str): The output string to validate

**Returns:** `bool` - True if the output is valid and the function name matches, False otherwise

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def test_func():
    pass

tool = BaseTool(function_map={"test_func": test_func})
valid_output = '{"type": "function", "function": {"name": "test_func"}}'
is_valid = tool.check_str_for_functions_valid(valid_output)
print(is_valid)  # Output: True
```

### `convert_funcs_into_tools`

**Description:** Convert all functions in the tools list into OpenAI function calling format.

**Arguments:** None

**Returns:** None (modifies internal state)

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def func1(x: int) -> int:
    """Function 1."""
    return x * 2

def func2(y: str) -> str:
    """Function 2."""
    return y.upper()

tool = BaseTool(tools=[func1, func2])
tool.convert_funcs_into_tools()
print(tool.function_map)  # {'func1': <function func1>, 'func2': <function func2>}
```

### `convert_tool_into_openai_schema`

**Description:** Convert tools into OpenAI function calling schema format.

**Arguments:** None

**Returns:** `dict[str, Any]` - Combined OpenAI function calling schema

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

def subtract(a: int, b: int) -> int:
    """Subtract b from a."""
    return a - b

tool = BaseTool(tools=[add, subtract])
schema = tool.convert_tool_into_openai_schema()
print(schema)
```

### `check_func_if_have_docs`

**Description:** Check if a function has proper documentation.

**Arguments:**

- `func` (callable): The function to check

**Returns:** `bool` - True if function has documentation

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def documented_func():
    """This function has documentation."""
    pass

def undocumented_func():
    pass

tool = BaseTool()
print(tool.check_func_if_have_docs(documented_func))  # True
# tool.check_func_if_have_docs(undocumented_func)  # Raises ToolDocumentationError
```

### `check_func_if_have_type_hints`

**Description:** Check if a function has proper type hints.

**Arguments:**

- `func` (callable): The function to check

**Returns:** `bool` - True if function has type hints

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def typed_func(x: int) -> str:
    """A typed function."""
    return str(x)

def untyped_func(x):
    """An untyped function."""
    return str(x)

tool = BaseTool()
print(tool.check_func_if_have_type_hints(typed_func))  # True
# tool.check_func_if_have_type_hints(untyped_func)  # Raises ToolTypeHintError
```

### `find_function_name`

**Description:** Find a function by name in the tools list.

**Arguments:**
- `func_name` (str): The name of the function to find

**Returns:** `Optional[callable]` - The function if found, None otherwise

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def my_function():
    """My function."""
    pass

tool = BaseTool(tools=[my_function])
found_func = tool.find_function_name("my_function")
print(found_func)  # <function my_function at ...>
```

### `function_to_dict`

**Description:** Convert a function to dictionary representation.

**Arguments:**
- `func` (callable): The function to convert

**Returns:** `dict` - Dictionary representation of the function

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def example_func(param: str) -> str:
    """Example function."""
    return param

tool = BaseTool()
func_dict = tool.function_to_dict(example_func)
print(func_dict)
```

### `multiple_functions_to_dict`

**Description:** Convert multiple functions to dictionary representations.

**Arguments:**

- `funcs` (list[callable]): List of functions to convert

**Returns:** `list[dict]` - List of dictionary representations

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def func1(x: int) -> int:
    """Function 1."""
    return x

def func2(y: str) -> str:
    """Function 2."""
    return y

tool = BaseTool()
func_dicts = tool.multiple_functions_to_dict([func1, func2])
print(func_dicts)
```

### `execute_function_with_dict`

**Description:** Execute a function using a dictionary of parameters.

**Arguments:**

- `func_dict` (dict): Dictionary containing function parameters

- `func_name` (Optional[str]): Name of function to execute (if not in dict)

**Returns:** `Any` - Result of function execution

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def power(base: int, exponent: int) -> int:
    """Calculate base to the power of exponent."""
    return base ** exponent

tool = BaseTool(tools=[power])
result = tool.execute_function_with_dict({"base": 2, "exponent": 3}, "power")
print(result)  # Output: 8
```

### `execute_multiple_functions_with_dict`

**Description:** Execute multiple functions using dictionaries of parameters.

**Arguments:**

- `func_dicts` (list[dict]): List of dictionaries containing function parameters

- `func_names` (Optional[list[str]]): Optional list of function names

**Returns:** `list[Any]` - List of results from function executions

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

def multiply(a: int, b: int) -> int:
    """Multiply two numbers."""
    return a * b

tool = BaseTool(tools=[add, multiply])
results = tool.execute_multiple_functions_with_dict(
    [{"a": 1, "b": 2}, {"a": 3, "b": 4}], 
    ["add", "multiply"]
)
print(results)  # [3, 12]
```

### `validate_function_schema`

**Description:** Validate the schema of a function for different AI providers.

**Arguments:**

- `schema` (Optional[Union[List[Dict[str, Any]], Dict[str, Any]]]): Function schema(s) to validate

- `provider` (str): Target provider format ("openai", "anthropic", "generic", "auto")

**Returns:** `bool` - True if schema(s) are valid, False otherwise

**Example:**
```python
from swarms.tools.base_tool import BaseTool

openai_schema = {
    "type": "function",
    "function": {
        "name": "add_numbers",
        "description": "Add two numbers",
        "parameters": {
            "type": "object",
            "properties": {
                "a": {"type": "integer"},
                "b": {"type": "integer"}
            },
            "required": ["a", "b"]
        }
    }
}

tool = BaseTool()
is_valid = tool.validate_function_schema(openai_schema, "openai")
print(is_valid)  # True
```

### `get_schema_provider_format`

**Description:** Get the detected provider format of a schema.

**Arguments:**

- `schema` (Dict[str, Any]): Function schema dictionary

**Returns:** `str` - Provider format ("openai", "anthropic", "generic", "unknown")

**Example:**
```python
from swarms.tools.base_tool import BaseTool

openai_schema = {
    "type": "function",
    "function": {"name": "test", "description": "Test function"}
}

tool = BaseTool()
provider = tool.get_schema_provider_format(openai_schema)
print(provider)  # "openai"
```

### `convert_schema_between_providers`

**Description:** Convert a function schema between different provider formats.

**Arguments:**

- `schema` (Dict[str, Any]): Source function schema

- `target_provider` (str): Target provider format ("openai", "anthropic", "generic")

**Returns:** `Dict[str, Any]` - Converted schema

**Example:**
```python
from swarms.tools.base_tool import BaseTool

openai_schema = {
    "type": "function",
    "function": {
        "name": "test_func",
        "description": "Test function",
        "parameters": {"type": "object", "properties": {}}
    }
}

tool = BaseTool()
anthropic_schema = tool.convert_schema_between_providers(openai_schema, "anthropic")
print(anthropic_schema)
# Output: {"name": "test_func", "description": "Test function", "input_schema": {...}}
```

### `execute_function_calls_from_api_response`

**Description:** Automatically detect and execute function calls from OpenAI or Anthropic API responses.

**Arguments:**

- `api_response` (Union[Dict[str, Any], str, List[Any]]): The API response containing function calls

- `sequential` (bool): If True, execute functions sequentially. If False, execute in parallel

- `max_workers` (int): Maximum number of worker threads for parallel execution

- `return_as_string` (bool): If True, return results as formatted strings

**Returns:** `Union[List[Any], List[str]]` - List of results from executed functions

**Example:**
```python
from swarms.tools.base_tool import BaseTool

def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"Weather in {city}: Sunny, 25°C"

# Simulated OpenAI API response
openai_response = {
    "choices": [{
        "message": {
            "tool_calls": [{
                "type": "function",
                "function": {
                    "name": "get_weather",
                    "arguments": '{"city": "New York"}'
                },
                "id": "call_123"
            }]
        }
    }]
}

tool = BaseTool(tools=[get_weather])
results = tool.execute_function_calls_from_api_response(openai_response)
print(results)  # ["Function 'get_weather' result:\nWeather in New York: Sunny, 25°C"]
```

### `detect_api_response_format`

**Description:** Detect the format of an API response.

**Arguments:**

- `response` (Union[Dict[str, Any], str, BaseModel]): API response to analyze

**Returns:** `str` - Detected format ("openai", "anthropic", "generic", "unknown")

**Example:**
```python
from swarms.tools.base_tool import BaseTool

openai_response = {
    "choices": [{"message": {"tool_calls": []}}]
}

anthropic_response = {
    "content": [{"type": "tool_use", "name": "test", "input": {}}]
}

tool = BaseTool()
print(tool.detect_api_response_format(openai_response))  # "openai"
print(tool.detect_api_response_format(anthropic_response))  # "anthropic"
```

---

## Exception Classes

The BaseTool class defines several custom exception classes for better error handling:

- `BaseToolError`: Base exception class for all BaseTool related errors

- `ToolValidationError`: Raised when tool validation fails

- `ToolExecutionError`: Raised when tool execution fails

- `ToolNotFoundError`: Raised when a requested tool is not found

- `FunctionSchemaError`: Raised when function schema conversion fails

- `ToolDocumentationError`: Raised when tool documentation is missing or invalid

- `ToolTypeHintError`: Raised when tool type hints are missing or invalid

## Usage Tips

1. **Always provide documentation and type hints** for your functions when using BaseTool
2. **Use verbose=True** during development for detailed logging
3. **Set up function_map** for efficient tool execution by name
4. **Validate schemas** before using them with different AI providers
5. **Use parallel execution** for better performance when executing multiple functions
6. **Handle exceptions** appropriately using the custom exception classes 

--------------------------------------------------

# File: swarms/tools/build_tool.md

# Swarms Tool Documentation

A tool is a Python function designed to perform specific tasks with clear type annotations and comprehensive docstrings. Below are examples of financial tools to help you get started.

## Rules

To create a tool in the Swarms environment, follow these rules:

1. **Function Definition**: 
   - The tool must be defined as a Python function.
   - The function should perform a specific task and be named appropriately.

2. **Type Annotations**: 
   - All arguments and the return value must have type annotations.
   - Both input and output types must be strings (`str`).

3. **Docstrings**: 
   - Each function must include a comprehensive docstring that adheres to PEP 257 standards. The docstring should explain:
     - The purpose of the function.
     - Arguments: names, types, and descriptions.
     - Return value: type and description.
     - Potential exceptions that the function may raise.

4. **Input and Output Types**:
   - The function's input must be a string.
   - The function's output must be a string.

## Example Financial Tools

### Example 1: Fetch Stock Price from Yahoo Finance

```python
import yfinance as yf

def get_stock_price(symbol: str) -> str:
    """
    Fetches the current stock price from Yahoo Finance.

    Args:
        symbol (str): The stock symbol (e.g., "AAPL", "TSLA", "NVDA").

    Returns:
        str: A formatted string containing the current stock price and basic information.

    Raises:
        ValueError: If the stock symbol is invalid or data cannot be retrieved.
        Exception: If there is an error with the API request.
    """
    try:
        # Remove any whitespace and convert to uppercase
        symbol = symbol.strip().upper()
        
        if not symbol:
            raise ValueError("Stock symbol cannot be empty.")
        
        # Fetch stock data
        stock = yf.Ticker(symbol)
        info = stock.info
        
        if not info or 'regularMarketPrice' not in info:
            raise ValueError(f"Unable to fetch data for symbol: {symbol}")
        
        current_price = info.get('regularMarketPrice', 'N/A')
        previous_close = info.get('regularMarketPreviousClose', 'N/A')
        market_cap = info.get('marketCap', 'N/A')
        company_name = info.get('longName', symbol)
        
        # Format market cap for readability
        if isinstance(market_cap, (int, float)) and market_cap > 0:
            if market_cap >= 1e12:
                market_cap_str = f"${market_cap/1e12:.2f}T"
            elif market_cap >= 1e9:
                market_cap_str = f"${market_cap/1e9:.2f}B"
            elif market_cap >= 1e6:
                market_cap_str = f"${market_cap/1e6:.2f}M"
            else:
                market_cap_str = f"${market_cap:,.0f}"
        else:
            market_cap_str = "N/A"
        
        # Calculate price change
        if isinstance(current_price, (int, float)) and isinstance(previous_close, (int, float)):
            price_change = current_price - previous_close
            price_change_percent = (price_change / previous_close) * 100
            change_str = f"{price_change:+.2f} ({price_change_percent:+.2f}%)"
        else:
            change_str = "N/A"
        
        result = f"""
Stock: {company_name} ({symbol})
Current Price: ${current_price}
Previous Close: ${previous_close}
Change: {change_str}
Market Cap: {market_cap_str}
        """.strip()
        
        return result
        
    except ValueError as e:
        print(f"Value Error: {e}")
        raise
    except Exception as e:
        print(f"Error fetching stock data: {e}")
        raise
```

### Example 2: Fetch Cryptocurrency Price from CoinGecko

```python
import requests

def get_crypto_price(coin_id: str) -> str:
    """
    Fetches the current cryptocurrency price from CoinGecko API.

    Args:
        coin_id (str): The cryptocurrency ID (e.g., "bitcoin", "ethereum", "cardano").

    Returns:
        str: A formatted string containing the current crypto price and market data.

    Raises:
        ValueError: If the coin ID is invalid or data cannot be retrieved.
        requests.exceptions.RequestException: If there is an error with the API request.
    """
    try:
        # Remove any whitespace and convert to lowercase
        coin_id = coin_id.strip().lower()
        
        if not coin_id:
            raise ValueError("Coin ID cannot be empty.")
        
        url = f"https://api.coingecko.com/api/v3/simple/price"
        params = {
            "ids": coin_id,
            "vs_currencies": "usd",
            "include_market_cap": "true",
            "include_24hr_vol": "true",
            "include_24hr_change": "true",
            "include_last_updated_at": "true"
        }
        
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()
        
        if coin_id not in data:
            raise ValueError(f"Coin ID '{coin_id}' not found. Please check the spelling.")
        
        coin_data = data[coin_id]
        
        if not coin_data:
            raise ValueError(f"No data available for coin ID: {coin_id}")
        
        usd_price = coin_data.get('usd', 'N/A')
        market_cap = coin_data.get('usd_market_cap', 'N/A')
        volume_24h = coin_data.get('usd_24h_vol', 'N/A')
        change_24h = coin_data.get('usd_24h_change', 'N/A')
        last_updated = coin_data.get('last_updated_at', 'N/A')
        
        # Format large numbers for readability
        def format_number(value):
            if isinstance(value, (int, float)) and value > 0:
                if value >= 1e12:
                    return f"${value/1e12:.2f}T"
                elif value >= 1e9:
                    return f"${value/1e9:.2f}B"
                elif value >= 1e6:
                    return f"${value/1e6:.2f}M"
                elif value >= 1e3:
                    return f"${value/1e3:.2f}K"
                else:
                    return f"${value:,.2f}"
            return "N/A"
        
        # Format the result
        result = f"""
Cryptocurrency: {coin_id.title()}
Current Price: ${usd_price:,.8f}" if isinstance(usd_price, (int, float)) else f"Current Price: {usd_price}
Market Cap: {format_number(market_cap)}
24h Volume: {format_number(volume_24h)}
24h Change: {change_24h:+.2f}%" if isinstance(change_24h, (int, float)) else f"24h Change: {change_24h}
Last Updated: {last_updated}
        """.strip()
        
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"Request Error: {e}")
        raise
    except ValueError as e:
        print(f"Value Error: {e}")
        raise
    except Exception as e:
        print(f"Error fetching crypto data: {e}")
        raise
```

### Example 3: Calculate Portfolio Performance

```python
def calculate_portfolio_performance(initial_investment_str: str, current_value_str: str, time_period_str: str) -> str:
    """
    Calculates portfolio performance metrics including return percentage and annualized return.

    Args:
        initial_investment_str (str): The initial investment amount as a string.
        current_value_str (str): The current portfolio value as a string.
        time_period_str (str): The time period in years as a string.

    Returns:
        str: A formatted string containing portfolio performance metrics.

    Raises:
        ValueError: If any of the inputs cannot be converted to the appropriate type or are negative.
    """
    try:
        initial_investment = float(initial_investment_str)
        current_value = float(current_value_str)
        time_period = float(time_period_str)
        
        if initial_investment <= 0 or current_value < 0 or time_period <= 0:
            raise ValueError("Initial investment and time period must be positive, current value must be non-negative.")
        
        # Calculate total return
        total_return = current_value - initial_investment
        total_return_percentage = (total_return / initial_investment) * 100
        
        # Calculate annualized return
        if time_period > 0:
            annualized_return = ((current_value / initial_investment) ** (1 / time_period) - 1) * 100
        else:
            annualized_return = 0
        
        # Determine performance status
        if total_return > 0:
            status = "Profitable"
        elif total_return < 0:
            status = "Loss"
        else:
            status = "Break-even"
        
        result = f"""
Portfolio Performance Analysis:
Initial Investment: ${initial_investment:,.2f}
Current Value: ${current_value:,.2f}
Time Period: {time_period:.1f} years

Total Return: ${total_return:+,.2f} ({total_return_percentage:+.2f}%)
Annualized Return: {annualized_return:+.2f}%
Status: {status}
        """.strip()
        
        return result
        
    except ValueError as e:
        print(f"Value Error: {e}")
        raise
    except Exception as e:
        print(f"Error calculating portfolio performance: {e}")
        raise
```

### Example 4: Calculate Compound Interest

```python
def calculate_compound_interest(principal_str: str, rate_str: str, time_str: str, compounding_frequency_str: str) -> str:
    """
    Calculates compound interest for investment planning.

    Args:
        principal_str (str): The initial investment amount as a string.
        rate_str (str): The annual interest rate (as decimal) as a string.
        time_str (str): The investment time period in years as a string.
        compounding_frequency_str (str): The number of times interest is compounded per year as a string.

    Returns:
        str: A formatted string containing the compound interest calculation results.

    Raises:
        ValueError: If any of the inputs cannot be converted to the appropriate type or are negative.
    """
    try:
        principal = float(principal_str)
        rate = float(rate_str)
        time = float(time_str)
        n = int(compounding_frequency_str)
        
        if principal <= 0 or rate < 0 or time <= 0 or n <= 0:
            raise ValueError("Principal, time, and compounding frequency must be positive. Rate must be non-negative.")
        
        # Calculate compound interest
        amount = principal * (1 + rate / n) ** (n * time)
        interest_earned = amount - principal
        
        # Calculate effective annual rate
        effective_rate = ((1 + rate / n) ** n - 1) * 100
        
        result = f"""
Compound Interest Calculation:
Principal: ${principal:,.2f}
Annual Rate: {rate*100:.2f}%
Time Period: {time:.1f} years
Compounding Frequency: {n} times per year

Final Amount: ${amount:,.2f}
Interest Earned: ${interest_earned:,.2f}
Effective Annual Rate: {effective_rate:.2f}%
        """.strip()
        
        return result
        
    except ValueError as e:
        print(f"Value Error: {e}")
        raise
    except Exception as e:
        print(f"Error calculating compound interest: {e}")
        raise
```

## Integrating Tools into an Agent

To integrate tools into an agent, simply pass callable functions with proper type annotations and documentation into the agent class.

```python
from swarms import Agent

# Initialize the financial analysis agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=(
        "You are a professional financial analyst agent. Use the provided tools to "
        "analyze stocks, cryptocurrencies, and investment performance. Provide "
        "clear, accurate financial insights and recommendations. Always format "
        "responses in markdown for better readability."
    ),
    model_name="gpt-4o",
    max_loops=3,
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    dynamic_temperature_enabled=True,
    saved_state_path="financial_agent.json",
    tools=[get_stock_price, get_crypto_price, calculate_portfolio_performance],
    user_name="financial_analyst",
    retry_attempts=3,
    context_length=200000,
)

# Run the agent
response = agent("Analyze the current price of Apple stock and Bitcoin, then calculate the performance of a $10,000 investment in each over the past 2 years.")
print(response)
```

## Complete Financial Analysis Example

```python
import yfinance as yf
import requests
from swarms import Agent

def get_stock_price(symbol: str) -> str:
    """
    Fetches the current stock price from Yahoo Finance.

    Args:
        symbol (str): The stock symbol (e.g., "AAPL", "TSLA", "NVDA").

    Returns:
        str: A formatted string containing the current stock price and basic information.

    Raises:
        ValueError: If the stock symbol is invalid or data cannot be retrieved.
        Exception: If there is an error with the API request.
    """
    try:
        symbol = symbol.strip().upper()
        
        if not symbol:
            raise ValueError("Stock symbol cannot be empty.")
        
        stock = yf.Ticker(symbol)
        info = stock.info
        
        if not info or 'regularMarketPrice' not in info:
            raise ValueError(f"Unable to fetch data for symbol: {symbol}")
        
        current_price = info.get('regularMarketPrice', 'N/A')
        previous_close = info.get('regularMarketPreviousClose', 'N/A')
        market_cap = info.get('marketCap', 'N/A')
        company_name = info.get('longName', symbol)
        
        if isinstance(market_cap, (int, float)) and market_cap > 0:
            if market_cap >= 1e12:
                market_cap_str = f"${market_cap/1e12:.2f}T"
            elif market_cap >= 1e9:
                market_cap_str = f"${market_cap/1e9:.2f}B"
            elif market_cap >= 1e6:
                market_cap_str = f"${market_cap/1e6:.2f}M"
            else:
                market_cap_str = f"${market_cap:,.0f}"
        else:
            market_cap_str = "N/A"
        
        if isinstance(current_price, (int, float)) and isinstance(previous_close, (int, float)):
            price_change = current_price - previous_close
            price_change_percent = (price_change / previous_close) * 100
            change_str = f"{price_change:+.2f} ({price_change_percent:+.2f}%)"
        else:
            change_str = "N/A"
        
        result = f"""
Stock: {company_name} ({symbol})
Current Price: ${current_price}
Previous Close: ${previous_close}
Change: {change_str}
Market Cap: {market_cap_str}
        """.strip()
        
        return result
        
    except ValueError as e:
        print(f"Value Error: {e}")
        raise
    except Exception as e:
        print(f"Error fetching stock data: {e}")
        raise

def get_crypto_price(coin_id: str) -> str:
    """
    Fetches the current cryptocurrency price from CoinGecko API.

    Args:
        coin_id (str): The cryptocurrency ID (e.g., "bitcoin", "ethereum", "cardano").

    Returns:
        str: A formatted string containing the current crypto price and market data.

    Raises:
        ValueError: If the coin ID is invalid or data cannot be retrieved.
        requests.exceptions.RequestException: If there is an error with the API request.
    """
    try:
        coin_id = coin_id.strip().lower()
        
        if not coin_id:
            raise ValueError("Coin ID cannot be empty.")
        
        url = f"https://api.coingecko.com/api/v3/simple/price"
        params = {
            "ids": coin_id,
            "vs_currencies": "usd",
            "include_market_cap": "true",
            "include_24hr_vol": "true",
            "include_24hr_change": "true",
            "include_last_updated_at": "true"
        }
        
        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()
        
        if coin_id not in data:
            raise ValueError(f"Coin ID '{coin_id}' not found. Please check the spelling.")
        
        coin_data = data[coin_id]
        
        if not coin_data:
            raise ValueError(f"No data available for coin ID: {coin_id}")
        
        usd_price = coin_data.get('usd', 'N/A')
        market_cap = coin_data.get('usd_market_cap', 'N/A')
        volume_24h = coin_data.get('usd_24h_vol', 'N/A')
        change_24h = coin_data.get('usd_24h_change', 'N/A')
        last_updated = coin_data.get('last_updated_at', 'N/A')
        
        def format_number(value):
            if isinstance(value, (int, float)) and value > 0:
                if value >= 1e12:
                    return f"${value/1e12:.2f}T"
                elif value >= 1e9:
                    return f"${value/1e9:.2f}B"
                elif value >= 1e6:
                    return f"${value/1e6:.2f}M"
                elif value >= 1e3:
                    return f"${value/1e3:.2f}K"
                else:
                    return f"${value:,.2f}"
            return "N/A"
        
        result = f"""
Cryptocurrency: {coin_id.title()}
Current Price: ${usd_price:,.8f}" if isinstance(usd_price, (int, float)) else f"Current Price: {usd_price}
Market Cap: {format_number(market_cap)}
24h Volume: {format_number(volume_24h)}
24h Change: {change_24h:+.2f}%" if isinstance(change_24h, (int, float)) else f"24h Change: {change_24h}
Last Updated: {last_updated}
        """.strip()
        
        return result
        
    except requests.exceptions.RequestException as e:
        print(f"Request Error: {e}")
        raise
    except ValueError as e:
        print(f"Value Error: {e}")
        raise
    except Exception as e:
        print(f"Error fetching crypto data: {e}")
        raise

# Initialize the financial analysis agent
agent = Agent(
    agent_name="Financial-Analysis-Agent",
    system_prompt=(
        "You are a professional financial analyst agent specializing in stock and "
        "cryptocurrency analysis. Use the provided tools to fetch real-time market "
        "data and provide comprehensive financial insights. Always present data "
        "in a clear, professional format with actionable recommendations."
    ),
    model_name="gpt-4o",
    max_loops=3,
    autosave=True,
    dashboard=False,
    verbose=True,
    streaming_on=True,
    dynamic_temperature_enabled=True,
    saved_state_path="financial_agent.json",
    tools=[get_stock_price, get_crypto_price],
    user_name="financial_analyst",
    retry_attempts=3,
    context_length=200000,
)

# Run the agent
response = agent("What are the current prices and market data for Apple stock and Bitcoin? Provide a brief analysis of their performance.")
print(response)
```


--------------------------------------------------

# File: swarms/tools/main.md

# The Swarms Tool System: Functions, Pydantic BaseModels as Tools, and Radical Customization


This guide provides an in-depth look at the Swarms Tool System, focusing on its functions, the use of Pydantic BaseModels as tools, and the extensive customization options available. Aimed at developers, this documentation highlights how the Swarms framework works and offers detailed examples of creating and customizing tools and agents, specifically for accounting tasks.

The Swarms Tool System is a flexible and extensible component of the Swarms framework that allows for the creation, registration, and utilization of various tools. These tools can perform a wide range of tasks and are integrated into agents to provide specific functionalities. The system supports multiple ways to define tools, including using Pydantic BaseModels, functions, and dictionaries.

### Architecture

The architecture of the Swarms Tool System is designed to be highly modular. It consists of the following main components:

1. **Agents:** The primary entities that execute tasks.
2. **Tools:** Functions or classes that perform specific operations.
3. **Schemas:** Definitions of input and output data formats using Pydantic BaseModels.

### Key Concepts

#### Tools

Tools are the core functional units within the Swarms framework. They can be defined in various ways:

- **Pydantic BaseModels**: Tools can be defined using Pydantic BaseModels to ensure data validation and serialization.
- **Functions**: Tools can be simple or complex functions.
- **Dictionaries**: Tools can be represented as dictionaries for flexibility.

#### Agents

Agents utilize tools to perform tasks. They are configured with a set of tools and schemas, and they execute the tools based on the input they receive.

## Detailed Documentation

### Tool Definition

#### Using Pydantic BaseModels

Pydantic BaseModels provide a structured way to define tool inputs and outputs. They ensure data validation and serialization, making them ideal for complex data handling.

**Example:**

Define Pydantic BaseModels for accounting tasks:

```python
from pydantic import BaseModel

class CalculateTax(BaseModel):
    income: float

class GenerateInvoice(BaseModel):
    client_name: str
    amount: float
    date: str

class SummarizeExpenses(BaseModel):
    expenses: list[dict]
```

Define tool functions using these models:

```python
def calculate_tax(data: CalculateTax) -> dict:
    tax_rate = 0.3  # Example tax rate
    tax = data.income * tax_rate
    return {"income": data.income, "tax": tax}

def generate_invoice(data: GenerateInvoice) -> dict:
    invoice = {
        "client_name": data.client_name,
        "amount": data.amount,
        "date": data.date,
        "invoice_id": "INV12345"
    }
    return invoice

def summarize_expenses(data: SummarizeExpenses) -> dict:
    total_expenses = sum(expense['amount'] for expense in data.expenses)
    return {"total_expenses": total_expenses}
```

#### Using Functions Directly

Tools can also be defined directly as functions without using Pydantic models. This approach is suitable for simpler tasks where complex validation is not required.

**Example:**

```python
def basic_tax_calculation(income: float) -> dict:
    tax_rate = 0.25
    tax = income * tax_rate
    return {"income": income, "tax": tax}
```

#### Using Dictionaries

Tools can be represented as dictionaries, providing maximum flexibility. This method is useful when the tool's functionality is more dynamic or when integrating with external systems.

**Example:**

```python
basic_tool_schema = {
    "name": "basic_tax_tool",
    "description": "A basic tax calculation tool",
    "parameters": {
        "type": "object",
        "properties": {
            "income": {"type": "number", "description": "Income amount"}
        },
        "required": ["income"]
    }
}

def basic_tax_tool(income: float) -> dict:
    tax_rate = 0.2
    tax = income * tax_rate
    return {"income": income, "tax": tax}
```

### Tool Registration

Tools need to be registered with the agent for it to utilize them. This can be done by specifying the tools in the `tools` parameter during agent initialization.

**Example:**

```python
from swarms import Agent
from llama_hosted import llama3Hosted

# Define Pydantic BaseModels for accounting tasks
class CalculateTax(BaseModel):
    income: float

class GenerateInvoice(BaseModel):
    client_name: str
    amount: float
    date: str

class SummarizeExpenses(BaseModel):
    expenses: list[dict]

# Define tool functions using these models
def calculate_tax(data: CalculateTax) -> dict:
    tax_rate = 0.3
    tax = data.income * tax_rate
    return {"income": data.income, "tax": tax}

def generate_invoice(data: GenerateInvoice) -> dict:
    invoice = {
        "client_name": data.client_name,
        "amount": data.amount,
        "date": data.date,
        "invoice_id": "INV12345"
    }
    return invoice

def summarize_expenses(data: SummarizeExpenses) -> dict:
    total_expenses = sum(expense['amount'] for expense in data.expenses)
    return {"total_expenses": total_expenses}

# Function to generate a tool schema for demonstration purposes
def create_tool_schema():
    return {
        "name": "execute",
        "description": "Executes code on the user's machine",
        "parameters": {
            "type": "object",
            "properties": {
                "language": {
                    "type": "string",
                    "description": "Programming language",
                    "enum": ["python", "java"]
                },
                "code": {"type": "string", "description": "Code to execute"}
            },
            "required": ["language", "code"]
        }
    }

# Initialize the agent with the tools
agent = Agent(
    agent_name="Accounting Agent",
    system_prompt="This agent assists with various accounting tasks.",
    sop_list=["Provide accurate and timely accounting services."],
    llm=llama3Hosted(),
    max_loops="auto",
    interactive=True,
    verbose=True,
    tool_schema=BaseModel,
    list_base_models=[
        CalculateTax,
        GenerateInvoice,
        SummarizeExpenses
    ],
    output_type=str,
    metadata_output_type="json",
    function_calling_format_type="OpenAI",
    function_calling_type="json",
    tools=[
        calculate_tax,
        generate_invoice,
        summarize_expenses
    ],
    list_base_models_json=create_tool_schema(),
)
```

### Running the Agent

The agent can execute tasks using the `run` method. This method takes a prompt and determines the appropriate tool to use based on the input.

**Example:**

```python
# Example task: Calculate tax for an income
result = agent.run("Calculate the tax for an income of $50,000.")
print(f"Result: {result}")

# Example task: Generate an invoice
invoice_data = agent.run("Generate an invoice for John Doe for $1500 on 2024-06-01.")
print(f"Invoice Data: {invoice_data}")

# Example task: Summarize expenses
expenses = [
    {"amount": 200.0, "description": "Office supplies"},
    {"amount": 1500.0, "description": "Software licenses"},
    {"amount": 300.0, "description": "Travel expenses"}
]
summary = agent.run("Summarize these expenses: " + str(expenses))
print(f"Expenses Summary: {summary}")
```


### Customizing Tools

Custom tools can be created to extend the functionality of the Swarms framework. This can include integrating external APIs, performing complex calculations, or handling specialized data formats.

**Example: Custom Accounting Tool**

```python
from pydantic import BaseModel

class CustomAccountingTool(BaseModel):
    data: dict

def custom_accounting_tool(data: CustomAccountingTool) -> dict:
    # Custom logic for the accounting tool
    result = {
        "status": "success",
        "data_processed": len(data.data)
    }
    return result

# Register the custom tool with the agent
agent = Agent(
    agent_name="Accounting Agent",
    system_prompt="This agent assists with various accounting tasks.",
    sop_list=["Provide accurate and timely accounting services."],
    llm=llama3Hosted(),
    max_loops="auto",
    interactive=True,
    verbose=True,
    tool_schema=BaseModel,
    list_base_models=[
        CalculateTax,
        GenerateInvoice,
        SummarizeExpenses,
        CustomAccountingTool
    ],
    output_type=str,
    metadata_output_type="json",
    function_calling_format_type="OpenAI",
    function_calling_type="json",
    tools=[
        calculate_tax,
        generate_invoice,
        summarize_expenses,
        custom_accounting_tool
    ],
    list_base_models_json=create_tool_schema(),
)
```

### Advanced Customization

Advanced customization involves modifying the core components of the Swarms framework. This includes extending existing classes, adding new methods, or integrating third-party libraries.

**Example: Extending the Agent Class**

```python
from swarms import Agent

class AdvancedAccountingAgent(Agent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def custom_behavior(self):
        print("Executing custom behavior")

    def another_custom_method(self):
        print("Another

 custom method")

# Initialize the advanced agent
advanced_agent = AdvancedAccountingAgent(
    agent_name="Advanced Accounting Agent",
    system_prompt="This agent performs advanced accounting tasks.",
    sop_list=["Provide advanced accounting services."],
    llm=llama3Hosted(),
    max_loops="auto",
    interactive=True,
    verbose=True,
    tool_schema=BaseModel,
    list_base_models=[
        CalculateTax,
        GenerateInvoice,
        SummarizeExpenses,
        CustomAccountingTool
    ],
    output_type=str,
    metadata_output_type="json",
    function_calling_format_type="OpenAI",
    function_calling_type="json",
    tools=[
        calculate_tax,
        generate_invoice,
        summarize_expenses,
        custom_accounting_tool
    ],
    list_base_models_json=create_tool_schema(),
)

# Call custom methods
advanced_agent.custom_behavior()
advanced_agent.another_custom_method()
```

### Integrating External Libraries

You can integrate external libraries to extend the functionality of your tools. This is useful for adding new capabilities or leveraging existing libraries for complex tasks.

**Example: Integrating Pandas for Data Processing**

```python
import pandas as pd
from pydantic import BaseModel

class DataFrameTool(BaseModel):
    data: list[dict]

def process_data_frame(data: DataFrameTool) -> dict:
    df = pd.DataFrame(data.data)
    summary = df.describe().to_dict()
    return {"summary": summary}

# Register the tool with the agent
agent = Agent(
    agent_name="Data Processing Agent",
    system_prompt="This agent processes data frames.",
    sop_list=["Provide data processing services."],
    llm=llama3Hosted(),
    max_loops="auto",
    interactive=True,
    verbose=True,
    tool_schema=BaseModel,
    list_base_models=[DataFrameTool],
    output_type=str,
    metadata_output_type="json",
    function_calling_format_type="OpenAI",
    function_calling_type="json",
    tools=[process_data_frame],
    list_base_models_json=create_tool_schema(),
)

# Example task: Process a data frame
data = [
    {"col1": 1, "col2": 2},
    {"col1": 3, "col2": 4},
    {"col1": 5, "col2": 6}
]
result = agent.run("Process this data frame: " + str(data))
print(f"Data Frame Summary: {result}")
```

## Conclusion

The Swarms Tool System provides a robust and flexible framework for defining and utilizing tools within agents. By leveraging Pydantic BaseModels, functions, and dictionaries, developers can create highly customized tools to perform a wide range of tasks. The extensive customization options allow for the integration of external libraries and the extension of core components, making the Swarms framework suitable for diverse applications.

This guide has covered the fundamental concepts and provided detailed examples to help you get started with the Swarms Tool System. With this foundation, you can explore and implement advanced features to build powerful

--------------------------------------------------

# File: swarms/tools/mcp_client_call.md

# MCP Client Call Reference Documentation

This document provides a comprehensive reference for the MCP (Model Control Protocol) client call functions, including detailed parameter descriptions, return types, and usage examples.

## Table of Contents

- [aget_mcp_tools](#aget_mcp_tools)

- [get_mcp_tools_sync](#get_mcp_tools_sync)

- [get_tools_for_multiple_mcp_servers](#get_tools_for_multiple_mcp_servers)

- [execute_tool_call_simple](#execute_tool_call_simple)

## Function Reference

### aget_mcp_tools

Asynchronously fetches available MCP tools from the server with retry logic.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| server_path | Optional[str] | No | Path to the MCP server script |
| format | str | No | Format of the returned tools (default: "openai") |
| connection | Optional[MCPConnection] | No | MCP connection object |
| *args | Any | No | Additional positional arguments |
| **kwargs | Any | No | Additional keyword arguments |

#### Returns

- `List[Dict[str, Any]]`: List of available MCP tools in OpenAI format

#### Raises

- `MCPValidationError`: If server_path is invalid

- `MCPConnectionError`: If connection to server fails

#### Example

```python
import asyncio
from swarms.tools.mcp_client_call import aget_mcp_tools
from swarms.tools.mcp_connection import MCPConnection

async def main():
    # Using server path
    tools = await aget_mcp_tools(server_path="http://localhost:8000")
    
    # Using connection object
    connection = MCPConnection(
        host="localhost",
        port=8000,
        headers={"Authorization": "Bearer token"}
    )
    tools = await aget_mcp_tools(connection=connection)
    
    print(f"Found {len(tools)} tools")

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

### get_mcp_tools_sync

Synchronous version of get_mcp_tools that handles event loop management.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| server_path | Optional[str] | No | Path to the MCP server script |
| format | str | No | Format of the returned tools (default: "openai") |
| connection | Optional[MCPConnection] | No | MCP connection object |
| *args | Any | No | Additional positional arguments |
| **kwargs | Any | No | Additional keyword arguments |

#### Returns

- `List[Dict[str, Any]]`: List of available MCP tools in OpenAI format

#### Raises

- `MCPValidationError`: If server_path is invalid

- `MCPConnectionError`: If connection to server fails

- `MCPExecutionError`: If event loop management fails

#### Example

```python
from swarms.tools.mcp_client_call import get_mcp_tools_sync
from swarms.tools.mcp_connection import MCPConnection

# Using server path
tools = get_mcp_tools_sync(server_path="http://localhost:8000")

# Using connection object
connection = MCPConnection(
    host="localhost",
    port=8000,
    headers={"Authorization": "Bearer token"}
)
tools = get_mcp_tools_sync(connection=connection)

print(f"Found {len(tools)} tools")
```

### get_tools_for_multiple_mcp_servers

Get tools for multiple MCP servers concurrently using ThreadPoolExecutor.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| urls | List[str] | Yes | List of server URLs to fetch tools from |
| connections | List[MCPConnection] | No | Optional list of MCPConnection objects |
| format | str | No | Format to return tools in (default: "openai") |
| output_type | Literal["json", "dict", "str"] | No | Type of output format (default: "str") |
| max_workers | Optional[int] | No | Maximum number of worker threads |

#### Returns

- `List[Dict[str, Any]]`: Combined list of tools from all servers

#### Raises

- `MCPExecutionError`: If fetching tools from any server fails

#### Example

```python
from swarms.tools.mcp_client_call import get_tools_for_multiple_mcp_servers
from swarms.tools.mcp_connection import MCPConnection

# Define server URLs
urls = [
    "http://server1:8000",
    "http://server2:8000"
]

# Optional: Define connections
connections = [
    MCPConnection(host="server1", port=8000),
    MCPConnection(host="server2", port=8000)
]

# Get tools from all servers
tools = get_tools_for_multiple_mcp_servers(
    urls=urls,
    connections=connections,
    format="openai",
    output_type="dict",
    max_workers=4
)

print(f"Found {len(tools)} tools across all servers")
```

### execute_tool_call_simple

Execute a tool call using the MCP client.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| response | Any | No | Tool call response object |
| server_path | str | No | Path to the MCP server |
| connection | Optional[MCPConnection] | No | MCP connection object |
| output_type | Literal["json", "dict", "str", "formatted"] | No | Type of output format (default: "str") |
| *args | Any | No | Additional positional arguments |
| **kwargs | Any | No | Additional keyword arguments |

#### Returns

- `List[Dict[str, Any]]`: Result of the tool execution

#### Raises

- `MCPConnectionError`: If connection to server fails

- `MCPExecutionError`: If tool execution fails

#### Example
```python
import asyncio
from swarms.tools.mcp_client_call import execute_tool_call_simple
from swarms.tools.mcp_connection import MCPConnection

async def main():
    # Example tool call response
    response = {
        "name": "example_tool",
        "parameters": {"param1": "value1"}
    }
    
    # Using server path
    result = await execute_tool_call_simple(
        response=response,
        server_path="http://localhost:8000",
        output_type="json"
    )
    
    # Using connection object
    connection = MCPConnection(
        host="localhost",
        port=8000,
        headers={"Authorization": "Bearer token"}
    )
    result = await execute_tool_call_simple(
        response=response,
        connection=connection,
        output_type="dict"
    )
    
    print(f"Tool execution result: {result}")

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

## Error Handling

The MCP client functions use a retry mechanism with exponential backoff for failed requests. The following error types may be raised:

- `MCPValidationError`: Raised when input validation fails

- `MCPConnectionError`: Raised when connection to the MCP server fails

- `MCPExecutionError`: Raised when tool execution fails

## Best Practices

1. Always handle potential exceptions when using these functions
2. Use connection objects for authenticated requests
3. Consider using the async versions for better performance in async applications
4. Use appropriate output types based on your needs
5. When working with multiple servers, adjust max_workers based on your system's capabilities



--------------------------------------------------

# File: swarms/tools/tool_storage.md

# ToolStorage


The `ToolStorage` module provides a structured and efficient way to manage and utilize various tool functions. It is designed to store tool functions, manage settings, and ensure smooth registration and retrieval of tools. This module is particularly useful in applications that require dynamic management of a collection of functions, such as plugin systems, modular software, or any application where functions need to be registered and called dynamically.

## Class: ToolStorage

The `ToolStorage` class is the core component of the module. It provides functionalities to add, retrieve, and list tool functions as well as manage settings.

### Attributes

| Attribute  | Type               | Description                                                           |
|------------|--------------------|-----------------------------------------------------------------------|
| `verbose`  | `bool`             | A flag to enable verbose logging.                                      |
| `tools`    | `List[Callable]`   | A list of tool functions.                                              |
| `_tools`   | `Dict[str, Callable]` | A dictionary that stores the tools, where the key is the tool name and the value is the tool function. |
| `_settings`| `Dict[str, Any]`   | A dictionary that stores the settings, where the key is the setting name and the value is the setting value. |

### Methods

#### `__init__`

Initializes the `ToolStorage` instance.


| Parameter  | Type              | Default | Description                                                |
|------------|-------------------|---------|------------------------------------------------------------|
| `verbose`  | `bool`            | `None`  | A flag to enable verbose logging.                          |
| `tools`    | `List[Callable]`  | `None`  | A list of tool functions to initialize the storage with.   |
| `*args`    | `tuple`           | `None`  | Additional positional arguments.                           |
| `**kwargs` | `dict`            | `None`  | Additional keyword arguments.                              |

#### `add_tool`

Adds a tool to the storage.

| Parameter | Type     | Description                  |
|-----------|----------|------------------------------|
| `func`    | `Callable` | The tool function to be added. |

**Raises:**
- `ValueError`: If a tool with the same name already exists.

#### `get_tool`

Retrieves a tool by its name.

| Parameter | Type   | Description                   |
|-----------|--------|-------------------------------|
| `name`    | `str`  | The name of the tool to retrieve. |

**Returns:**
- `Callable`: The tool function.

**Raises:**
- `ValueError`: If no tool with the given name is found.

#### `set_setting`

Sets a setting in the storage.


| Parameter | Type   | Description              |
|-----------|--------|--------------------------|
| `key`     | `str`  | The key for the setting. |
| `value`   | `Any`  | The value for the setting. |

#### `get_setting`

Gets a setting from the storage.

| Parameter | Type   | Description              |
|-----------|--------|--------------------------|
| `key`     | `str`  | The key for the setting. |

**Returns:**
- `Any`: The value of the setting.

**Raises:**
- `KeyError`: If the setting is not found.

#### `list_tools`

Lists all registered tools.

**Returns:**
- `List[str]`: A list of tool names.

## Decorator: tool_registry

The `tool_registry` decorator registers a function as a tool in the storage.

| Parameter | Type           | Description                      |
|-----------|----------------|----------------------------------|
| `storage` | `ToolStorage`  | The storage instance to register the tool in. |

**Returns:**
- `Callable`: The decorator function.

## Usage Examples


### Full Example
```python
from swarms import ToolStorage, tool_registry

storage = ToolStorage()


# Example usage
@tool_registry(storage)
def example_tool(x: int, y: int) -> int:
    """
    Example tool function that adds two numbers.

    Args:
        x (int): The first number.
        y (int): The second number.

    Returns:
        int: The sum of the two numbers.
    """
    return x + y


# Query all the tools and get the example tool
print(storage.list_tools())  # Should print ['example_tool']
# print(storage.get_tool('example_tool'))  # Should print <function example_tool at 0x...>

# Find the tool by names and call it
print(storage.get_tool("example_tool"))  # Should print 5


# Test the storage and querying
if __name__ == "__main__":
    print(storage.list_tools())  # Should print ['example_tool']
    print(storage.get_tool("example_tool"))  # Should print 5
    storage.set_setting("example_setting", 42)
    print(storage.get_setting("example_setting"))  # Should print 42

```


### Basic Usage

#### Example 1: Initializing ToolStorage and Adding a Tool

```python
from swarms.tools.tool_registry import ToolStorage, tool_registry

# Initialize ToolStorage
storage = ToolStorage()

# Define a tool function
@tool_registry(storage)
def add_numbers(x: int, y: int) -> int:
    return x + y

# List tools
print(storage.list_tools())  # Output: ['add_numbers']

# Retrieve and use the tool
add_tool = storage.get_tool('add_numbers')
print(add_tool(5, 3))  # Output: 8
```

### Advanced Usage

#### Example 2: Managing Settings

```python
# Set a setting
storage.set_setting('max_retries', 5)

# Get a setting
max_retries = storage.get_setting('max_retries')
print(max_retries)  # Output: 5
```

### Error Handling

#### Example 3: Handling Errors in Tool Retrieval

```python
try:
    non_existent_tool = storage.get_tool('non_existent')
except ValueError as e:
    print(e)  # Output: No tool found with name: non_existent
```

#### Example 4: Handling Duplicate Tool Addition

```python
try:
    @tool_registry(storage)
    def add_numbers(x: int, y: int) -> int:
        return x + y
except ValueError as e:
    print(e)  # Output: Tool with name add_numbers already exists.
```

## Conclusion

The `ToolStorage` module provides a robust solution for managing tool functions and settings. Its design allows for easy registration, retrieval, and management of tools, making it a valuable asset in various applications requiring dynamic function handling. The inclusion of detailed logging ensures that the operations are transparent and any issues can be quickly identified and resolved.

--------------------------------------------------

# File: swarms/tools/tools_examples.md

# Swarms Tools Documentation

Swarms provides a comprehensive toolkit for integrating various types of tools into your AI agents. This guide covers all available tool options including callable functions, MCP servers, schemas, and more.

## Installation

```bash
pip install swarms
```

## Overview

Swarms provides a comprehensive suite of tool integration methods to enhance your AI agents' capabilities:

| Tool Type | Description |
|-----------|-------------|
| **Callable Functions** | Direct integration of Python functions with proper type hints and comprehensive docstrings for immediate tool functionality |
| **MCP Servers** | Model Context Protocol servers enabling distributed tool functionality across multiple services and environments |
| **Tool Schemas** | Structured tool definitions that provide standardized interfaces and validation for tool integration |
| **Tool Collections** | Pre-built tool packages offering ready-to-use functionality for common use cases |

---

## Method 1: Callable Functions

Callable functions are the simplest way to add tools to your Swarms agents. They are regular Python functions with type hints and comprehensive docstrings.

### Step 1: Define Your Tool Functions

Create functions with the following requirements:

- **Type hints** for all parameters and return values

- **Comprehensive docstrings** with Args, Returns, Raises, and Examples sections

- **Error handling** for robust operation

#### Example: Cryptocurrency Price Tools

```python
import json
import requests
from swarms import Agent


def get_coin_price(coin_id: str, vs_currency: str = "usd") -> str:
    """
    Get the current price of a specific cryptocurrency.

    Args:
        coin_id (str): The CoinGecko ID of the cryptocurrency 
                      Examples: 'bitcoin', 'ethereum', 'cardano'
        vs_currency (str, optional): The target currency for price conversion.
                                   Supported: 'usd', 'eur', 'gbp', 'jpy', etc.
                                   Defaults to "usd".

    Returns:
        str: JSON formatted string containing the coin's current price and market data
             including market cap, 24h volume, and price changes

    Raises:
        requests.RequestException: If the API request fails due to network issues
        ValueError: If coin_id is empty or invalid
        TimeoutError: If the request takes longer than 10 seconds

    Example:
        >>> result = get_coin_price("bitcoin", "usd")
        >>> print(result)
        {"bitcoin": {"usd": 45000, "usd_market_cap": 850000000000, ...}}
        
        >>> result = get_coin_price("ethereum", "eur")
        >>> print(result)
        {"ethereum": {"eur": 3200, "eur_market_cap": 384000000000, ...}}
    """
    try:
        # Validate input parameters
        if not coin_id or not coin_id.strip():
            raise ValueError("coin_id cannot be empty")
            
        url = "https://api.coingecko.com/api/v3/simple/price"
        params = {
            "ids": coin_id.lower().strip(),
            "vs_currencies": vs_currency.lower(),
            "include_market_cap": True,
            "include_24hr_vol": True,
            "include_24hr_change": True,
            "include_last_updated_at": True,
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()
        
        # Check if the coin was found
        if not data:
            return json.dumps({
                "error": f"Cryptocurrency '{coin_id}' not found. Please check the coin ID."
            })
            
        return json.dumps(data, indent=2)

    except requests.RequestException as e:
        return json.dumps({
            "error": f"Failed to fetch price for {coin_id}: {str(e)}",
            "suggestion": "Check your internet connection and try again"
        })
    except ValueError as e:
        return json.dumps({"error": str(e)})
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def get_top_cryptocurrencies(limit: int = 10, vs_currency: str = "usd") -> str:
    """
    Fetch the top cryptocurrencies by market capitalization.

    Args:
        limit (int, optional): Number of coins to retrieve. 
                              Range: 1-250 coins
                              Defaults to 10.
        vs_currency (str, optional): The target currency for price conversion.
                                   Supported: 'usd', 'eur', 'gbp', 'jpy', etc.
                                   Defaults to "usd".

    Returns:
        str: JSON formatted string containing top cryptocurrencies with detailed market data
             including: id, symbol, name, current_price, market_cap, market_cap_rank,
             total_volume, price_change_24h, price_change_7d, last_updated

    Raises:
        requests.RequestException: If the API request fails
        ValueError: If limit is not between 1 and 250

    Example:
        >>> result = get_top_cryptocurrencies(5, "usd")
        >>> print(result)
        [{"id": "bitcoin", "name": "Bitcoin", "current_price": 45000, ...}]
        
        >>> result = get_top_cryptocurrencies(limit=3, vs_currency="eur")
        >>> print(result)
        [{"id": "bitcoin", "name": "Bitcoin", "current_price": 38000, ...}]
    """
    try:
        # Validate parameters
        if not isinstance(limit, int) or not 1 <= limit <= 250:
            raise ValueError("Limit must be an integer between 1 and 250")

        url = "https://api.coingecko.com/api/v3/coins/markets"
        params = {
            "vs_currency": vs_currency.lower(),
            "order": "market_cap_desc",
            "per_page": limit,
            "page": 1,
            "sparkline": False,
            "price_change_percentage": "24h,7d",
        }

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()

        # Simplify and structure the data for better readability
        simplified_data = []
        for coin in data:
            simplified_data.append({
                "id": coin.get("id"),
                "symbol": coin.get("symbol", "").upper(),
                "name": coin.get("name"),
                "current_price": coin.get("current_price"),
                "market_cap": coin.get("market_cap"),
                "market_cap_rank": coin.get("market_cap_rank"),
                "total_volume": coin.get("total_volume"),
                "price_change_24h": round(coin.get("price_change_percentage_24h", 0), 2),
                "price_change_7d": round(coin.get("price_change_percentage_7d_in_currency", 0), 2),
                "last_updated": coin.get("last_updated"),
            })

        return json.dumps(simplified_data, indent=2)

    except (requests.RequestException, ValueError) as e:
        return json.dumps({
            "error": f"Failed to fetch top cryptocurrencies: {str(e)}"
        })
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})


def search_cryptocurrencies(query: str) -> str:
    """
    Search for cryptocurrencies by name or symbol.

    Args:
        query (str): The search term (coin name or symbol)
                    Examples: 'bitcoin', 'btc', 'ethereum', 'eth'
                    Case-insensitive search

    Returns:
        str: JSON formatted string containing search results with coin details
             including: id, name, symbol, market_cap_rank, thumb (icon URL)
             Limited to top 10 results for performance

    Raises:
        requests.RequestException: If the API request fails
        ValueError: If query is empty

    Example:
        >>> result = search_cryptocurrencies("ethereum")
        >>> print(result)
        {"coins": [{"id": "ethereum", "name": "Ethereum", "symbol": "eth", ...}]}
        
        >>> result = search_cryptocurrencies("btc")
        >>> print(result)
        {"coins": [{"id": "bitcoin", "name": "Bitcoin", "symbol": "btc", ...}]}
    """
    try:
        # Validate input
        if not query or not query.strip():
            raise ValueError("Search query cannot be empty")
            
        url = "https://api.coingecko.com/api/v3/search"
        params = {"query": query.strip()}

        response = requests.get(url, params=params, timeout=10)
        response.raise_for_status()

        data = response.json()

        # Extract and format the results
        coins = data.get("coins", [])[:10]  # Limit to top 10 results
        
        result = {
            "coins": coins,
            "query": query,
            "total_results": len(data.get("coins", [])),
            "showing": min(len(coins), 10)
        }

        return json.dumps(result, indent=2)

    except requests.RequestException as e:
        return json.dumps({
            "error": f'Failed to search for "{query}": {str(e)}'
        })
    except ValueError as e:
        return json.dumps({"error": str(e)})
    except Exception as e:
        return json.dumps({"error": f"Unexpected error: {str(e)}"})
```

### Step 2: Configure Your Agent

Create an agent with the following key parameters:

```python
# Initialize the agent with cryptocurrency tools
agent = Agent(
    agent_name="Financial-Analysis-Agent",                    # Unique identifier for your agent
    agent_description="Personal finance advisor agent with cryptocurrency market analysis capabilities",
    system_prompt="""You are a personal finance advisor agent with access to real-time 
    cryptocurrency data from CoinGecko. You can help users analyze market trends, check 
    coin prices, find trending cryptocurrencies, and search for specific coins. Always 
    provide accurate, up-to-date information and explain market data in an easy-to-understand way.""",
    max_loops=1,                                              # Number of reasoning loops
    max_tokens=4096,                                          # Maximum response length
    model_name="anthropic/claude-3-opus-20240229",          # LLM model to use
    dynamic_temperature_enabled=True,                         # Enable adaptive creativity
    output_type="all",                                        # Return complete response
    tools=[                                                   # List of callable functions
        get_coin_price,
        get_top_cryptocurrencies,
        search_cryptocurrencies,
    ],
)
```

### Step 3: Use Your Agent

```python
# Example usage with different queries
response = agent.run("What are the top 5 cryptocurrencies by market cap?")
print(response)

# Query with specific parameters
response = agent.run("Get the current price of Bitcoin and Ethereum in EUR")
print(response)

# Search functionality
response = agent.run("Search for cryptocurrencies related to 'cardano'")
print(response)
```

---

## Method 2: MCP (Model Context Protocol) Servers

MCP servers provide a standardized way to create distributed tool functionality. They're ideal for:

- **Reusable tools** across multiple agents

- **Complex tool logic** that needs isolation

- **Third-party tool integration**

- **Scalable architectures**

### Step 1: Create Your MCP Server

```python
from mcp.server.fastmcp import FastMCP
import requests

# Initialize the MCP server with configuration
mcp = FastMCP("OKXCryptoPrice")  # Server name for identification
mcp.settings.port = 8001         # Port for server communication
```

### Step 2: Define MCP Tools

Each MCP tool requires the `@mcp.tool` decorator with specific parameters:

```python
@mcp.tool(
    name="get_okx_crypto_price",                              # Tool identifier (must be unique)
    description="Get the current price and basic information for a given cryptocurrency from OKX exchange.",
)
def get_okx_crypto_price(symbol: str) -> str:
    """
    Get the current price and basic information for a given cryptocurrency using OKX API.

    Args:
        symbol (str): The cryptocurrency trading pair
                     Format: 'BASE-QUOTE' (e.g., 'BTC-USDT', 'ETH-USDT')
                     If only base currency provided, '-USDT' will be appended
                     Case-insensitive input

    Returns:
        str: A formatted string containing:
             - Current price in USDT
             - 24-hour price change percentage
             - Formatted for human readability

    Raises:
        requests.RequestException: If the OKX API request fails
        ValueError: If symbol format is invalid
        ConnectionError: If unable to connect to OKX servers

    Example:
        >>> get_okx_crypto_price('BTC-USDT')
        'Current price of BTC/USDT: $45,000.00\n24h Change: +2.34%'
        
        >>> get_okx_crypto_price('eth')  # Automatically converts to ETH-USDT
        'Current price of ETH/USDT: $3,200.50\n24h Change: -1.23%'
    """
    try:
        # Input validation and formatting
        if not symbol or not symbol.strip():
            return "Error: Please provide a valid trading pair (e.g., 'BTC-USDT')"

        # Normalize symbol format
        symbol = symbol.upper().strip()
        if not symbol.endswith("-USDT"):
            symbol = f"{symbol}-USDT"

        # OKX API endpoint for ticker information
        url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}"

        # Make the API request with timeout
        response = requests.get(url, timeout=10)
        response.raise_for_status()

        data = response.json()

        # Check API response status
        if data.get("code") != "0":
            return f"Error: {data.get('msg', 'Unknown error from OKX API')}"

        # Extract ticker data
        ticker_data = data.get("data", [{}])[0]
        if not ticker_data:
            return f"Error: Could not find data for {symbol}. Please verify the trading pair exists."

        # Parse numerical data
        price = float(ticker_data.get("last", 0))
        change_percent = float(ticker_data.get("change24h", 0)) * 100  # Convert to percentage

        # Format response
        base_currency = symbol.split("-")[0]
        change_symbol = "+" if change_percent >= 0 else ""
        
        return (f"Current price of {base_currency}/USDT: ${price:,.2f}\n"
                f"24h Change: {change_symbol}{change_percent:.2f}%")

    except requests.exceptions.Timeout:
        return "Error: Request timed out. OKX servers may be slow."
    except requests.exceptions.RequestException as e:
        return f"Error fetching OKX data: {str(e)}"
    except (ValueError, KeyError) as e:
        return f"Error parsing OKX response: {str(e)}"
    except Exception as e:
        return f"Unexpected error: {str(e)}"


@mcp.tool(
    name="get_okx_crypto_volume",                             # Second tool with different functionality
    description="Get the 24-hour trading volume for a given cryptocurrency from OKX exchange.",
)
def get_okx_crypto_volume(symbol: str) -> str:
    """
    Get the 24-hour trading volume for a given cryptocurrency using OKX API.

    Args:
        symbol (str): The cryptocurrency trading pair
                     Format: 'BASE-QUOTE' (e.g., 'BTC-USDT', 'ETH-USDT')
                     If only base currency provided, '-USDT' will be appended
                     Case-insensitive input

    Returns:
        str: A formatted string containing:
             - 24-hour trading volume in the base currency
             - Volume formatted with thousand separators
             - Currency symbol for clarity

    Raises:
        requests.RequestException: If the OKX API request fails
        ValueError: If symbol format is invalid

    Example:
        >>> get_okx_crypto_volume('BTC-USDT')
        '24h Trading Volume for BTC/USDT: 12,345.67 BTC'
        
        >>> get_okx_crypto_volume('ethereum')  # Converts to ETH-USDT
        '24h Trading Volume for ETH/USDT: 98,765.43 ETH'
    """
    try:
        # Input validation and formatting
        if not symbol or not symbol.strip():
            return "Error: Please provide a valid trading pair (e.g., 'BTC-USDT')"

        # Normalize symbol format
        symbol = symbol.upper().strip()
        if not symbol.endswith("-USDT"):
            symbol = f"{symbol}-USDT"

        # OKX API endpoint
        url = f"https://www.okx.com/api/v5/market/ticker?instId={symbol}"

        # Make API request
        response = requests.get(url, timeout=10)
        response.raise_for_status()

        data = response.json()

        # Validate API response
        if data.get("code") != "0":
            return f"Error: {data.get('msg', 'Unknown error from OKX API')}"

        ticker_data = data.get("data", [{}])[0]
        if not ticker_data:
            return f"Error: Could not find data for {symbol}. Please verify the trading pair."

        # Extract volume data
        volume_24h = float(ticker_data.get("vol24h", 0))
        base_currency = symbol.split("-")[0]
        
        return f"24h Trading Volume for {base_currency}/USDT: {volume_24h:,.2f} {base_currency}"

    except requests.exceptions.RequestException as e:
        return f"Error fetching OKX data: {str(e)}"
    except Exception as e:
        return f"Error: {str(e)}"
```

### Step 3: Start Your MCP Server

```python
if __name__ == "__main__":
    # Run the MCP server with SSE (Server-Sent Events) transport
    # Server will be available at http://localhost:8001/sse
    mcp.run(transport="sse")
```

### Step 4: Connect Agent to MCP Server

```python
from swarms import Agent

# Method 2: Using direct URL (simpler for development)
mcp_url = "http://0.0.0.0:8001/sse"

# Initialize agent with MCP tools
agent = Agent(
    agent_name="Financial-Analysis-Agent",                    # Agent identifier
    agent_description="Personal finance advisor with OKX exchange data access",
    system_prompt="""You are a financial analysis agent with access to real-time 
    cryptocurrency data from OKX exchange. You can check prices, analyze trading volumes, 
    and provide market insights. Always format numerical data clearly and explain 
    market movements in context.""",
    max_loops=1,                                              # Processing loops
    mcp_url=mcp_url,                                         # MCP server connection
    output_type="all",                                        # Complete response format
    # Note: tools are automatically loaded from MCP server
)
```

### Step 5: Use Your MCP-Enabled Agent

```python
# The agent automatically discovers and uses tools from the MCP server
response = agent.run(
    "Fetch the price for Bitcoin using the OKX exchange and also get its trading volume"
)
print(response)

# Multiple tool usage
response = agent.run(
    "Compare the prices of BTC, ETH, and ADA on OKX, and show their trading volumes"
)
print(response)
```

---

## Best Practices

### Function Design

| Practice | Description |
|----------|-------------|
| Type Hints | Always use type hints for all parameters and return values |
| Docstrings | Write comprehensive docstrings with Args, Returns, Raises, and Examples |
| Error Handling | Implement proper error handling with specific exception types |
| Input Validation | Validate input parameters before processing |
| Data Structure | Return structured data (preferably JSON) for consistency |

### MCP Server Development

| Practice | Description |
|----------|-------------|
| Tool Naming | Use descriptive tool names that clearly indicate functionality |
| Timeouts | Set appropriate timeouts for external API calls |
| Error Handling | Implement graceful error handling for network issues |
| Configuration | Use environment variables for sensitive configuration |
| Testing | Test tools independently before integration |

### Agent Configuration

| Practice | Description |
|----------|-------------|
| Loop Control | Choose appropriate max_loops based on task complexity |
| Token Management | Set reasonable token limits to control response length |
| System Prompts | Write clear system prompts that explain tool capabilities |
| Agent Naming | Use meaningful agent names for debugging and logging |
| Tool Integration | Consider tool combinations for comprehensive functionality |

### Performance Optimization

| Practice | Description |
|----------|-------------|
| Data Caching | Cache frequently requested data when possible |
| Connection Management | Use connection pooling for multiple API calls |
| Rate Control | Implement rate limiting to respect API constraints |
| Performance Monitoring | Monitor tool execution times and optimize slow operations |
| Async Operations | Use async operations for concurrent tool execution when supported |

---

## Troubleshooting

### Common Issues

#### Tool Not Found

```python
# Ensure function is in tools list
agent = Agent(
    # ... other config ...
    tools=[your_function_name],  # Function object, not string
)
```

#### MCP Connection Failed
```python
# Check server status and URL
import requests
response = requests.get("http://localhost:8001/health")  # Health check endpoint
```

#### Type Hint Errors

```python
# Always specify return types
def my_tool(param: str) -> str:  # Not just -> None
    return "result"
```

#### JSON Parsing Issues

```python
# Always return valid JSON strings
import json
return json.dumps({"result": data}, indent=2)
```

--------------------------------------------------

# File: swarms/ui/main.md

# Swarms Chat UI Documentation

The Swarms Chat interface provides a customizable, multi-agent chat experience using Gradio. It supports various specialized AI agents—from finance to healthcare and news analysis—by leveraging Swarms models.

---

## Table of Contents

1. [Installation](#installation)
2. [Quick Start](#quick-start)
3. [Parameters Overview](#parameters-overview)
4. [Specialized Agents](#specialized-agents)
    - [Finance Agents](#finance-agents)
    - [Healthcare Agents](#healthcare-agents)
    - [News & Research Agents](#news--research-agents)
5. [Swarms Integration Features](#swarms-integration-features)
6. [Usage Examples](#usage-examples)
    - [Finance Agent Example](#finance-agent-example)
    - [Healthcare Agent Example](#healthcare-agent-example)
    - [News Analysis Agent Example](#news-analysis-agent-example)
7. [Setup and Deployment](#setup-and-deployment)
8. [Best Practices](#best-practices)
9. [Notes](#notes)

---

## Installation

Make sure you have Python 3.7+ installed, then install the required packages using pip:

```bash
pip install gradio ai-gradio swarms
```

---

## Quick Start

Below is a minimal example to get the Swarms Chat interface up and running. Customize the agent, title, and description as needed.

```python
import gradio as gr
import ai_gradio

# Create and launch a Swarms Chat interface
gr.load(
    name='swarms:gpt-4-turbo',  # Model identifier (supports OpenAI and others)
    src=ai_gradio.registry,      # Source module for model configurations
    agent_name="Stock-Analysis-Agent",  # Example agent from Finance category
    title='Swarms Chat',
    description='Chat with an AI agent powered by Swarms'
).launch()
```

---

## Parameters Overview

When configuring your interface, consider the following parameters:

- **`name` (str):**  
  Model identifier (e.g., `'swarms:gpt-4-turbo'`) that specifies which Swarms model to use.

- **`src` (module):**  
  The source module (typically `ai_gradio.registry`) that contains model configurations.

- **`agent_name` (str):**  
  The name of the specialized agent you wish to use (e.g., "Stock-Analysis-Agent").

- **`title` (str):**  
  The title that appears at the top of the web interface.

- **`description` (str):**  
  A short summary describing the functionality of the chat interface.

---

## Specialized Agents

Swarms Chat supports multiple specialized agents designed for different domains. Below is an overview of available agent types.

### Finance Agents

1. **Stock Analysis Agent**
   - **Capabilities:**
     - Market analysis and stock recommendations.
     - Both technical and fundamental analysis.
     - Portfolio management suggestions.

2. **Tax Planning Agent**
   - **Capabilities:**
     - Tax optimization strategies.
     - Deduction analysis.
     - Guidance on tax law compliance.

### Healthcare Agents

1. **Medical Diagnosis Assistant**
   - **Capabilities:**
     - Analysis of symptoms.
     - Treatment recommendations.
     - Research using current medical literature.

2. **Healthcare Management Agent**
   - **Capabilities:**
     - Patient care coordination.
     - Organization of medical records.
     - Monitoring and tracking treatment plans.

### News & Research Agents

1. **News Analysis Agent**
   - **Capabilities:**
     - Real-time news aggregation.
     - Filtering news by topics.
     - Trend analysis and insights.

2. **Research Assistant**
   - **Capabilities:**
     - Analysis of academic papers.
     - Literature review support.
     - Guidance on research methodologies.

---

## Swarms Integration Features

### Core Capabilities

- **Multi-Agent Collaboration:** Multiple agents can be engaged simultaneously for a coordinated experience.
- **Real-Time Data Processing:** The interface processes and responds to queries in real time.
- **Natural Language Understanding:** Advanced NLP for context-aware and coherent responses.
- **Context-Aware Responses:** Responses are tailored based on conversation context.

### Technical Features

- **API Integration Support:** Easily connect with external APIs.
- **Custom Model Selection:** Choose the appropriate model for your specific task.
- **Concurrent Processing:** Supports multiple sessions concurrently.
- **Session Management:** Built-in session management ensures smooth user interactions.

---

## Usage Examples

Below are detailed examples for each type of specialized agent.

### Finance Agent Example

This example configures a chat interface for stock analysis:

```python
import gradio as gr
import ai_gradio

finance_interface = gr.load(
    name='swarms:gpt-4-turbo',
    src=ai_gradio.registry,
    agent_name="Stock-Analysis-Agent",
    title='Finance Assistant',
    description='Expert financial analysis and advice tailored to your investment needs.'
)
finance_interface.launch()
```

### Healthcare Agent Example

This example sets up a chat interface for healthcare assistance:

```python
import gradio as gr
import ai_gradio

healthcare_interface = gr.load(
    name='swarms:gpt-4-turbo',
    src=ai_gradio.registry,
    agent_name="Medical-Assistant-Agent",
    title='Healthcare Assistant',
    description='Access medical information, symptom analysis, and treatment recommendations.'
)
healthcare_interface.launch()
```

### News Analysis Agent Example

This example creates an interface for real-time news analysis:

```python
import gradio as gr
import ai_gradio

news_interface = gr.load(
    name='swarms:gpt-4-turbo',
    src=ai_gradio.registry,
    agent_name="News-Analysis-Agent",
    title='News Analyzer',
    description='Get real-time insights and analysis of trending news topics.'
)
news_interface.launch()
```

---

## Setup and Deployment

1. **Install Dependencies:**  
   Make sure all required packages are installed.

   ```bash
   pip install gradio ai-gradio swarms
   ```

2. **Import Modules:**  
   Import Gradio and ai_gradio in your Python script.

   ```python
   import gradio as gr
   import ai_gradio
   ```

3. **Configure and Launch the Interface:**  
   Configure your interface with the desired parameters and then launch.

   ```python
   interface = gr.load(
       name='swarms:gpt-4-turbo',
       src=ai_gradio.registry,
       agent_name="Your-Desired-Agent",
       title='Your Interface Title',
       description='A brief description of your interface.'
   )
   interface.launch()
   ```

4. **Deployment Options:**  
   - **Local:** By default, the interface runs at [http://localhost:7860](http://localhost:7860).
   - **Cloud Deployment:** Use cloud platforms like Heroku, AWS, or Google Cloud for remote access.
   - **Concurrent Sessions:** The system supports multiple users at the same time. Monitor resources and use proper scaling.

---

## Best Practices

1. **Select the Right Agent:**  
   Use the agent that best suits your specific domain needs.

2. **Model Configuration:**  
   Adjust model parameters based on your computational resources to balance performance and cost.

3. **Error Handling:**  
   Implement error handling to manage unexpected inputs or API failures gracefully.

4. **Resource Monitoring:**  
   Keep an eye on system performance, especially during high-concurrency sessions.

5. **Regular Updates:**  
   Keep your Swarms and Gradio packages updated to ensure compatibility with new features and security patches.

---

## Notes

- **Local vs. Remote:**  
  The interface runs locally by default but can be deployed on remote servers for wider accessibility.

- **Customization:**  
  You can configure custom model parameters and integrate additional APIs as needed.

- **Session Management:**  
  Built-in session handling ensures that users can interact concurrently without interfering with each other's sessions.

- **Error Handling & Rate Limiting:**  
  The system includes basic error handling and rate limiting to maintain performance under load.

---

This documentation is designed to provide clarity, reliability, and comprehensive guidance for integrating and using the Swarms Chat UI. For further customization or troubleshooting, consult the respective package documentation and community forums.

--------------------------------------------------

# File: swarms/utils/agent_loader.md

# AgentLoader Documentation

The `AgentLoader` is a comprehensive utility for creating Swarms agents from various file formats including Markdown, YAML, and CSV files. It provides a unified interface for loading agents with support for concurrent processing, configuration overrides, and automatic file type detection.

## Overview

The AgentLoader enables you to:

- Load agents from Markdown files 
- Load agents from YAML configuration files
- Load agents from CSV files
- Automatically detect file types and use appropriate loaders
- Process multiple files concurrently for improved performance
- Override default configurations with custom parameters
- Handle various agent configurations and settings

## Installation

The AgentLoader is included with the Swarms framework:

```python
from swarms.structs import AgentLoader
from swarms.utils import load_agent_from_markdown, load_agents_from_markdown
```

## Supported File Formats

### 1. Markdown Files (Claude Code Format)

The primary format uses YAML frontmatter with markdown content:

```markdown
---
name: FinanceAdvisor
description: Expert financial advisor for investment and budgeting guidance
model_name: claude-sonnet-4-20250514
temperature: 0.7
max_loops: 1
mcp_url: http://example.com/mcp  # optional
---

You are an expert financial advisor with deep knowledge in:
- Investment strategies and portfolio management
- Personal budgeting and financial planning
- Risk assessment and diversification
- Tax optimization strategies
- Retirement planning

Your approach:
- Provide clear, actionable financial advice
- Consider individual risk tolerance and goals
- Explain complex concepts in simple terms
- Always emphasize the importance of diversification
- Include relevant disclaimers about financial advice

When analyzing financial situations:
1. Assess current financial position
2. Identify short-term and long-term goals
3. Evaluate risk tolerance
4. Recommend appropriate strategies
5. Suggest specific action steps
```

**Schema Fields:**

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | ✅ Yes | - | Your agent name |
| `description` | string | ✅ Yes | - | Description of the agent's role and capabilities |
| `model_name` | string | ❌ No | "gpt-4.1" | Name of the model to use |
| `temperature` | float | ❌ No | 0.1 | Model temperature (0.0-2.0) |
| `max_loops` | integer | ❌ No | 1 | Maximum reasoning loops |
| `mcp_url` | string | ❌ No | None | MCP server URL if needed |
| `streaming_on` | boolean | ❌ No | False | Enable streaming output |

### 2. YAML Files

YAML configuration files for agent definitions:

```yaml
agents:
  - name: "ResearchAgent"
    description: "Research and analysis specialist"
    model_name: "gpt-4"
    temperature: 0.3
    max_loops: 2
    system_prompt: "You are a research specialist..."
```

### 3. CSV Files

CSV files with agent configurations:

```csv
name,description,model_name,temperature,max_loops
ResearchAgent,Research specialist,gpt-4,0.3,2
AnalysisAgent,Data analyst,claude-3,0.1,1
```

## Quick Start

### Loading a Single Agent

```python
from swarms.structs import AgentLoader

# Initialize the loader
loader = AgentLoader()

# Load agent from markdown file
agent = loader.load_agent_from_markdown("finance_advisor.md")

# Use the agent
response = agent.run(
    "I have $10,000 to invest. What's a good strategy for a beginner?"
)
```

### Loading Multiple Agents

```python
from swarms.structs import AgentLoader

loader = AgentLoader()

# Load agents from list of files with concurrent processing
agents = loader.load_agents_from_markdown([
    "market_researcher.md",
    "financial_analyst.md", 
    "risk_analyst.md"
], concurrent=True)  # Uses all CPU cores for faster loading

# Use agents in a workflow
from swarms.structs import SequentialWorkflow

workflow = SequentialWorkflow(
    agents=agents,
    max_loops=1
)

task = "Analyze the AI healthcare market for a $50M investment."
result = workflow.run(task)
```

### Automatic File Type Detection

```python
from swarms.structs import AgentLoader

loader = AgentLoader()

# Automatically detect file type and load appropriately
agents = loader.auto("agents.yaml")  # YAML file
agents = loader.auto("agents.csv")    # CSV file
agents = loader.auto("agents.md")     # Markdown file
```

## Class-Based Usage

### AgentLoader Class

For more advanced usage, use the `AgentLoader` class directly:

```python
from swarms.structs import AgentLoader

# Initialize loader
loader = AgentLoader()

# Load single agent
agent = loader.load_single_agent("path/to/agent.md")

# Load multiple agents with concurrent processing
agents = loader.load_multiple_agents(
    "./agents_directory/", 
    concurrent=True,      # Enable concurrent processing
    max_file_size_mb=10.0 # Limit file size for memory safety
)

# Parse markdown file without creating agent
config = loader.parse_markdown_file("path/to/agent.md")
print(config.name, config.description)
```

## Configuration Options

You can override default configuration when loading agents:

```python
agent = loader.load_agent_from_markdown(
    file_path="agent.md",
    max_loops=5,
    verbose=True,
    dashboard=True,
    autosave=False,
    context_length=200000,
    temperature=0.5
)
```

### Available Configuration Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `max_loops` | int | 1 | Maximum number of reasoning loops |
| `autosave` | bool | False | Enable automatic state saving |
| `dashboard` | bool | False | Enable dashboard monitoring |
| `verbose` | bool | False | Enable verbose logging |
| `dynamic_temperature_enabled` | bool | False | Enable dynamic temperature |
| `saved_state_path` | str | None | Path for saving agent state |
| `user_name` | str | "default_user" | User identifier |
| `retry_attempts` | int | 3 | Number of retry attempts |
| `context_length` | int | 100000 | Maximum context length |
| `return_step_meta` | bool | False | Return step metadata |
| `output_type` | str | "str" | Output format type |
| `auto_generate_prompt` | bool | False | Auto-generate prompts |
| `streaming_on` | bool | False | Enable streaming output |
| `mcp_url` | str | None | MCP server URL if needed |

## Advanced Features

### Concurrent Processing

The AgentLoader utilizes multiple CPU cores for concurrent agent loading:

```python
from swarms.structs import AgentLoader

loader = AgentLoader()

# Automatic concurrent processing for multiple files
agents = loader.load_agents_from_markdown([
    "agent1.md", "agent2.md", "agent3.md", "agent4.md"
])  # concurrent=True by default

# Manual control over concurrency
agents = loader.load_agents_from_markdown(
    "./agents_directory/",
    concurrent=True,        # Enable concurrent processing
    max_file_size_mb=5.0   # Limit file size for memory safety
)

# Disable concurrency for debugging or single files
agents = loader.load_agents_from_markdown(
    ["single_agent.md"],
    concurrent=False        # Sequential processing
)
```

### File Size Validation

```python
# Set maximum file size to prevent memory issues
agents = loader.load_agents_from_markdown(
    "./agents_directory/",
    max_file_size_mb=5.0  # Skip files larger than 5MB
)
```

### Multiple File Type Support

```python
from swarms.structs import AgentLoader

loader = AgentLoader()

# Load from different file types
yaml_agents = loader.load_agents_from_yaml("agents.yaml")
csv_agents = loader.load_agents_from_csv("agents.csv")
md_agents = loader.load_agents_from_markdown("agents.md")

# Load from multiple YAML files with different return types
yaml_files = ["agents1.yaml", "agents2.yaml"]
return_types = ["auto", "list"]
agents = loader.load_many_agents_from_yaml(yaml_files, return_types)
```

## Complete Examples

### Example 1: Finance Advisor Agent

Create a file `finance_advisor.md`:

```markdown
---
name: FinanceAdvisor
description: Expert financial advisor for investment and budgeting guidance
model_name: claude-sonnet-4-20250514
temperature: 0.7
max_loops: 1
---

You are an expert financial advisor with deep knowledge in:

- Investment strategies and portfolio management
- Personal budgeting and financial planning
- Risk assessment and diversification
- Tax optimization strategies
- Retirement planning

Your approach:

- Provide clear, actionable financial advice
- Consider individual risk tolerance and goals
- Explain complex concepts in simple terms
- Always emphasize the importance of diversification
- Include relevant disclaimers about financial advice

When analyzing financial situations:

1. Assess current financial position
2. Identify short-term and long-term goals
3. Evaluate risk tolerance
4. Recommend appropriate strategies
5. Suggest specific action steps
```

### Loading and Using the Agent

```python
from swarms.structs import AgentLoader

# Load the Finance Advisor agent
loader = AgentLoader()
agent = loader.load_agent_from_markdown("finance_advisor.md")

# Use the agent for financial advice
response = agent.run(
    "I have $10,000 to invest. What's a good strategy for a beginner?"
)
```

### Example 2: Multi-Agent Workflow

```python
from swarms.structs import AgentLoader, SequentialWorkflow

# Load multiple specialized agents
loader = AgentLoader()
agents = loader.load_agents_from_markdown([
    "market_researcher.md",
    "financial_analyst.md", 
    "risk_analyst.md"
], concurrent=True)

# Create a sequential workflow
workflow = SequentialWorkflow(
    agents=agents,
    max_loops=1
)

# Execute complex task across multiple agents
task = """
Analyze the AI healthcare market for a $50M investment opportunity.
Focus on market size, competition, financials, and risks.
"""

result = workflow.run(task)
```

### Example 3: Mixed File Types

```python
from swarms.structs import AgentLoader

loader = AgentLoader()

# Load agents from different file types
markdown_agents = loader.load_agents_from_markdown("./md_agents/")
yaml_agents = loader.load_agents_from_yaml("config.yaml")
csv_agents = loader.load_agents_from_csv("data.csv")

# Combine all agents
all_agents = markdown_agents + yaml_agents + csv_agents

print(f"Loaded {len(all_agents)} agents from various sources")
```

## Error Handling

The AgentLoader provides comprehensive error handling:

```python
from swarms.structs import AgentLoader

loader = AgentLoader()

try:
    # This will raise FileNotFoundError
    agent = loader.load_agent_from_markdown("nonexistent.md")
except FileNotFoundError as e:
    print(f"File not found: {e}")

try:
    # This will handle parsing errors gracefully
    agents = loader.load_multiple_agents("./invalid_directory/")
    print(f"Successfully loaded {len(agents)} agents")
except Exception as e:
    print(f"Error loading agents: {e}")
```

## Best Practices

1. **Consistent Naming**: Use clear, descriptive agent names
2. **Detailed Descriptions**: Provide comprehensive role descriptions
3. **Structured Content**: Use clear sections to define agent behavior
4. **Error Handling**: Always wrap agent loading in try-catch blocks
5. **Model Selection**: Choose appropriate models based on agent complexity
6. **Configuration**: Override defaults when specific behavior is needed
7. **File Organization**: Organize agents by domain or function
8. **Memory Management**: Use `max_file_size_mb` for large agent collections

## API Reference

### AgentLoader Class

```python
class AgentLoader:
    """
    Loader class for creating Agent objects from various file formats.
    
    This class provides methods to load agents from Markdown, YAML, and CSV files.
    """
    
    def __init__(self):
        """Initialize the AgentLoader instance."""
        pass
    
    def load_agents_from_markdown(
        self,
        file_paths: Union[str, List[str]],
        concurrent: bool = True,
        max_file_size_mb: float = 10.0,
        **kwargs
    ) -> List[Agent]:
        """
        Load multiple agents from one or more Markdown files.
        
        Args:
            file_paths: Path or list of paths to Markdown file(s)
            concurrent: Whether to load files concurrently
            max_file_size_mb: Maximum file size in MB to process
            **kwargs: Additional keyword arguments passed to the underlying loader
            
        Returns:
            A list of loaded Agent objects
        """
    
    def load_agent_from_markdown(
        self, 
        file_path: str, 
        **kwargs
    ) -> Agent:
        """
        Load a single agent from a Markdown file.
        
        Args:
            file_path: Path to the Markdown file containing the agent definition
            **kwargs: Additional keyword arguments passed to the underlying loader
            
        Returns:
            The loaded Agent object
        """
    
    def load_agents_from_yaml(
        self,
        yaml_file: str,
        return_type: ReturnTypes = "auto",
        **kwargs
    ) -> List[Agent]:
        """
        Load agents from a YAML file.
        
        Args:
            yaml_file: Path to the YAML file containing agent definitions
            return_type: The return type for the loader
            **kwargs: Additional keyword arguments passed to the underlying loader
            
        Returns:
            A list of loaded Agent objects
        """
    
    def load_agents_from_csv(
        self, 
        csv_file: str, 
        **kwargs
    ) -> List[Agent]:
        """
        Load agents from a CSV file.
        
        Args:
            csv_file: Path to the CSV file containing agent definitions
            **kwargs: Additional keyword arguments passed to the underlying loader
            
        Returns:
            A list of loaded Agent objects
        """
    
    def auto(
        self, 
        file_path: str, 
        *args, 
        **kwargs
    ):
        """
        Automatically load agents from a file based on its extension.
        
        Args:
            file_path: Path to the agent file (Markdown, YAML, or CSV)
            *args: Additional positional arguments passed to the underlying loader
            **kwargs: Additional keyword arguments passed to the underlying loader
            
        Returns:
            A list of loaded Agent objects
            
        Raises:
            ValueError: If the file type is not supported
        """
```

**Method Parameters and Return Types:**

| Method | Parameters | Type | Required | Default | Return Type | Description |
|--------|------------|------|----------|---------|-------------|-------------|
| `load_agents_from_markdown` | `file_paths` | Union[str, List[str]] | ✅ Yes | - | List[Agent] | File path(s) or directory |
| `load_agents_from_markdown` | `concurrent` | bool | ❌ No | True | List[Agent] | Enable concurrent processing |
| `load_agents_from_markdown` | `max_file_size_mb` | float | ❌ No | 10.0 | List[Agent] | Max file size in MB |
| `load_agents_from_markdown` | `**kwargs` | dict | ❌ No | {} | List[Agent] | Configuration overrides |
| `load_agent_from_markdown` | `file_path` | str | ✅ Yes | - | Agent | Path to markdown file |
| `load_agent_from_markdown` | `**kwargs` | dict | ❌ No | {} | Agent | Configuration overrides |
| `load_agents_from_yaml` | `yaml_file` | str | ✅ Yes | - | List[Agent] | Path to YAML file |
| `load_agents_from_yaml` | `return_type` | ReturnTypes | ❌ No | "auto" | List[Agent] | Return type for loader |
| `load_agents_from_yaml` | `**kwargs` | dict | ❌ No | {} | List[Agent] | Configuration overrides |
| `load_agents_from_csv` | `csv_file` | str | ✅ Yes | - | List[Agent] | Path to CSV file |
| `load_agents_from_csv` | `**kwargs` | dict | ❌ No | {} | List[Agent] | Configuration overrides |
| `auto` | `file_path` | str | ✅ Yes | - | List[Agent] | Path to agent file |
| `auto` | `*args` | tuple | ❌ No | () | List[Agent] | Positional arguments |
| `auto` | `**kwargs` | dict | ❌ No | {} | List[Agent] | Keyword arguments |

### Convenience Functions

```python
def load_agent_from_markdown(
    file_path: str, 
    **kwargs
) -> Agent:
    """
    Load a single agent from a markdown file using the Claude Code YAML frontmatter format.
    
    Args:
        file_path: Path to the markdown file containing YAML frontmatter
        **kwargs: Optional keyword arguments to override agent configuration
        
    Returns:
        Configured Agent instance loaded from the markdown file
    """

def load_agents_from_markdown(
    file_paths: Union[str, List[str]],
    concurrent: bool = True,
    max_file_size_mb: float = 10.0,
    **kwargs
) -> List[Agent]:
    """
    Load multiple agents from markdown files using the Claude Code YAML frontmatter format.
    
    Args:
        file_paths: Either a directory path containing markdown files or a list of markdown file paths
        concurrent: If True, enables concurrent processing for faster loading
        max_file_size_mb: Maximum file size (in MB) for each markdown file
        **kwargs: Optional keyword arguments to override agent configuration
        
    Returns:
        List of configured Agent instances loaded from the markdown files
    """
```

**Function Parameters:**

| Function | Parameter | Type | Required | Default | Description |
|----------|-----------|------|----------|---------|-------------|
| `load_agent_from_markdown` | `file_path` | str | ✅ Yes | - | Path to markdown file |
| `load_agent_from_markdown` | `**kwargs` | dict | ❌ No | {} | Configuration overrides |
| `load_agents_from_markdown` | `file_paths` | Union[str, List[str]] | ✅ Yes | - | File path(s) or directory |
| `load_agents_from_markdown` | `concurrent` | bool | ❌ No | True | Enable concurrent processing |
| `load_agents_from_markdown` | `max_file_size_mb` | float | ❌ No | 10.0 | Max file size in MB |
| `load_agents_from_markdown` | `**kwargs` | dict | ❌ No | {} | Configuration overrides |

### Configuration Model

```python
class MarkdownAgentConfig(BaseModel):
    """Configuration model for agents loaded from Claude Code markdown files."""
    
    name: Optional[str] = None
    description: Optional[str] = None
    model_name: Optional[str] = "gpt-4.1"
    temperature: Optional[float] = Field(default=0.1, ge=0.0, le=2.0)
    mcp_url: Optional[int] = None
    system_prompt: Optional[str] = None
    max_loops: Optional[int] = Field(default=1, ge=1)
    autosave: Optional[bool] = False
    dashboard: Optional[bool] = False
    verbose: Optional[bool] = False
    dynamic_temperature_enabled: Optional[bool] = False
    saved_state_path: Optional[str] = None
    user_name: Optional[str] = "default_user"
    retry_attempts: Optional[int] = Field(default=3, ge=1)
    context_length: Optional[int] = Field(default=100000, ge=1000)
    return_step_meta: Optional[bool] = False
    output_type: Optional[str] = "str"
    auto_generate_prompt: Optional[bool] = False
    streaming_on: Optional[bool] = False
```

**MarkdownAgentConfig Schema:**

| Field | Type | Required | Default | Validation | Description |
|-------|------|----------|---------|------------|-------------|
| `name` | Optional[str] | ❌ No | None | - | Agent name |
| `description` | Optional[str] | ❌ No | None | - | Agent description |
| `model_name` | Optional[str] | ❌ No | "gpt-4.1" | - | Model to use |
| `temperature` | Optional[float] | ❌ No | 0.1 | 0.0 ≤ x ≤ 2.0 | Model temperature |
| `mcp_url` | Optional[int] | ❌ No | None | - | MCP server URL |
| `system_prompt` | Optional[str] | ❌ No | None | Non-empty string | System prompt |
| `max_loops` | Optional[int] | ❌ No | 1 | ≥ 1 | Maximum reasoning loops |
| `autosave` | Optional[bool] | ❌ No | False | - | Enable auto-save |
| `dashboard` | Optional[bool] | ❌ No | False | - | Enable dashboard |
| `verbose` | Optional[bool] | ❌ No | False | - | Enable verbose logging |
| `dynamic_temperature_enabled` | Optional[bool] | ❌ No | False | - | Enable dynamic temperature |
| `saved_state_path` | Optional[str] | ❌ No | None | - | State save path |
| `user_name` | Optional[str] | ❌ No | "default_user" | - | User identifier |
| `retry_attempts` | Optional[int] | ❌ No | 3 | ≥ 1 | Retry attempts |
| `context_length` | Optional[int] | ❌ No | 100000 | ≥ 1000 | Context length |
| `return_step_meta` | Optional[bool] | ❌ No | False | - | Return step metadata |
| `output_type` | Optional[str] | ❌ No | "str" | - | Output format |
| `auto_generate_prompt` | Optional[bool] | ❌ No | False | - | Auto-generate prompts |
| `streaming_on` | Optional[bool] | ❌ No | False | - | Enable streaming |

## Examples Repository

Find complete working examples in the `examples/utils/agent_loader/` directory:

### Single Agent Example (`agent_loader_demo.py`)

```python
from swarms.utils import load_agent_from_markdown

agent = load_agent_from_markdown("finance_advisor.md")

agent.run(task="What were the best performing etfs in 2023")
```

### Multi-Agent Workflow Example (`multi_agents_loader_demo.py`)

```python
from swarms.utils import load_agents_from_markdown

agents = load_agents_from_markdown([
    "market_researcher.md",
    "financial_analyst.md", 
    "risk_analyst.md"
])

# Use agents in a workflow
from swarms.structs.sequential_workflow import SequentialWorkflow

workflow = SequentialWorkflow(
    agents=agents,
    max_loops=1
)

task = """
Analyze the AI healthcare market for a $50M investment opportunity.
Focus on market size, competition, financials, and risks.
"""

result = workflow.run(task)
```

### Sample Agent Definition (`finance_advisor.md`)

```markdown
---
name: FinanceAdvisor
description: Expert financial advisor for investment and budgeting guidance
model_name: claude-sonnet-4-20250514
temperature: 0.7
max_loops: 1
---

You are an expert financial advisor with deep knowledge in:

- Investment strategies and portfolio management
- Personal budgeting and financial planning
- Risk assessment and diversification
- Tax optimization strategies
- Retirement planning

Your approach:

- Provide clear, actionable financial advice
- Consider individual risk tolerance and goals
- Explain complex concepts in simple terms
- Always emphasize the importance of diversification
- Include relevant disclaimers about financial advice

When analyzing financial situations:

1. Assess current financial position
2. Identify short-term and long-term goals
3. Evaluate risk tolerance
4. Recommend appropriate strategies
5. Suggest specific action steps
```

## Performance Considerations

### Concurrent Processing

- **Default Behavior**: Uses `os.cpu_count() * 2` worker threads
- **Memory Management**: Automatically validates file sizes before processing
- **Timeout Handling**: 5-minute total timeout, 1-minute per agent timeout
- **Error Recovery**: Continues processing other files if individual files fail

### File Size Limits

- **Default Limit**: 10MB maximum file size
- **Configurable**: Adjustable via `max_file_size_mb` parameter
- **Memory Safety**: Prevents memory issues with large agent definitions

### Resource Optimization

```python
# For large numbers of agents, consider batch processing
loader = AgentLoader()

# Process in smaller batches
batch1 = loader.load_agents_from_markdown("./batch1/", concurrent=True)
batch2 = loader.load_agents_from_markdown("./batch2/", concurrent=True)

# Or limit concurrent workers for resource-constrained environments
agents = loader.load_agents_from_markdown(
    "./agents/",
    concurrent=True,
    max_file_size_mb=5.0  # Smaller files for faster processing
)
```

## Troubleshooting

### Common Issues

1. **File Not Found**: Ensure file paths are correct and files exist
2. **YAML Parsing Errors**: Check YAML frontmatter syntax in markdown files
3. **Memory Issues**: Reduce `max_file_size_mb` or process files in smaller batches
4. **Timeout Errors**: Check file sizes and network connectivity for remote files
5. **Configuration Errors**: Verify all required fields are present in agent definitions

### Debug Mode

```python
import logging
from swarms.structs import AgentLoader

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

loader = AgentLoader()

# Load with verbose output
agent = loader.load_agent_from_markdown(
    "agent.md",
    verbose=True
)
```

## Support

For questions and support:

- GitHub Issues: [https://github.com/kyegomez/swarms/issues](https://github.com/kyegomez/swarms/issues)
- Documentation: [https://docs.swarms.world](https://docs.swarms.world)
- Community: Join our Discord for real-time support

--------------------------------------------------

# File: swarms_cloud/add_agent.md

# Publishing an Agent to Agent Marketplace

## Requirements

- `swarms-cloud` package with `pip3 install -U swarms-cloud`

- Onboarding Process with `swarms-cloud onboarding`

- A Dockerfile `Dockerfile` containing the API of your agent code with FastAPI

- A YAML file for configuration `agent.yaml`

## Deployment YAML
```yaml

# Agent metadata and description
agent_name: "example-agent"  # The name of the agent
description: "This agent performs financial data analysis."  # A brief description of the agent's purpose
version: "v1.0"  # The version number of the agent
author: "Agent Creator Name"  # The name of the person or entity that created the agent
contact_email: "creator@example.com"  # The email address for contacting the agent's creator
tags:
  - "financial"  # Tag indicating the agent is related to finance
  - "data-analysis"  # Tag indicating the agent performs data analysis
  - "agent"  # Tag indicating this is an agent


# Deployment configuration
deployment_config:
  # Dockerfile configuration
  dockerfile_path: "./Dockerfile"  # The path to the Dockerfile for building the agent's image
  dockerfile_port: 8080  # The port number the agent will listen on
  
  # Resource allocation for the agent
  resources:
    cpu: 2  # Number of CPUs allocated to the agent
    memory: "2Gi"  # Memory allocation for the agent in gigabytes
    max_instances: 5  # Maximum number of instances to scale up to
    min_instances: 1  # Minimum number of instances to keep running
    timeout: 300s  # Request timeout setting in seconds

  # Autoscaling configuration
  autoscaling:
    max_concurrency: 80  # Maximum number of requests the agent can handle concurrently
    target_utilization: 0.6  # CPU utilization target for auto-scaling

  # Environment variables for the agent
  environment_variables:
    DATABASE_URL: "postgres://user:password@db-url"  # URL for the database connection
    API_KEY: "your-secret-api-key"  # API key for authentication
    LOG_LEVEL: "info"  # Log level for the agent

  # Secrets configuration
  secrets:
    SECRET_NAME_1: "projects/my-project/secrets/my-secret/versions/latest"  # Path to a secret
```

--------------------------------------------------

# File: swarms_cloud/agent_api.md

# Agent API

The Swarms.ai Agent API provides powerful endpoints for running individual AI agents and batch agent operations. This documentation explains how to use these endpoints for effective agent-based task execution.

## Getting Started

To use the Agent API, you'll need a Swarms.ai API key:

1. Go to [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)
2. Generate a new API key
3. Store your API key securely - it won't be shown again

```python
import os
import requests
from dotenv import load_dotenv

# Load API key from environment
load_dotenv()
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

# Configure headers with your API key
headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json"
}
```

## Individual Agent API

The Individual Agent API allows you to run a single agent with a specific configuration and task.

### Agent Configuration (`AgentSpec`)

The `AgentSpec` class defines the configuration for an individual agent.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agent_name` | string | Required | Unique name identifying the agent and its functionality |
| `description` | string | None | Detailed explanation of the agent's purpose and capabilities |
| `system_prompt` | string | None | Initial instructions guiding the agent's behavior and responses |
| `model_name` | string | "gpt-4o-mini" | The AI model used by the agent (e.g., gpt-4o, gpt-4o-mini, openai/o3-mini) |
| `auto_generate_prompt` | boolean | false | Whether the agent should automatically create prompts based on task requirements |
| `max_tokens` | integer | 8192 | Maximum number of tokens the agent can generate in its responses |
| `temperature` | float | 0.5 | Controls output randomness (lower values = more deterministic responses) |
| `role` | string | "worker" | The agent's role within a swarm, influencing its behavior and interactions |
| `max_loops` | integer | 1 | Maximum number of times the agent can repeat its task for iterative processing |
| `tools_dictionary` | array | None | Dictionary of tools the agent can use to complete its task |
| `mcp_url` | string | None | URL for the MCP server that the agent can connect to |

### Agent Completion

The `AgentCompletion` class combines an agent configuration with a specific task.

| Parameter | Type | Description |
|-----------|------|-------------|
| `agent_config` | AgentSpec | Configuration of the agent to be completed |
| `task` | string | The task to be completed by the agent |
| `history` | Optional[Union[Dict[Any, Any], List[Dict[str, str]]]] | The history of the agent's previous tasks and responses. Can be either a dictionary or a list of message objects. |

### Single Agent Endpoint

**Endpoint:** `POST /v1/agent/completions`

Run a single agent with a specific configuration and task.

#### Request

```python
def run_single_agent(agent_config, task):
    """
    Run a single agent with the AgentCompletion format.
    
    Args:
        agent_config: Dictionary containing agent configuration
        task: String describing the task for the agent
        
    Returns:
        Dictionary containing the agent's response
    """
    payload = {
        "agent_config": agent_config,
        "task": task
    }
    
    try:
        response = requests.post(
            f"{BASE_URL}/v1/agent/completions", 
            headers=headers, 
            json=payload
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error making request: {e}")
        return None
```

#### Example Usage

```python
agent_config = {
    "agent_name": "Research Analyst",
    "description": "An expert in analyzing and synthesizing research data",
    "system_prompt": (
        "You are a Research Analyst with expertise in data analysis and synthesis. "
        "Your role is to analyze provided information, identify key insights, "
        "and present findings in a clear, structured format. "
        "Focus on accuracy, clarity, and actionable recommendations."
    ),
    "model_name": "gpt-4o",
    "role": "worker",
    "max_loops": 2,
    "max_tokens": 8192,
    "temperature": 0.5,
    "auto_generate_prompt": False,
}

task = "Analyze the impact of artificial intelligence on healthcare delivery and provide a comprehensive report with key findings and recommendations."

result = run_single_agent(agent_config, task)
print(result)
```

#### Response Structure

```json
{
  "id": "agent-6a8b9c0d1e2f3g4h5i6j7k8l9m0n",
  "success": true,
  "name": "Research Analyst",
  "description": "An expert in analyzing and synthesizing research data",
  "temperature": 0.5,
  "outputs": {
    "content": "# Impact of Artificial Intelligence on Healthcare Delivery\n\n## Executive Summary\n...",
    "role": "assistant"
  },
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 3822,
    "total_tokens": 5072
  },
  "timestamp": "2025-05-10T18:35:29.421Z"
}
```

## Batch Agent API

The Batch Agent API allows you to run multiple agents in parallel, each with different configurations and tasks.

### Batch Agent Endpoint

**Endpoint:** `POST /v1/agent/batch/completions`

Run multiple agents with different configurations and tasks in a single API call.

#### Request

```python
def run_batch_agents(agent_completions):
    """
    Run multiple agents in batch.
    
    Args:
        agent_completions: List of dictionaries, each containing agent_config and task
        
    Returns:
        List of agent responses
    """
    try:
        response = requests.post(
            f"{BASE_URL}/v1/agent/batch/completions",
            headers=headers,
            json=agent_completions
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error making batch request: {e}")
        return None
```

#### Example Usage

```python
batch_completions = [
    {
        "agent_config": {
            "agent_name": "Research Analyst",
            "description": "An expert in analyzing research data",
            "system_prompt": "You are a Research Analyst...",
            "model_name": "gpt-4o",
            "max_loops": 2
        },
        "task": "Analyze the impact of AI on healthcare delivery."
    },
    {
        "agent_config": {
            "agent_name": "Market Analyst",
            "description": "An expert in market analysis",
            "system_prompt": "You are a Market Analyst...",
            "model_name": "gpt-4o",
            "max_loops": 1
        },
        "task": "Analyze the AI startup landscape in 2025."
    }
]

batch_results = run_batch_agents(batch_completions)
print(batch_results)
```

#### Response Structure

```json
[
  {
    "id": "agent-1a2b3c4d5e6f7g8h9i0j",
    "success": true,
    "name": "Research Analyst",
    "description": "An expert in analyzing research data",
    "temperature": 0.5,
    "outputs": {
      "content": "# Impact of AI on Healthcare Delivery\n...",
      "role": "assistant"
    },
    "usage": {
      "input_tokens": 1250,
      "output_tokens": 3822,
      "total_tokens": 5072
    },
    "timestamp": "2025-05-10T18:35:29.421Z"
  },
  {
    "id": "agent-9i8h7g6f5e4d3c2b1a0",
    "success": true,
    "name": "Market Analyst",
    "description": "An expert in market analysis",
    "temperature": 0.5,
    "outputs": {
      "content": "# AI Startup Landscape 2025\n...",
      "role": "assistant"
    },
    "usage": {
      "input_tokens": 980,
      "output_tokens": 4120,
      "total_tokens": 5100
    },
    "timestamp": "2025-05-10T18:35:31.842Z"
  }
]
```

## Error Handling

The API uses standard HTTP status codes to indicate success or failure:

| Status Code | Meaning |
|-------------|---------|
| 200 | Success |
| 400 | Bad Request - Check your request parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - Insufficient permissions |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Something went wrong on the server |

When an error occurs, the response body will contain additional information:

```json
{
  "detail": "Error message explaining what went wrong"
}
```

### Common Errors and Solutions

| Error | Possible Solution |
|-------|-------------------|
| "Invalid API Key" | Verify your API key is correct and properly included in the request headers |
| "Rate limit exceeded" | Reduce the number of requests or contact support to increase your rate limit |
| "Invalid agent configuration" | Check your agent_config parameters for any missing or invalid values |
| "Failed to create agent" | Ensure your system_prompt and model_name are valid |
| "Insufficient credits" | Add credits to your account at https://swarms.world/platform/account |

## Advanced Usage

### Setting Dynamic Temperature

The agent can dynamically adjust its temperature for optimal outputs:

```python
agent_config = {
    # Other config options...
    "temperature": 0.7,
    "dynamic_temperature_enabled": True
}
```

### Using Agent Tools

Agents can utilize various tools to enhance their capabilities:

```python
agent_config = {
    # Other config options...
    "tools_dictionary": [
        {
            "name": "web_search",
            "description": "Search the web for information",
            "parameters": {
                "query": "string"
            }
        },
        {
            "name": "calculator",
            "description": "Perform mathematical calculations",
            "parameters": {
                "expression": "string"
            }
        }
    ]
}
```

## Best Practices

!!! tip "API Key Security"
    Store API keys in environment variables or secure vaults, never in code repositories.
    ```python
    # DON'T do this
    api_key = "sk-123456789abcdef"
    
    # DO this instead
    import os
    from dotenv import load_dotenv
    load_dotenv()
    api_key = os.getenv("SWARMS_API_KEY")
    ```

!!! info "Agent Naming Conventions"
    Use a consistent naming pattern for your agents to make your code more maintainable.
    ```python
    # Good naming convention
    agent_configs = {
        "market_analyst": {...},
        "research_specialist": {...},
        "code_reviewer": {...}
    }
    ```

!!! success "Crafting Effective System Prompts"
    A well-crafted system prompt acts as your agent's personality and instruction set.
    
    === "Basic Prompt"
        ```
        You are a research analyst. Analyze the data and provide insights.
        ```
    
    === "Enhanced Prompt"
        ```
        You are a Research Analyst with 15+ years of experience in biotech market analysis.
        
        Your task is to:
        1. Analyze the provided market data methodically
        2. Identify key trends and emerging patterns
        3. Highlight potential investment opportunities
        4. Assess risks and regulatory considerations
        5. Provide actionable recommendations supported by the data
        
        Format your response as a professional report with clear sections,
        focusing on data-driven insights rather than generalities.
        ```

!!! warning "Token Management"
    Manage your token usage carefully to control costs.
    
    - Higher token limits provide more complete responses but increase costs
    - Consider using different models based on task complexity
    - For gpt-4o models, typical settings:
        - Simple tasks: 2048 tokens (lower cost)
        - Medium complexity: 4096 tokens (balanced)
        - Complex analysis: 8192+ tokens (higher cost, more detail)

!!! danger "Error Handling"
    Implement comprehensive error handling to make your application resilient.
    
    ```python
    try:
        response = requests.post(
            f"{BASE_URL}/v1/agent/completions",
            headers=headers,
            json=payload,
            timeout=30  # Add timeout to prevent hanging requests
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 429:
            # Implement exponential backoff for rate limiting
            retry_after = int(e.response.headers.get('Retry-After', 5))
            time.sleep(retry_after)
            return run_agent(payload)  # Retry the request
        elif e.response.status_code == 401:
            logger.error("Authentication failed. Check your API key.")
        else:
            logger.error(f"HTTP Error: {e.response.status_code} - {e.response.text}")
        return {"error": e.response.text}
    except requests.exceptions.Timeout:
        logger.error("Request timed out. The server might be busy.")
        return {"error": "Request timed out"}
    except requests.exceptions.RequestException as e:
        logger.error(f"Request Error: {e}")
        return {"error": str(e)}
    ```

!!! example "Implementing Caching"
    Cache identical requests to improve performance and reduce costs.
    
    ```python
    import hashlib
    import json
    from functools import lru_cache
    
    def generate_cache_key(agent_config, task):
        """Generate a unique cache key for an agent request."""
        cache_data = json.dumps({"agent_config": agent_config, "task": task}, sort_keys=True)
        return hashlib.md5(cache_data.encode()).hexdigest()
    
    @lru_cache(maxsize=100)
    def cached_agent_run(cache_key, agent_config, task):
        """Run agent with caching based on config and task."""
        # Convert agent_config back to a dictionary if it's a string representation
        if isinstance(agent_config, str):
            agent_config = json.loads(agent_config)
            
        payload = {
            "agent_config": agent_config,
            "task": task
        }
        
        try:
            response = requests.post(
                f"{BASE_URL}/v1/agent/completions",
                headers=headers,
                json=payload
            )
            response.raise_for_status()
            return response.json()
        except Exception as e:
            return {"error": str(e)}
    
    def run_agent_with_cache(agent_config, task):
        """Wrapper function to run agent with caching."""
        # Generate a cache key
        cache_key = generate_cache_key(agent_config, task)
        
        # Convert agent_config to a hashable type for lru_cache
        hashable_config = json.dumps(agent_config, sort_keys=True)
        
        # Call the cached function
        return cached_agent_run(cache_key, hashable_config, task)
    ```

!!! abstract "Usage & Cost Monitoring"
    Set up a monitoring system to track your API usage and costs.
    
    ```python
    def log_api_usage(api_call_type, tokens_used, cost_estimate):
        """Log API usage for monitoring."""
        with open("api_usage_log.csv", "a") as f:
            timestamp = datetime.now().isoformat()
            f.write(f"{timestamp},{api_call_type},{tokens_used},{cost_estimate}\n")
    
    def estimate_cost(tokens):
        """Estimate cost based on token usage."""
        # Example pricing: $0.002 per 1K tokens (adjust according to current pricing)
        return (tokens / 1000) * 0.002
    
    def run_agent_with_logging(agent_config, task):
        """Run agent and log usage."""
        result = run_single_agent(agent_config, task)
        
        if "usage" in result:
            total_tokens = result["usage"]["total_tokens"]
            cost = estimate_cost(total_tokens)
            log_api_usage("single_agent", total_tokens, cost)
            
        return result
    ```

## FAQ

??? question "What's the difference between Single Agent and Batch Agent APIs?"
    The Single Agent API (`/v1/agent/completions`) runs one agent with one task, while the Batch Agent API (`/v1/agent/batch/completions`) allows running multiple agents with different configurations and tasks in parallel. Use Batch Agent when you need to process multiple independent tasks efficiently.

??? question "How do I choose the right model for my agent?"
    Model selection depends on your task complexity, performance requirements, and budget:
    
    | Model | Best For | Characteristics |
    |-------|----------|-----------------|
    | gpt-4o | Complex analysis, creative tasks | Highest quality, most expensive |
    | gpt-4o-mini | General purpose tasks | Good balance of quality and cost |
    | openai/o3-mini | Simple, factual tasks | Fast, economical |
    
    For exploratory work, start with gpt-4o-mini and adjust based on results.

??? question "What should I include in my system prompt?"
    A good system prompt should include:
    
    1. **Role definition**: Who the agent is and their expertise
    2. **Task instructions**: Specific, clear directions on what to do
    3. **Output format**: How results should be structured
    4. **Constraints**: Any limitations or requirements
    5. **Examples**: Sample inputs and outputs when helpful
    
    Keep prompts focused and avoid contradictory instructions.

??? question "How can I optimize costs when using the Agent API?"
    Cost optimization strategies include:
    
    - Use the appropriate model for your task complexity
    - Set reasonable token limits based on expected output length
    - Implement caching for repeated or similar requests
    - Batch related requests together
    - Use `max_loops: 1` unless you specifically need iterative refinement
    - Monitor usage patterns and adjust configurations accordingly

??? question "What's the maximum number of agents I can run in a batch?"
    While there's no hard limit specified, we recommend keeping batch sizes under 20 agents for optimal performance. For very large batches, consider splitting them into multiple calls or contacting support for guidance on handling high-volume processing.

??? question "How do I handle rate limiting?"
    Implement exponential backoff in your error handling:
    
    ```python
    import time
    
    def run_with_backoff(func, max_retries=5, initial_delay=1):
        """Run a function with exponential backoff retry logic."""
        retries = 0
        delay = initial_delay
        
        while retries < max_retries:
            try:
                return func()
            except requests.exceptions.HTTPError as e:
                if e.response.status_code == 429:  # Too Many Requests
                    retry_after = int(e.response.headers.get('Retry-After', delay))
                    print(f"Rate limited. Retrying after {retry_after} seconds...")
                    time.sleep(retry_after)
                    retries += 1
                    delay *= 2  # Exponential backoff
                else:
                    raise
            except Exception as e:
                raise
                
        raise Exception(f"Failed after {max_retries} retries")
    ```

??? question "Can I use tools with my agents?"
    Yes, you can enable tools through the `tools_dictionary` parameter in your agent configuration. This allows agents to access external functionality like web searches, calculations, or custom tools.
    
    ```python
    agent_config = {
        # Other configuration...
        "tools_dictionary": [
            {
                "name": "web_search",
                "description": "Search the web for current information",
                "parameters": {
                    "query": {
                        "type": "string",
                        "description": "The search query"
                    }
                }
            }
        ]
    }
    ```

??? question "How do I debug agent performance issues?"
    Debugging steps for agent performance issues:
    
    1. **Check system prompts**: Ensure they're clear and not overly restrictive
    2. **Review model selection**: Try a more capable model if output quality is poor
    3. **Adjust token limits**: Increase max_tokens if outputs are getting truncated
    4. **Examine temperature**: Lower for more deterministic outputs, higher for creativity
    5. **Test with simpler tasks**: Isolate whether the issue is with the task complexity
    6. **Enable verbose logging**: Add detailed logging to track request/response cycles
    7. **Contact support**: For persistent issues, reach out with example payloads and responses

??? question "What's the pricing model for the Agent API?"
    The Agent API uses a token-based pricing model:
    
    1. **Input tokens**: Text sent to the API (task, system prompts)
    2. **Output tokens**: Text generated by the agent
    
    Pricing varies by model and is calculated per 1,000 tokens. Check the [pricing page](https://swarms.world/platform/pricing) for current rates.
    
    The API also offers a "flex" tier for lower-priority, cost-effective processing.

## Further Resources

[:material-file-document: Swarms.ai Documentation](https://docs.swarms.world){ .md-button }
[:material-application: Swarms.ai Platform](https://swarms.world/platform){ .md-button }
[:material-key: API Key Management](https://swarms.world/platform/api-keys){ .md-button }
[:material-forum: Swarms.ai Community](https://discord.gg/EamjgSaEQf){ .md-button }

--------------------------------------------------

# File: swarms_cloud/agent_rearrange.md

# AgentRearrange

*Dynamically reorganizes agents to optimize task performance and efficiency*

**Swarm Type**: `AgentRearrange`

## Overview

The AgentRearrange swarm type dynamically reorganizes the workflow between agents based on task requirements and performance metrics. This architecture is particularly useful when the effectiveness of agents depends on their sequence or arrangement, allowing for optimal task distribution and execution flow.

Key features:
- **Dynamic Reorganization**: Automatically adjusts agent order based on task needs
- **Performance Optimization**: Optimizes workflow for maximum efficiency
- **Adaptive Sequencing**: Learns from execution patterns to improve arrangement
- **Flexible Task Distribution**: Distributes work based on agent capabilities

## Use Cases

- Complex workflows where task order matters
- Multi-step processes requiring optimization
- Tasks where agent performance varies by sequence
- Adaptive workflow management systems

## API Usage

### Basic AgentRearrange Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Document Processing Rearrange",
        "description": "Process documents with dynamic agent reorganization",
        "swarm_type": "AgentRearrange",
        "task": "Analyze this legal document and extract key insights, then summarize findings and identify action items",
        "agents": [
          {
            "agent_name": "Document Analyzer",
            "description": "Analyzes document content and structure",
            "system_prompt": "You are an expert document analyst. Extract key information, themes, and insights from documents.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Legal Expert",
            "description": "Provides legal context and interpretation",
            "system_prompt": "You are a legal expert. Analyze documents for legal implications, risks, and compliance issues.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.2
          },
          {
            "agent_name": "Summarizer",
            "description": "Creates concise summaries and action items",
            "system_prompt": "You are an expert at creating clear, actionable summaries from complex information.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.4
          }
        ],
        "rearrange_flow": "Summarizer -> Legal Expert -> Document Analyzer",
        "max_loops": 1
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Document Processing Rearrange",
        "description": "Process documents with dynamic agent reorganization",
        "swarm_type": "AgentRearrange",
        "task": "Analyze this legal document and extract key insights, then summarize findings and identify action items",
        "agents": [
            {
                "agent_name": "Document Analyzer",
                "description": "Analyzes document content and structure",
                "system_prompt": "You are an expert document analyst. Extract key information, themes, and insights from documents.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Legal Expert", 
                "description": "Provides legal context and interpretation",
                "system_prompt": "You are a legal expert. Analyze documents for legal implications, risks, and compliance issues.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.2
            },
            {
                "agent_name": "Summarizer",
                "description": "Creates concise summaries and action items", 
                "system_prompt": "You are an expert at creating clear, actionable summaries from complex information.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.4
            }
        ],
        "rearrange_flow": "Summarizer -> Legal Expert -> Document Analyzer",
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("AgentRearrange swarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Output: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-Uc8R7UcepLmNNPwcU7JC6YPy5wiI",
    "status": "success",
    "swarm_name": "Document Processing Rearrange",
    "description": "Process documents with dynamic agent reorganization",
    "swarm_type": "AgentRearrange",
    "output": [
        {
            "role": "Summarizer",
            "content": "\"Of course! Please provide the legal document you would like me to analyze, and I'll help extract key insights, summarize findings, and identify any action items.\""
        },
        {
            "role": "Legal Expert",
            "content": "\"\"Absolutely! Please upload or describe the legal document you need assistance with, and I'll provide an analysis that highlights key insights, summarizes the findings, and identifies any action items that may be necessary.\"\""
        },
        {
            "role": "Document Analyzer",
            "content": "\"Of course! Please provide the legal document you would like me to analyze, and I'll help extract key insights, summarize findings, and identify any action items.\""
        }
    ],
    "number_of_agents": 3,
    "service_tier": "standard",
    "execution_time": 7.898931264877319,
    "usage": {
        "input_tokens": 22,
        "output_tokens": 144,
        "total_tokens": 166,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.03,
                "input_token_cost": 0.000066,
                "output_token_cost": 0.00216,
                "token_counts": {
                    "total_input_tokens": 22,
                    "total_output_tokens": 144,
                    "total_tokens": 166
                },
                "num_agents": 3,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.032226,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}
```

## Configuration Options

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `rearrange_flow` | string | Instructions for how agents should be rearranged | None |
| `agents` | Array<AgentSpec> | List of agents to be dynamically arranged | Required |
| `max_loops` | integer | Maximum rearrangement iterations | 1 |

## Best Practices

- Provide clear `rearrange_flow` instructions for optimal reorganization
- Design agents with complementary but flexible roles
- Use when task complexity requires adaptive sequencing
- Monitor execution patterns to understand rearrangement decisions

## Related Swarm Types

- [SequentialWorkflow](sequential_workflow.md) - For fixed sequential processing
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic swarm construction
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured agent hierarchies

--------------------------------------------------

# File: swarms_cloud/api_clients.md

# Swarms API Clients

*Production-Ready Client Libraries for Every Programming Language*

## Overview

The Swarms API provides official client libraries across multiple programming languages, enabling developers to integrate powerful multi-agent AI capabilities into their applications with ease. Our clients are designed for production use, featuring robust error handling, comprehensive documentation, and seamless integration with existing codebases.

Whether you're building enterprise applications, research prototypes, or innovative AI products, our client libraries provide the tools you need to harness the full power of the Swarms platform.

## Available Clients

| Language | Status | Repository | Documentation | Description |
|----------|--------|------------|---------------|-------------|
| **Python** | ✅ **Available** | [swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) | [Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | Production-grade Python client with comprehensive error handling, retry logic, and extensive examples |
| **TypeScript/Node.js** | ✅ **Available** | [swarms-ts](https://github.com/The-Swarm-Corporation/swarms-ts) | 📚 *Coming Soon* | Modern TypeScript client with full type safety, Promise-based API, and Node.js compatibility |
| **Go** | ✅ **Available** | [swarms-client-go](https://github.com/The-Swarm-Corporation/swarms-client-go) | 📚 *Coming Soon* | High-performance Go client optimized for concurrent operations and microservices |
| **Java** | ✅ **Available** | [swarms-java](https://github.com/The-Swarm-Corporation/swarms-java) | 📚 *Coming Soon* | Enterprise Java client with Spring Boot integration and comprehensive SDK features |
| **Kotlin** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Modern Kotlin client with coroutines support and Android compatibility |
| **Ruby** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Elegant Ruby client with Rails integration and gem packaging |
| **Rust** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Ultra-fast Rust client with memory safety and zero-cost abstractions |
| **C#/.NET** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | .NET client with async/await support and NuGet packaging |

## Client Features

All Swarms API clients are built with the following enterprise-grade features:

### 🔧 **Core Functionality**

| Feature                | Description                                                        |
|------------------------|--------------------------------------------------------------------|
| **Full API Coverage**  | Complete access to all Swarms API endpoints                        |
| **Type Safety**        | Strongly-typed interfaces for all request/response objects         |
| **Error Handling**     | Comprehensive error handling with detailed error messages           |
| **Retry Logic**        | Automatic retries with exponential backoff for transient failures  |

---

### 🚀 **Performance & Reliability**

| Feature                  | Description                                                        |
|--------------------------|--------------------------------------------------------------------|
| **Connection Pooling**   | Efficient HTTP connection management                               |
| **Rate Limiting**        | Built-in rate limit handling and backoff strategies                |
| **Timeout Configuration**| Configurable timeouts for different operation types                |
| **Streaming Support**    | Real-time streaming for long-running operations                    |

---

### 🛡️ **Security & Authentication**

| Feature                | Description                                                        |
|------------------------|--------------------------------------------------------------------|
| **API Key Management** | Secure API key handling and rotation                               |
| **TLS/SSL**            | End-to-end encryption for all communications                       |
| **Request Signing**    | Optional request signing for enhanced security                     |
| **Environment Configuration** | Secure environment-based configuration                      |

---

### 📊 **Monitoring & Debugging**

| Feature                    | Description                                                        |
|----------------------------|--------------------------------------------------------------------|
| **Comprehensive Logging**  | Detailed logging for debugging and monitoring                      |
| **Request/Response Tracing** | Full request/response tracing capabilities                      |
| **Metrics Integration**    | Built-in metrics for monitoring client performance                 |
| **Debug Mode**             | Enhanced debugging features for development                        |


## Client-Specific Features

### Python Client

| Feature                | Description                                              |
|------------------------|----------------------------------------------------------|
| **Async Support**      | Full async/await support with `asyncio`                  |
| **Pydantic Integration** | Type-safe request/response models                     |
| **Context Managers**   | Resource management with context managers                |
| **Rich Logging**       | Integration with Python's `logging` module               |

---

### TypeScript/Node.js Client

| Feature                | Description                                              |
|------------------------|----------------------------------------------------------|
| **TypeScript First**   | Built with TypeScript for maximum type safety            |
| **Promise-Based**      | Modern Promise-based API with async/await                |
| **Browser Compatible** | Works in both Node.js and modern browsers                |
| **Zero Dependencies**  | Minimal dependency footprint                             |

---

### Go Client

| Feature                | Description                                              |
|------------------------|----------------------------------------------------------|
| **Context Support**    | Full context.Context support for cancellation            |
| **Structured Logging** | Integration with structured logging libraries            |
| **Concurrency Safe**   | Thread-safe design for concurrent operations             |
| **Minimal Allocation** | Optimized for minimal memory allocation                  |

---

### Java Client

| Feature                | Description                                              |
|------------------------|----------------------------------------------------------|
| **Spring Boot Ready**  | Built-in Spring Boot auto-configuration                  |
| **Reactive Support**   | Optional reactive streams support                        |
| **Enterprise Features**| JMX metrics, health checks, and more                     |
| **Maven & Gradle**     | Available on Maven Central                               |

## Advanced Configuration

### Environment Variables

All clients support standard environment variables for configuration:

```bash
# API Configuration
SWARMS_API_KEY=your_api_key_here
SWARMS_BASE_URL=https://api.swarms.world

# Client Configuration
SWARMS_TIMEOUT=60
SWARMS_MAX_RETRIES=3
SWARMS_LOG_LEVEL=INFO
```

## Community & Support

### 📚 **Documentation & Resources**

| Resource                    | Link                                                                                   |
|-----------------------------|----------------------------------------------------------------------------------------|
| Complete API Documentation  | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/)             |
| Python Client Docs          | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/)           |
| API Examples & Tutorials    | [View Examples](https://docs.swarms.world/en/latest/examples/)                         |

---

### 💬 **Community Support**

| Community Channel           | Description                                                                           | Link                                                                                  |
|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| Discord Community           | Join our active developer community for real-time support and discussions             | [Join Discord](https://discord.gg/EamjgSaEQf)                                         |
| GitHub Discussions          | Ask questions and share ideas                                                         | [GitHub Discussions](https://github.com/The-Swarm-Corporation/swarms/discussions)     |
| Twitter/X                   | Follow for updates and announcements                                                  | [Twitter/X](https://x.com/swarms_corp)                                                |

---

### 🐛 **Issue Reporting & Contributions**

| Contribution Area           | Description                                                                           | Link                                                                                  |
|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| Report Bugs                 | Help us improve by reporting issues                                                   | [Report Bugs](https://github.com/The-Swarm-Corporation/swarms/issues)                 |
| Feature Requests            | Suggest new features and improvements                                                 | [Feature Requests](https://github.com/The-Swarm-Corporation/swarms/issues)            |
| Contributing Guide          | Learn how to contribute to the project                                                | [Contributing Guide](https://docs.swarms.world/en/latest/contributors/main/)          |

---

### 📧 **Direct Support**

| Support Type                | Contact Information                                                                   |
|-----------------------------|---------------------------------------------------------------------------------------|
| Support Call                       | [Book a call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true)                                          |
| Enterprise Support          | Contact us for dedicated enterprise support options                                   |


## Contributing to Client Development

We welcome contributions to all our client libraries! Here's how you can help:

### 🛠️ **Development**

| Task                                   | Description                                      |
|-----------------------------------------|--------------------------------------------------|
| Implement new features and endpoints    | Add new API features and expand client coverage   |
| Improve error handling and retry logic  | Enhance robustness and reliability               |
| Add comprehensive test coverage         | Ensure code quality and prevent regressions      |
| Optimize performance and memory usage   | Improve speed and reduce resource consumption    |

---

### 📝 **Documentation**

| Task                        | Description                                         |
|-----------------------------|-----------------------------------------------------|
| Write tutorials and examples | Create guides and sample code for users             |
| Improve API documentation    | Clarify and expand reference docs                   |
| Create integration guides    | Help users connect clients to their applications    |
| Translate documentation      | Make docs accessible in multiple languages          |

---

### 🧪 **Testing**

| Task                          | Description                                         |
|-------------------------------|-----------------------------------------------------|
| Add unit and integration tests | Test individual components and end-to-end flows     |
| Test with different language versions | Ensure compatibility across environments   |
| Performance benchmarking      | Measure and optimize speed and efficiency           |
| Security testing              | Identify and fix vulnerabilities                    |

---

### 📦 **Packaging**

| Task                          | Description                                         |
|-------------------------------|-----------------------------------------------------|
| Package managers (npm, pip, Maven, etc.) | Publish to popular package repositories  |
| Distribution optimization     | Streamline builds and reduce package size           |
| Version management            | Maintain clear versioning and changelogs            |
| Release automation            | Automate build, test, and deployment pipelines      |

## Enterprise Features

For enterprise customers, we offer additional features and support:

### 🏢 **Enterprise Client Features**

| Feature                  | Description                                                    |
|--------------------------|----------------------------------------------------------------|
| **Priority Support**     | Dedicated support team with SLA guarantees                     |
| **Custom Integrations**  | Tailored integrations for your specific needs                  |
| **On-Premises Deployment** | Support for on-premises or private cloud deployments         |
| **Advanced Security**    | Enhanced security features and compliance support              |
| **Training & Onboarding**| Comprehensive training for your development team               |

### 📞 **Contact Enterprise Sales**

| Contact Type   | Details                                                                                  |
|----------------|-----------------------------------------------------------------------------------------|
| **Sales**      | [kye@swarms.world](mailto:kye@swarms.world)                                         |
| **Schedule Demo** | [Book a Demo](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true)  |
| **Partnership**| [kye@swarms.world](mailto:kye@swarms.world)                           |

---

*Ready to build the future with AI agents? Start with any of our client libraries and join our growing community of developers building the next generation of intelligent applications.* 

--------------------------------------------------

# File: swarms_cloud/api_pricing.md

# Swarm Agent API Pricing

!!! success "🎉 Get Started with $20 Free Credits!"
    New users receive $20 in free credits when they sign up! [Create your account now](https://swarms.world/platform/account) to start building with our powerful multi-agent platform.

!!! abstract "Overview"
    The Swarm Agent API provides a powerful platform for managing multi-agent collaboration at scale and orchestrating swarms of LLM agents in the cloud. Our pricing model is designed to be transparent and cost-effective, enabling you to harness the full potential of your agents with ease.

## Credit System

The Swarm API operates on a credit-based system with the following characteristics:

- **Credits** are the currency used within the platform

- 1 credit = $1 USD

- Credits can be purchased with USD or $swarms Solana tokens

### Credit Types

| Type | Description | Expiration |
|------|-------------|------------|
| Standard Credits | Purchased credits | Never expires |
| Free Credits | Promotional credits | May have expiration dates |

## Pricing Structure

### Base Costs

| Cost Component | Price |
|----------------|-------|
| Base cost per agent | $0.01 per agent |

### Token Usage Costs

| Token Type | Cost |
|------------|------|
| Input tokens | $2.00 per 1M tokens |
| Output tokens | $4.50 per 1M tokens |

### Night-Time Discount

!!! tip "Off-Peak Hours Discount"
    To encourage efficient resource usage during off-peak hours, we offer significant discounts for operations performed during California night-time hours:

    | Time Period (Pacific Time) | Discount |
    |----------------------------|----------|
    | 8:00 PM to 6:00 AM | 75% off token costs |

## Cost Calculation

### Formula

The total cost for a swarm execution is calculated as follows:

```math
Total Cost = (Number of Agents × $0.01) + 
             (Total Input Tokens / 1M × $2.00 × Number of Agents) +
             (Total Output Tokens / 1M × $4.50 × Number of Agents)
```

With night-time discount applied:
```math
Input Token Cost = Input Token Cost × 0.25
Output Token Cost = Output Token Cost × 0.25
```

### Example Scenarios

#### Scenario 1: Basic Workflow (Day-time)

!!! example "Basic Workflow Example"
    **Parameters:**
    
    - 3 agents
    
    - 10,000 input tokens total
    
    - 25,000 output tokens total

    **Calculation:**
    
    - Agent cost: 3 × $0.01 = $0.03
    
    - Input token cost: (10,000 / 1,000,000) × $2.00 × 3 = $0.06
    
    - Output token cost: (25,000 / 1,000,000) × $4.50 × 3 = $0.3375
    
    - **Total cost: $0.4275**

#### Scenario 2: Complex Workflow (Night-time)

!!! example "Complex Workflow Example"
    **Parameters:**
    
    - 5 agents
    
    - 50,000 input tokens total
    
    - 125,000 output tokens total

    **Calculation:**
    
    - Agent cost: 5 × $0.01 = $0.05
    
    - Input token cost: (50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125
    
    - Output token cost: (125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125
    
    - **Total cost: $0.878125**

## Purchasing Credits

Credits can be purchased through our platform in two ways:

### USD Payment

- Available through our [account page](https://swarms.world/platform/account)

- Secure payment processing

- Minimum purchase: $10

### $swarms Token Payment

- Use Solana-based $swarms tokens

- Tokens can be purchased on supported exchanges

- Connect your Solana wallet on our [account page](https://swarms.world/platform/account)

## Free Credits

!!! info "Free Credit Program"
    We occasionally offer free credits to:
    
    - New users (welcome bonus)
    
    - During promotional periods
    
    - For educational and research purposes

    **Important Notes:**
    
    - Used before standard credits
    
    - May have expiration dates
    
    - May have usage restrictions

## Billing and Usage Tracking

Track your credit usage through our comprehensive logging and reporting features:

### API Logs
- Access detailed logs via the `/v1/swarm/logs` endpoint

- View cost breakdowns for each execution

### Dashboard
- Real-time credit balance display

- Historical usage graphs

- Detailed cost analysis

- Available at [https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)

## FAQ

??? question "Is there a minimum credit purchase?"
    Yes, the minimum credit purchase is $10 USD equivalent.

??? question "Do credits expire?"
    Standard credits do not expire. Free promotional credits may have expiration dates.

??? question "How is the night-time discount applied?"
    The system automatically detects the execution time based on Pacific Time (America/Los_Angeles) and applies a 75% discount to token costs for executions between 8:00 PM and 6:00 AM.

??? question "What happens if I run out of credits during execution?"
    Executions will fail with a 402 Payment Required error if sufficient credits are not available. We recommend maintaining a credit balance appropriate for your usage patterns.

??? question "Can I get a refund for unused credits?"
    Please contact our support team for refund requests for unused credits.

??? question "Are there volume discounts available?"
    Yes, please contact our sales team for enterprise pricing and volume discounts.

## References

- [Swarm API Documentation](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/)
- [Account Management Portal](https://swarms.world/platform/account)
- [Swarm Types Reference](https://docs.swarms.world/swarms_cloud/swarm_types)

---

!!! info "Need Help?"
    For additional questions or custom pricing options, please contact our support team at [kye@swarms.world](mailto:kye@swarms.world).

--------------------------------------------------

# File: swarms_cloud/auto.md

# Auto

*Intelligently selects the most effective swarm architecture for a given task*

**Swarm Type**: `auto` (or `Auto`)

## Overview

The Auto swarm type intelligently selects the most effective swarm architecture for a given task based on context analysis and task requirements. This intelligent system evaluates the task description and automatically chooses the optimal swarm type from all available architectures, ensuring maximum efficiency and effectiveness.

Key features:
- **Intelligent Selection**: Automatically chooses the best swarm type for each task
- **Context Analysis**: Analyzes task requirements to make optimal decisions
- **Adaptive Architecture**: Adapts to different types of problems automatically
- **Zero Configuration**: No manual architecture selection required

## Use Cases

- When unsure about which swarm type to use
- General-purpose task automation
- Rapid prototyping and experimentation
- Simplified API usage for non-experts

## API Usage



## Selection Logic

The Auto swarm type analyzes various factors to make its selection:

| Factor | Consideration |
|--------|---------------|
| **Task Complexity** | Simple → Single agent, Complex → Multi-agent |
| **Sequential Dependencies** | Dependencies → SequentialWorkflow |
| **Parallel Opportunities** | Independent subtasks → ConcurrentWorkflow |
| **Collaboration Needs** | Discussion required → GroupChat |
| **Expertise Diversity** | Multiple domains → MixtureOfAgents |
| **Management Needs** | Oversight required → HierarchicalSwarm |
| **Routing Requirements** | Task distribution → MultiAgentRouter |

## Best Practices

- Provide detailed task descriptions for better selection
- Use `rules` parameter to guide selection criteria
- Review the selected architecture in response metadata
- Ideal for users new to swarm architectures

## Related Swarm Types

Since Auto can select any swarm type, it's related to all architectures:
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic agent generation
- [SequentialWorkflow](sequential_workflow.md) - Often selected for linear tasks
- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel processing needs
- [MixtureOfAgents](mixture_of_agents.md) - For diverse expertise requirements

--------------------------------------------------

# File: swarms_cloud/auto_swarm_builder.md

# AutoSwarmBuilder [ Needs an Fix ]

*Automatically configures optimal swarm architectures based on task requirements*

**Swarm Type**: `AutoSwarmBuilder`

## Overview

The AutoSwarmBuilder automatically configures optimal agent architectures based on task requirements and performance metrics, simplifying swarm creation. This intelligent system analyzes the given task and automatically generates the most suitable agent configuration, eliminating the need for manual swarm design.

Key features:
- **Intelligent Configuration**: Automatically designs optimal swarm structures
- **Task-Adaptive**: Adapts architecture based on specific task requirements
- **Performance Optimization**: Selects configurations for maximum efficiency
- **Simplified Setup**: Eliminates manual agent configuration complexity

## Use Cases

- Quick prototyping and experimentation
- Unknown or complex task requirements
- Automated swarm optimization
- Simplified swarm creation for non-experts

## API Usage


## Configuration Options

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `task` | string | Task description for automatic optimization | Required |
| `rules` | string | Additional constraints and guidelines | None |
| `max_loops` | integer | Maximum execution rounds | 1 |

## Best Practices

- Provide detailed, specific task descriptions for better optimization
- Use `rules` parameter to guide the automatic configuration
- Ideal for rapid prototyping and experimentation
- Review generated architecture in response metadata

## Related Swarm Types

- [Auto](auto.md) - For automatic swarm type selection
- [MixtureOfAgents](mixture_of_agents.md) - Often selected by AutoSwarmBuilder
- [HierarchicalSwarm](hierarchical_swarm.md) - For complex structured tasks

--------------------------------------------------

# File: swarms_cloud/best_practices.md

# Swarms API Best Practices Guide

This comprehensive guide outlines production-grade best practices for using the Swarms API effectively. Learn how to choose the right swarm architecture, optimize costs, and implement robust error handling.

## Quick Reference Cards

=== "Swarm Types"
    
    !!! info "Available Swarm Architectures"
        
        | Swarm Type | Best For | Use Cases |
        |------------|----------|------------|
        | `AgentRearrange` | Dynamic workflows | - Complex task decomposition<br>- Adaptive processing<br>- Multi-stage analysis<br>- Dynamic resource allocation |
        | `MixtureOfAgents` | Diverse expertise | - Cross-domain problems<br>- Comprehensive analysis<br>- Multi-perspective tasks<br>- Research synthesis |
        | `SpreadSheetSwarm` | Data processing | - Financial analysis<br>- Data transformation<br>- Batch calculations<br>- Report generation |
        | `SequentialWorkflow` | Linear processes | - Document processing<br>- Step-by-step analysis<br>- Quality control<br>- Content pipeline |
        | `ConcurrentWorkflow` | Parallel tasks | - Batch processing<br>- Independent analyses<br>- High-throughput needs<br>- Multi-market analysis |
        | `GroupChat` | Collaborative solving | - Brainstorming<br>- Decision making<br>- Problem solving<br>- Strategy development |
        | `MultiAgentRouter` | Task distribution | - Load balancing<br>- Specialized processing<br>- Resource optimization<br>- Service routing |
        | `AutoSwarmBuilder` | Automated setup | - Quick prototyping<br>- Simple tasks<br>- Testing<br>- MVP development |
        | `HiearchicalSwarm` | Complex organization | - Project management<br>- Research analysis<br>- Enterprise workflows<br>- Team automation |
        | `MajorityVoting` | Consensus needs | - Quality assurance<br>- Decision validation<br>- Risk assessment<br>- Content moderation |

=== "Application Patterns"
    
    !!! tip "Specialized Application Configurations"
        
        | Application | Recommended Swarm | Benefits |
        |------------|-------------------|-----------|
        | **Team Automation** | `HiearchicalSwarm` | - Automated team coordination<br>- Clear responsibility chain<br>- Scalable team structure |
        | **Research Pipeline** | `SequentialWorkflow` | - Structured research process<br>- Quality control at each stage<br>- Comprehensive output |
        | **Trading System** | `ConcurrentWorkflow` | - Multi-market coverage<br>- Real-time analysis<br>- Risk distribution |
        | **Content Factory** | `MixtureOfAgents` | - Automated content creation<br>- Consistent quality<br>- High throughput |

=== "Cost Optimization"

    !!! tip "Advanced Cost Management Strategies"
        
        | Strategy | Implementation | Impact |
        |----------|----------------|---------|
        | Batch Processing | Group related tasks | 20-30% cost reduction |
        | Off-peak Usage | Schedule for 8 PM - 6 AM PT | 15-25% cost reduction |
        | Token Optimization | Precise prompts, focused tasks | 10-20% cost reduction |
        | Caching | Store reusable results | 30-40% cost reduction |
        | Agent Optimization | Use minimum required agents | 15-25% cost reduction |
        | Smart Routing | Route to specialized agents | 10-15% cost reduction |
        | Prompt Engineering | Optimize input tokens | 15-20% cost reduction |
        | Flex Processing | Use flex tier for non-urgent tasks | 75% cost reduction |

=== "Service Tiers"

    !!! tip "Choosing the Right Service Tier"
        
        | Tier | Best For | Benefits | Considerations |
        |------|----------|----------|----------------|
        | Standard | - Real-time processing<br>- Time-sensitive tasks<br>- Critical workflows | - Immediate execution<br>- Higher priority<br>- Predictable timing | - Higher cost<br>- 5-min timeout |
        | Flex | - Batch processing<br>- Non-urgent tasks<br>- Cost-sensitive workloads | - 75% cost reduction<br>- Longer timeouts<br>- Auto-retries | - Variable timing<br>- Resource contention |

=== "Industry Solutions"

    !!! example "Industry-Specific Swarm Patterns"
        
        | Industry | Use Case | Applications |
        |----------|----------|--------------|
        | **Finance** | Automated trading desk | - Portfolio management<br>- Risk assessment<br>- Market analysis<br>- Trading execution |
        | **Healthcare** | Clinical workflow automation | - Patient analysis<br>- Diagnostic support<br>- Treatment planning<br>- Follow-up care |
        | **Legal** | Legal document processing | - Document review<br>- Case analysis<br>- Contract review<br>- Compliance checks |
        | **E-commerce** | E-commerce operations | - Product management<br>- Pricing optimization<br>- Customer support<br>- Inventory management |

=== "Error Handling"

    !!! warning "Advanced Error Management Strategies"
        
        | Error Code | Strategy | Recovery Pattern |
        |------------|----------|------------------|
        | 400 | Input Validation | Pre-request validation with fallback |
        | 401 | Auth Management | Secure key rotation and storage |
        | 429 | Rate Limiting | Exponential backoff with queuing |
        | 500 | Resilience | Retry with circuit breaking |
        | 503 | High Availability | Multi-region redundancy |
        | 504 | Timeout Handling | Adaptive timeouts with partial results |

## Choosing the Right Swarm Architecture

### Decision Framework

Use this framework to select the optimal swarm architecture for your use case:

1. **Task Complexity Analysis**
    - Simple tasks → `AutoSwarmBuilder`
    - Complex tasks → `HiearchicalSwarm` or `MultiAgentRouter`
    - Dynamic tasks → `AgentRearrange`

2. **Workflow Pattern**
    - Linear processes → `SequentialWorkflow`
    - Parallel operations → `ConcurrentWorkflow`
    - Collaborative tasks → `GroupChat`

3. **Domain Requirements**
    - Multi-domain expertise → `MixtureOfAgents`
    - Data processing → `SpreadSheetSwarm`
    - Quality assurance → `MajorityVoting`

### Industry-Specific Recommendations

=== "Finance"
    
    !!! example "Financial Applications"
        - Risk Analysis: `HiearchicalSwarm`
        - Market Research: `MixtureOfAgents`
        - Trading Strategies: `ConcurrentWorkflow`
        - Portfolio Management: `SpreadSheetSwarm`

=== "Healthcare"
    
    !!! example "Healthcare Applications"
        - Patient Analysis: `SequentialWorkflow`
        - Research Review: `MajorityVoting`
        - Treatment Planning: `GroupChat`
        - Medical Records: `MultiAgentRouter`

=== "Legal"
    
    !!! example "Legal Applications"
        - Document Review: `SequentialWorkflow`
        - Case Analysis: `MixtureOfAgents`
        - Compliance Check: `HiearchicalSwarm`
        - Contract Analysis: `ConcurrentWorkflow`

## Production Best Practices

### Best Practices Summary

!!! success "Recommended Patterns"
    - Use appropriate swarm types for tasks
    - Implement robust error handling
    - Monitor and log executions
    - Cache repeated results
    - Rotate API keys regularly
    - Choose appropriate service tier based on task urgency
    - Use flex processing for batch and non-urgent tasks

!!! danger "Anti-patterns to Avoid"
    - Hardcoding API keys
    - Ignoring rate limits
    - Missing error handling
    - Excessive agent count
    - Inadequate monitoring
    - Using standard tier for non-urgent tasks
    - Not implementing retry logic for flex tier

### Performance Benchmarks

!!! note "Typical Performance Metrics"
    
    | Metric | Target Range | Warning Threshold |
    |--------|--------------|-------------------|
    | Response Time | < 2s (standard)<br>< 15s (flex) | > 5s (standard)<br>> 30s (flex) |
    | Success Rate | > 99% | < 95% |
    | Cost per Task | < $0.05 (standard)<br>< $0.0125 (flex) | > $0.10 (standard)<br>> $0.025 (flex) |
    | Cache Hit Rate | > 80% | < 60% |
    | Error Rate | < 1% | > 5% |
    | Retry Rate (flex) | < 10% | > 30% |

### Additional Resources

!!! info "Useful Links"
    
    - [Swarms API Documentation](https://docs.swarms.world)
    - [API Dashboard](https://swarms.world/platform/api-keys)

--------------------------------------------------

# File: swarms_cloud/chinese_api_pricing.md

# Swarm Agent API 定价文档


Swarm Agent API 提供了一个强大的平台，用于大规模管理多代理协作和在云端编排 LLM 代理群。本文档概述了定价模型、成本计算方式以及如何购买和管理您的积分。

我们的定价设计旨在透明且具有成本效益，使您能够轻松发挥代理的全部潜力。成本基于：

- 使用的代理数量

- 输入和输出令牌使用量

- 执行时间

## 积分系统

Swarm API 采用基于积分的系统：

- **积分**是平台内使用的货币

- 1积分 = 1美元

- 积分可以用美元或 $swarms Solana 代币购买

- 两种类型的积分：

  - **标准积分**：购买的积分永不过期

  - **免费积分**：促销积分，可能有使用限制

## 定价结构

### 基本成本

| 成本组成 | 价格 |
|----------------|-------|
| 每个代理的基本成本 | 每个代理$0.01 |

### 令牌使用成本

| 令牌类型 | 成本 |
|------------|------|
| 输入令牌 | 每百万令牌$2.00 |
| 输出令牌 | 每百万令牌$4.50 |

### 夜间折扣

为了鼓励在非高峰时段高效利用资源，我们在加州夜间时段提供显著折扣：

| 时间段（太平洋时间） | 折扣 |
|----------------------------|----------|
| 晚上8:00至早上6:00 | 令牌成本75%折扣 |

## 成本计算

### 公式

群体执行的总成本计算如下：

```
总成本 = (代理数量 × $0.01) + 
        (总输入令牌数 / 1M × $2.00 × 代理数量) +
        (总输出令牌数 / 1M × $4.50 × 代理数量)
```

应用夜间折扣时：
```
输入令牌成本 = 输入令牌成本 × 0.25
输出令牌成本 = 输出令牌成本 × 0.25
```

### 示例场景

#### 场景1：基本工作流（白天）

- 3个代理

- 总共10,000个输入令牌

- 总共25,000个输出令牌

**计算：**

- 代理成本：3 × $0.01 = $0.03

- 输入令牌成本：(10,000 / 1,000,000) × $2.00 × 3 = $0.06

- 输出令牌成本：(25,000 / 1,000,000) × $4.50 × 3 = $0.3375

- **总成本：$0.4275**

#### 场景2：复杂工作流（夜间）

- 5个代理

- 总共50,000个输入令牌

- 总共125,000个输出令牌

**计算：**

- 代理成本：5 × $0.01 = $0.05

- 输入令牌成本：(50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125

- 输出令牌成本：(125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125

- **总成本：$0.878125**

## 购买积分

可以通过我们的平台以两种方式购买积分：

1. **美元支付**
   - 可通过我们的[账户页面](https://swarms.world/platform/account)使用
   - 安全支付处理
   - 最低购买额：$10

2. **$swarms 代币支付**
   - 使用基于Solana的$swarms代币
   - 可在支持的交易所购买代币
   - 在我们的[账户页面](https://swarms.world/platform/account)连接您的Solana钱包

## 免费积分

我们偶尔会向以下对象提供免费积分：

- 新用户（欢迎奖励）

- 促销期间

- 教育和研究目的

关于免费积分的说明：

- 在标准积分之前使用

- 可能有过期日期

- 可能有使用限制

## 账单和使用跟踪

通过我们全面的日志和报告功能跟踪您的积分使用情况：

1. **API日志**

   - 通过`/v1/swarm/logs`端点访问详细日志

   - 查看每次执行的成本明细

2. **仪表板**

   - 实时积分余额显示

   - 历史使用图表

   - 详细成本分析

   - 可在[https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)访问

## 常见问题

**问：是否有最低积分购买要求？**  
答：是的，最低积分购买额为10美元等值。

**问：积分会过期吗？**  
答：标准积分不会过期。免费促销积分可能有过期日期。

**问：夜间折扣如何应用？**  
答：系统会根据太平洋时间（America/Los_Angeles）自动检测执行时间，并在晚上8:00至早上6:00之间的执行应用75%的令牌成本折扣。

**问：如果我在执行过程中积分用完了会怎样？**  
答：如果没有足够的积分，执行将失败并显示402 Payment Required错误。我们建议维持适合您使用模式的积分余额。

**问：我可以获得未使用积分的退款吗？**  
答：请联系我们的支持团队处理未使用积分的退款请求。

**问：是否有批量折扣？**  
答：是的，请联系我们的销售团队了解企业定价和批量折扣。

## 参考资料

- [Swarm API 文档](https://docs.swarms.world)

- [账户管理门户](https://swarms.world/platform/account)

- [Swarm 类型参考](https://docs.swarms.world/swarm-types)

- [令牌使用指南](https://docs.swarms.world/token-usage)

- [API 参考](https://docs.swarms.world/api-reference)

---

如有其他问题或自定义定价选项，请联系我们的支持团队，邮箱：kye@swarms.world

--------------------------------------------------

# File: swarms_cloud/cloud_run.md

# Hosting Agents on Google Cloud Run

This documentation provides a highly detailed, step-by-step guide to hosting your agents using Google Cloud Run. It uses a well-structured project setup that includes a Dockerfile at the root level, a folder dedicated to your API file, and a `requirements.txt` file to manage all dependencies. This guide will ensure your deployment is scalable, efficient, and easy to maintain.

---

## **Project Structure**

Your project directory should adhere to the following structure to ensure compatibility and ease of deployment:

```
.
├── Dockerfile
├── requirements.txt
└── api/
    └── api.py
```

Each component serves a specific purpose in the deployment pipeline, ensuring modularity and maintainability.

---

## **Step 1: Prerequisites**

Before you begin, make sure to satisfy the following prerequisites to avoid issues during deployment:

1. **Google Cloud Account**:
   - Create a Google Cloud account at [Google Cloud Console](https://console.cloud.google.com/).
   - Enable billing for your project. Billing is necessary for accessing Cloud Run services.

2. **Install Google Cloud SDK**:
   - Follow the [installation guide](https://cloud.google.com/sdk/docs/install) to set up the Google Cloud SDK on your local machine.

3. **Install Docker**:
   - Download and install Docker by following the [official Docker installation guide](https://docs.docker.com/get-docker/). Docker is crucial for containerizing your application.

4. **Create a Google Cloud Project**:
   - Navigate to the Google Cloud Console and create a new project. Assign it a meaningful name and note the **Project ID**, as it will be used throughout this guide.

5. **Enable Required APIs**:
   - Visit the [API Library](https://console.cloud.google.com/apis/library) and enable the following APIs:
     - Cloud Run API
     - Cloud Build API
     - Artifact Registry API
   - These APIs are essential for deploying and managing your application in Cloud Run.

---

## **Step 2: Creating the Files**

### 1. **`api/api.py`**

This is the main Python script where you define your Swarms agents and expose an API endpoint for interacting with them. Here’s an example:

```python
from flask import Flask, request, jsonify
from swarms import Agent  # Assuming `swarms` is the framework you're using

app = Flask(__name__)

# Example Swarm agent
agent = Agent(
    agent_name="Stock-Analysis-Agent",
    model_name="gpt-4o-mini",
    max_loops="auto",
    interactive=True,
    streaming_on=True,
)

@app.route('/run-agent', methods=['POST'])
def run_agent():
    data = request.json
    task = data.get('task', '')
    result = agent.run(task)
    return jsonify({"result": result})

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)
```

This example sets up a basic API that listens for POST requests, processes a task using a Swarm agent, and returns the result as a JSON response. Customize it based on your agent’s functionality.

---

### 2. **`requirements.txt`**

This file lists all Python dependencies required for your project. Example:

```
flask
swarms
# add any other dependencies here
```

Be sure to include any additional libraries your agents rely on. Keeping this file up to date ensures smooth dependency management during deployment.

---

### 3. **`Dockerfile`**

The Dockerfile specifies how your application is containerized. Below is a sample Dockerfile for your setup:

```dockerfile
# Use an official Python runtime as the base image
FROM python:3.10-slim

# Set the working directory
WORKDIR /app

# Copy requirements.txt and install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy the application code
COPY api/ ./api/

# Expose port 8080 (Cloud Run default port)
EXPOSE 8080

# Run the application
CMD ["python", "api/api.py"]
```

This Dockerfile ensures your application is containerized with minimal overhead, focusing on slim images for efficiency.

---

## **Step 3: Deploying to Google Cloud Run**

### 1. **Authenticate with Google Cloud**

Log in to your Google Cloud account by running:

```bash
gcloud auth login
```

Set the active project to match your deployment target:

```bash
gcloud config set project [PROJECT_ID]
```

Replace `[PROJECT_ID]` with your actual Project ID.

---

### 2. **Build the Docker Image**

Use Google Cloud's Artifact Registry to store and manage your Docker image. Follow these steps:

1. **Create a Repository**:

```bash
gcloud artifacts repositories create my-repo --repository-format=Docker --location=us-central1
```

2. **Authenticate Docker with Google Cloud**:

```bash
gcloud auth configure-docker us-central1-docker.pkg.dev
```

3. **Build and Tag the Image**:

```bash
docker build -t us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image .
```

4. **Push the Image**:

```bash
docker push us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image
```

---

### 3. **Deploy to Cloud Run**

Deploy the application to Cloud Run with the following command:

```bash
gcloud run deploy my-agent-service \
  --image us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated
```

Key points:
- Replace `[PROJECT_ID]` with your actual Project ID.
- The `--allow-unauthenticated` flag makes the service publicly accessible. Exclude it to restrict access.

---

## **Step 4: Testing the Deployment**

Once the deployment is complete, test the service:

1. Note the URL provided by Cloud Run.
2. Use `curl` or Postman to send a request. Example:

```bash
curl -X POST [CLOUD_RUN_URL]/run-agent \
  -H "Content-Type: application/json" \
  -d '{"task": "example task"}'
```

This tests whether your agent processes the task correctly and returns the expected output.

---

## **Step 5: Updating the Service**

To apply changes to your application:

1. Edit the necessary files.
2. Rebuild and push the updated Docker image:

```bash
docker build -t us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image .
docker push us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image
```

3. Redeploy the service:

```bash
gcloud run deploy my-agent-service \
  --image us-central1-docker.pkg.dev/[PROJECT_ID]/my-repo/my-image
```

This ensures the latest version of your application is live.

---

## **Troubleshooting**

- **Permission Errors**:
  Ensure your account has roles like Cloud Run Admin and Artifact Registry Reader.
- **Port Issues**:
  Confirm the application listens on port 8080. Cloud Run expects this port by default.
- **Logs**:
  Use the Google Cloud Console or CLI to review logs for debugging:

```bash
gcloud logs read --project [PROJECT_ID]
```

---

## **Conclusion**

By following this comprehensive guide, you can deploy your agents on Google Cloud Run with ease. This method leverages Docker for containerization and Google Cloud services for seamless scalability and management. With a robust setup like this, you can focus on enhancing your agents’ capabilities rather than worrying about deployment challenges.



--------------------------------------------------

# File: swarms_cloud/cloudflare_workers.md

# Deploy AI Agents with Swarms API on Cloudflare Workers

Deploy intelligent AI agents powered by Swarms API on Cloudflare Workers edge network. Build production-ready cron agents that run automatically, fetch real-time data, perform AI analysis, and execute actions across 330+ cities worldwide.

<!-- ## Demo Video

Watch the stock agent in action:

<iframe width="800" height="450"
    src="https://www.youtube.com/embed/YOUR_VIDEO_ID"
    frameborder="0"
    allowfullscreen>
</iframe>

> **Note**: The demo video shows the complete workflow from data fetching to AI analysis and report generation. -->

## Overview

This integration demonstrates how to combine **Swarms API multi-agent intelligence** with **Cloudflare Workers edge computing** to create autonomous AI systems that:

- ⚡ **Execute automatically** on predefined schedules (cron jobs)
- 📊 **Fetch real-time data** from external APIs (Yahoo Finance, news feeds)
- 🤖 **Perform intelligent analysis** using specialized Swarms AI agents
- 📧 **Take automated actions** (email alerts, reports, notifications)
- 🌍 **Scale globally** on Cloudflare's edge network with sub-100ms latency

## Repository & Complete Implementation

For the **complete working implementation** with full source code, detailed setup instructions, and ready-to-deploy examples, visit:

**🔗 [Swarms-CloudFlare-Deployment Repository](https://github.com/The-Swarm-Corporation/Swarms-CloudFlare-Deployment)**

This repository provides:
- **Two complete implementations**: JavaScript and Python
- **Production-ready code** with error handling and monitoring
- **Step-by-step deployment guides** for both local and production environments
- **Real-world examples** including stock analysis agents
- **Configuration templates** and environment setup

## Available Implementations

The repository provides **two complete implementations** of stock analysis agents:

### 📂 `stock-agent/` - JavaScript Implementation
The original implementation using **JavaScript/TypeScript** on Cloudflare Workers.

### 📂 `python-stock-agent/` - Python Implementation  
A **Python Workers** implementation using Cloudflare's beta Python runtime with Pyodide.

## Stock Analysis Agent Features

Both implementations demonstrate a complete system that:

1. **Automated Analysis**: Runs stock analysis every 3 hours using Cloudflare Workers cron
2. **Real-time Data**: Fetches market data from Yahoo Finance API (no API key needed)
3. **News Integration**: Collects market news from Financial Modeling Prep API (optional)
4. **Multi-Agent Analysis**: Deploys multiple Swarms AI agents for technical and fundamental analysis
5. **Email Reports**: Sends comprehensive reports via Mailgun
6. **Web Interface**: Provides monitoring dashboard for manual triggers and status tracking

## Implementation Comparison

| Feature | JavaScript (`stock-agent/`) | Python (`python-stock-agent/`) |
|---------|----------------------------|--------------------------------|
| **Runtime** | V8 JavaScript Engine | Pyodide Python Runtime |
| **Language** | JavaScript/TypeScript | Python 3.x |
| **Status** | Production Ready | Beta (Python Workers) |
| **Performance** | Optimized V8 execution | Good, with Python stdlib support |
| **Syntax** | `fetch()`, `JSON.stringify()` | `await fetch()`, `json.dumps()` |
| **Error Handling** | `try/catch` | `try/except` |
| **Libraries** | Built-in Web APIs | Python stdlib + select packages |
| **Development** | Mature tooling | Growing ecosystem |

## Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Cloudflare      │    │  Data Sources   │    │   Swarms API    │
│ Workers Runtime │    │                 │    │                 │
│ "0 */3 * * *"   │───▶│ Yahoo Finance   │───▶│ Technical Agent │
│ JS | Python     │    │ News APIs       │    │ Fundamental     │
│ scheduled()     │    │ Market Data     │    │ Agent Analysis  │
│ Global Edge     │    │                 │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## Quick Start Guide

Choose your preferred implementation:

### Option A: JavaScript Implementation

```bash
# Clone the repository
git clone https://github.com/The-Swarm-Corporation/Swarms-CloudFlare-Deployment.git
cd Swarms-CloudFlare-Deployment/stock-agent

# Install dependencies
npm install
```

### Option B: Python Implementation

```bash
# Clone the repository
git clone https://github.com/The-Swarm-Corporation/Swarms-CloudFlare-Deployment.git
cd Swarms-CloudFlare-Deployment/python-stock-agent

# Install dependencies (Wrangler CLI)
npm install
```

### 2. Environment Configuration

Create a `.dev.vars` file in your chosen directory:

```env
# Required: Swarms API key
SWARMS_API_KEY=your-swarms-api-key-here

# Optional: Market news (free tier available)
FMP_API_KEY=your-fmp-api-key

# Optional: Email notifications
MAILGUN_API_KEY=your-mailgun-api-key
MAILGUN_DOMAIN=your-domain.com
RECIPIENT_EMAIL=your-email@example.com
```

### 3. Cron Schedule Configuration

The cron schedule is configured in `wrangler.jsonc`:

```jsonc
{
  "triggers": {
    "crons": [
      "0 */3 * * *"  // Every 3 hours
    ]
  }
}
```

Common cron patterns:
- `"0 9 * * 1-5"` - 9 AM weekdays only
- `"0 */6 * * *"` - Every 6 hours  
- `"0 0 * * *"` - Daily at midnight

### 4. Local Development

```bash
# Start local development server
npm run dev

# Visit http://localhost:8787 to test
```

### 5. Deploy to Cloudflare Workers

```bash
# Deploy to production
npm run deploy

# Your agent will be live at: https://stock-agent.your-subdomain.workers.dev
```

## API Integration Details

### Swarms API Agents

The stock agent uses two specialized AI agents:

1. **Technical Analyst Agent**:
   - Calculates technical indicators (RSI, MACD, Moving Averages)
   - Identifies support/resistance levels
   - Provides trading signals and price targets

2. **Fundamental Analyst Agent**:
   - Analyzes market conditions and sentiment
   - Evaluates news and economic indicators
   - Provides investment recommendations

### Data Sources

- **Yahoo Finance API**: Free real-time stock data (no API key required)
- **Financial Modeling Prep**: Market news and additional data (free tier: 250 requests/day)
- **Mailgun**: Email delivery service (free tier: 5,000 emails/month)

## Features

### Web Interface
- Real-time status monitoring
- Manual analysis triggers
- Progress tracking with visual feedback
- Analysis results display

### Automated Execution
- Scheduled cron job execution
- Error handling and recovery
- Cost tracking and monitoring
- Email report generation

### Production Ready
- Comprehensive error handling
- Timeout protection
- Rate limiting compliance
- Security best practices

## Configuration Examples

### Custom Stock Symbols

Edit the symbols array in `src/index.js`:

```javascript
const symbols = ['SPY', 'QQQ', 'AAPL', 'MSFT', 'TSLA', 'NVDA', 'AMZN', 'GOOGL'];
```

### Custom Swarms Agents

Modify the agent configuration:

```javascript
const swarmConfig = {
  agents: [
    {
      agent_name: "Risk Assessment Agent",
      system_prompt: "Analyze portfolio risk and provide recommendations...",
      model_name: "gpt-4o-mini",
      max_tokens: 2000,  
      temperature: 0.1
    }
  ]
};
```

## Cost Optimization

- **Cloudflare Workers**: Free tier includes 100,000 requests/day
- **Swarms API**: Monitor usage in dashboard, use gpt-4o-mini for cost efficiency
- **External APIs**: Leverage free tiers and implement intelligent caching

## Security & Best Practices

- Store API keys as Cloudflare Workers secrets
- Implement request validation and rate limiting
- Audit AI decisions and maintain compliance logs
- Use HTTPS for all external API calls

## Monitoring & Observability

- Cloudflare Workers analytics dashboard
- Real-time performance metrics
- Error tracking and alerting
- Cost monitoring and optimization

## Troubleshooting

### Common Issues

1. **API Key Errors**: Verify environment variables are set correctly
2. **Cron Not Triggering**: Check cron syntax and Cloudflare Workers limits
3. **Email Not Sending**: Verify Mailgun configuration and domain setup
4. **Data Fetch Failures**: Check external API status and rate limits

### Debug Mode

Enable detailed logging by setting:
```javascript
console.log('Debug mode enabled');
```

## Additional Resources

- [Cloudflare Workers Documentation](https://developers.cloudflare.com/workers/)
- [Swarms API Documentation](https://docs.swarms.world/)
- [Cron Expression Generator](https://crontab.guru/)
- [Financial Modeling Prep API](https://financialmodelingprep.com/developer/docs)



--------------------------------------------------

# File: swarms_cloud/concurrent_workflow.md

# ConcurrentWorkflow

*Runs independent tasks in parallel for faster processing*

**Swarm Type**: `ConcurrentWorkflow`

## Overview

The ConcurrentWorkflow swarm type runs independent tasks in parallel, significantly reducing processing time for complex operations. This architecture is ideal for tasks that can be processed simultaneously without dependencies, allowing multiple agents to work on different aspects of a problem at the same time.

Key features:
- **Parallel Execution**: Multiple agents work simultaneously
- **Reduced Processing Time**: Faster completion through parallelization
- **Independent Tasks**: Agents work on separate, non-dependent subtasks
- **Scalable Performance**: Performance scales with the number of agents

## Use Cases

- Independent data analysis tasks
- Parallel content generation
- Multi-source research projects
- Distributed problem solving

## API Usage

### Basic ConcurrentWorkflow Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Market Research Concurrent",
        "description": "Parallel market research across different sectors",
        "swarm_type": "ConcurrentWorkflow",
        "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
        "agents": [
          {
            "agent_name": "AI Market Analyst",
            "description": "Analyzes AI market trends and opportunities",
            "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Healthcare Market Analyst",
            "description": "Analyzes healthcare market trends",
            "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Fintech Market Analyst",
            "description": "Analyzes fintech market opportunities",
            "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "E-commerce Market Analyst",
            "description": "Analyzes e-commerce market trends",
            "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          }
        ],
        "max_loops": 1
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Market Research Concurrent",
        "description": "Parallel market research across different sectors",
        "swarm_type": "ConcurrentWorkflow",
        "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
        "agents": [
            {
                "agent_name": "AI Market Analyst",
                "description": "Analyzes AI market trends and opportunities",
                "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Healthcare Market Analyst",
                "description": "Analyzes healthcare market trends",
                "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Fintech Market Analyst",
                "description": "Analyzes fintech market opportunities",
                "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "E-commerce Market Analyst",
                "description": "Analyzes e-commerce market trends",
                "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            }
        ],
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("ConcurrentWorkflow swarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Parallel results: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-S17nZFDesmLHxCRoeyF3NVYvPaXk",
    "status": "success",
    "swarm_name": "Market Research Concurrent",
    "description": "Parallel market research across different sectors",
    "swarm_type": "ConcurrentWorkflow",
    "output": [
        {
            "role": "E-commerce Market Analyst",
            "content": "To analyze market opportunities in the AI, healthcare, fintech, and e-commerce sectors, we can break down each sector's current trends, consumer behavior, and emerging platforms. Here's an overview of each sector with a focus on e-commerce....."
        },
        {
            "role": "AI Market Analyst",
            "content": "The artificial intelligence (AI) landscape presents numerous opportunities across various sectors, particularly in healthcare, fintech, and e-commerce. Here's a detailed analysis of each sector:\n\n### Healthcare....."
        },
        {
            "role": "Healthcare Market Analyst",
            "content": "As a Healthcare Market Analyst, I will focus on analyzing market opportunities within the healthcare sector, particularly in the realm of AI and digital health. The intersection of healthcare with fintech and e-commerce also presents unique opportunities. Here's an overview of key trends and growth areas:...."
        },
        {
            "role": "Fintech Market Analyst",
            "content": "Certainly! Let's break down the market opportunities in the fintech sector, focusing on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments:\n\n### 1. Financial Technology Trends....."
        }
    ],
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 23.360230922698975,
    "usage": {
        "input_tokens": 35,
        "output_tokens": 2787,
        "total_tokens": 2822,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.000105,
                "output_token_cost": 0.041805,
                "token_counts": {
                    "total_input_tokens": 35,
                    "total_output_tokens": 2787,
                    "total_tokens": 2822
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.08191,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}
```

## Best Practices

- Design independent tasks that don't require sequential dependencies
- Use for tasks that can be parallelized effectively
- Ensure agents have distinct, non-overlapping responsibilities
- Ideal for time-sensitive analysis requiring multiple perspectives

## Related Swarm Types

- [SequentialWorkflow](sequential_workflow.md) - For ordered execution
- [MixtureOfAgents](mixture_of_agents.md) - For collaborative analysis
- [MultiAgentRouter](multi_agent_router.md) - For intelligent task distribution

--------------------------------------------------

# File: swarms_cloud/group_chat.md

# GroupChat

*Enables dynamic collaboration through chat-based interaction*

**Swarm Type**: `GroupChat`

## Overview

The GroupChat swarm type enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. Agents participate in a conversational workflow where they can build upon each other's contributions, debate ideas, and reach consensus through natural dialogue.

Key features:
- **Interactive Dialogue**: Agents communicate through natural conversation
- **Dynamic Collaboration**: Real-time information sharing and building upon ideas  
- **Consensus Building**: Agents can debate and reach decisions collectively
- **Flexible Participation**: Agents can contribute when relevant to the discussion

## Use Cases

- Brainstorming and ideation sessions
- Multi-perspective problem analysis
- Collaborative decision-making processes
- Creative content development

## API Usage

### Basic GroupChat Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Product Strategy Discussion",
        "description": "Collaborative chat to develop product strategy",
        "swarm_type": "GroupChat",
        "task": "Discuss and develop a go-to-market strategy for a new AI-powered productivity tool targeting small businesses",
        "agents": [
          {
            "agent_name": "Product Manager",
            "description": "Leads product strategy and development",
            "system_prompt": "You are a senior product manager. Focus on product positioning, features, user needs, and market fit. Ask probing questions and build on others ideas.",
            "model_name": "gpt-4o",
            "max_loops": 3,
          },
          {
            "agent_name": "Marketing Strategist", 
            "description": "Develops marketing and positioning strategy",
            "system_prompt": "You are a marketing strategist. Focus on target audience, messaging, channels, and competitive positioning. Contribute marketing insights to the discussion.",
            "model_name": "gpt-4o",
            "max_loops": 3,
          },
          {
            "agent_name": "Sales Director",
            "description": "Provides sales and customer perspective",
            "system_prompt": "You are a sales director with small business experience. Focus on pricing, sales process, customer objections, and market adoption. Share practical sales insights.",
            "model_name": "gpt-4o",
            "max_loops": 3,
          },
          {
            "agent_name": "UX Researcher",
            "description": "Represents user experience and research insights",
            "system_prompt": "You are a UX researcher specializing in small business tools. Focus on user behavior, usability, adoption barriers, and design considerations.",
            "model_name": "gpt-4o",
            "max_loops": 3,
          }
        ],
        "max_loops": 3
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Product Strategy Discussion",
        "description": "Collaborative chat to develop product strategy",
        "swarm_type": "GroupChat",
        "task": "Discuss and develop a go-to-market strategy for a new AI-powered productivity tool targeting small businesses",
        "agents": [
            {
                "agent_name": "Product Manager",
                "description": "Leads product strategy and development",
                "system_prompt": "You are a senior product manager. Focus on product positioning, features, user needs, and market fit. Ask probing questions and build on others ideas.",
                "model_name": "gpt-4o",
                "max_loops": 3,
            },
            {
                "agent_name": "Marketing Strategist", 
                "description": "Develops marketing and positioning strategy",
                "system_prompt": "You are a marketing strategist. Focus on target audience, messaging, channels, and competitive positioning. Contribute marketing insights to the discussion.",
                "model_name": "gpt-4o",
                "max_loops": 3,
            },
            {
                "agent_name": "Sales Director",
                "description": "Provides sales and customer perspective",
                "system_prompt": "You are a sales director with small business experience. Focus on pricing, sales process, customer objections, and market adoption. Share practical sales insights.",
                "model_name": "gpt-4o",
                "max_loops": 3,
            },
            {
                "agent_name": "UX Researcher",
                "description": "Represents user experience and research insights",
                "system_prompt": "You are a UX researcher specializing in small business tools. Focus on user behavior, usability, adoption barriers, and design considerations.",
                "model_name": "gpt-4o",
                "max_loops": 3,
            }
        ],
        "max_loops": 3
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("GroupChat swarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Chat discussion: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-2COVtf3k0Fz7jU1BOOHF3b5nuL2x",
    "status": "success",
    "swarm_name": "Product Strategy Discussion",
    "description": "Collaborative chat to develop product strategy",
    "swarm_type": "GroupChat",
    "output": "User: \n\nSystem: \n Group Chat Name: Product Strategy Discussion\nGroup Chat Description: Collaborative chat to develop product strategy\n Agents in your Group Chat: Available Agents for Team: None\n\n\n\n[Agent 1]\nName: Product Manager\nDescription: Leads product strategy and development\nRole.....",
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 47.36732482910156,
    "usage": {
        "input_tokens": 30,
        "output_tokens": 1633,
        "total_tokens": 1663,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.00009,
                "output_token_cost": 0.024495,
                "token_counts": {
                    "total_input_tokens": 30,
                    "total_output_tokens": 1633,
                    "total_tokens": 1663
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": false
            },
            "total_cost": 0.064585,
            "discount_active": false,
            "discount_type": "none",
            "discount_percentage": 0
        }
    }
}
```

## Best Practices

- Set clear discussion goals and objectives
- Use diverse agent personalities for richer dialogue
- Allow multiple conversation rounds for idea development
- Encourage agents to build upon each other's contributions

## Related Swarm Types

- [MixtureOfAgents](mixture_of_agents.md) - For complementary expertise
- [MajorityVoting](majority_voting.md) - For consensus decision-making
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic discussion setup

--------------------------------------------------

# File: swarms_cloud/hierarchical_swarm.md

# HiearchicalSwarm

*Implements structured, multi-level task management with clear authority*

**Swarm Type**: `HiearchicalSwarm`

## Overview

The HiearchicalSwarm implements a structured, multi-level approach to task management with clear lines of authority and delegation. This architecture organizes agents in a hierarchical structure where manager agents coordinate and oversee worker agents, enabling efficient task distribution and quality control.

Key features:
- **Structured Hierarchy**: Clear organizational structure with managers and workers
- **Delegated Authority**: Manager agents distribute tasks to specialized workers
- **Quality Oversight**: Multi-level review and validation processes
- **Scalable Organization**: Efficient coordination of large agent teams

## Use Cases

- Complex projects requiring management oversight
- Large-scale content production workflows
- Multi-stage validation and review processes
- Enterprise-level task coordination

## API Usage

### Basic HiearchicalSwarm Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Market Research ",
        "description": "Parallel market research across different sectors",
        "swarm_type": "HiearchicalSwarm",
        "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
        "agents": [
            {
                "agent_name": "AI Market Analyst",
                "description": "Analyzes AI market trends and opportunities",
                "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Healthcare Market Analyst",
                "description": "Analyzes healthcare market trends",
                "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Fintech Market Analyst",
                "description": "Analyzes fintech market opportunities",
                "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "E-commerce Market Analyst",
                "description": "Analyzes e-commerce market trends",
                "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            }
        ],
        "max_loops": 1
    }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Market Research ",
        "description": "Parallel market research across different sectors",
        "swarm_type": "HiearchicalSwarm",
        "task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
        "agents": [
            {
                "agent_name": "AI Market Analyst",
                "description": "Analyzes AI market trends and opportunities",
                "system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Healthcare Market Analyst",
                "description": "Analyzes healthcare market trends",
                "system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Fintech Market Analyst",
                "description": "Analyzes fintech market opportunities",
                "system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "E-commerce Market Analyst",
                "description": "Analyzes e-commerce market trends",
                "system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            }
        ],
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("HiearchicalSwarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Project plan: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-JIrcIAfs2d75xrXGaAL94uWyYJ8V",
    "status": "success",
    "swarm_name": "Market Research Auto",
    "description": "Parallel market research across different sectors",
    "swarm_type": "HiearchicalSwarm",
    "output": [
        {
            "role": "System",
            "content": "These are the agents in your team. Each agent has a specific role and expertise to contribute to the team's objectives.\nTotal Agents: 4\n\nBelow is a summary of your team members and their primary responsibilities:\n| Agent Name | Description |\n|------------|-------------|\n| AI Market Analyst | Analyzes AI market trends and opportunities |\n| Healthcare Market Analyst | Analyzes healthcare market trends |\n| Fintech Market Analyst | Analyzes fintech market opportunities |\n| E-commerce Market Analyst | Analyzes e-commerce market trends |\n\nEach agent is designed to handle tasks within their area of expertise. Collaborate effectively by assigning tasks according to these roles."
        },
        {
            "role": "Director",
            "content": [
                {
                    "role": "Director",
                    "content": [
                        {
                            "function": {
                                "arguments": "{\"plan\":\"Conduct a comprehensive analysis of market opportunities in the AI, healthcare, fintech, and e-commerce sectors. Each market analyst will focus on their respective sector, gathering data on current trends, growth opportunities, and potential challenges. The findings will be compiled into a report for strategic decision-making.\",\"orders\":[{\"agent_name\":\"AI Market Analyst\",\"task\":\"Research current trends in the AI market, identify growth opportunities, and analyze potential challenges.\"},{\"agent_name\":\"Healthcare Market Analyst\",\"task\":\"Analyze the healthcare market for emerging trends, growth opportunities, and possible challenges.\"},{\"agent_name\":\"Fintech Market Analyst\",\"task\":\"Investigate the fintech sector for current trends, identify opportunities for growth, and assess challenges.\"},{\"agent_name\":\"E-commerce Market Analyst\",\"task\":\"Examine e-commerce market trends, identify growth opportunities, and analyze potential challenges.\"}]}",
                                "name": "ModelMetaclass"
                            },
                            "id": "call_GxiyzIRb2oGQXokbbkeaeVry",
                            "type": "function"
                        }
                    ]
                }
            ]
        },
        {
            "role": "AI Market Analyst",
            "content": "### AI Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the AI Market:\n\n1. **Increased Adoption Across Industries**..."
        },
        {
            "role": "Healthcare Market Analyst",
            "content": "### Healthcare Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the Healthcare Market:\n\n1. **Telehealth Expansion**..."
        },
        {
            "role": "Fintech Market Analyst",
            "content": "### Fintech Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the Fintech Market:\n\n1. **Digital Payments Proliferation**...."
        },
        {
            "role": "E-commerce Market Analyst",
            "content": "### E-commerce Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the E-commerce Market:\n\n1. **Omnichannel Retailing**...."
        },
        {
            "role": "Director",
            "content": "### Feedback for Worker Agents\n\n#### AI Market Analyst\n\n**Strengths:**\n- Comprehensive coverage of current trends, growth opportunities, and challenges in the AI market.\n- Clear categorization of insights, making it easy to follow and understand.\n\n**Weaknesses....."
        },
        {
            "role": "System",
            "content": "--- Loop 1/1 completed ---"
        }
    ],
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 94.07934331893921,
    "usage": {
        "input_tokens": 35,
        "output_tokens": 3827,
        "total_tokens": 3862,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.000105,
                "output_token_cost": 0.057405,
                "token_counts": {
                    "total_input_tokens": 35,
                    "total_output_tokens": 3827,
                    "total_tokens": 3862
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": false
            },
            "total_cost": 0.09751,
            "discount_active": false,
            "discount_type": "none",
            "discount_percentage": 0
        }
    }
}
```

## Configuration Options

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `role` | string | Agent role: "manager" or "worker" | "worker" |
| `agents` | Array<AgentSpec> | Mix of manager and worker agents | Required |
| `max_loops` | integer | Coordination rounds for managers | 1 |

## Best Practices

- Clearly define manager and worker roles using the `role` parameter
- Give managers higher `max_loops` for coordination activities
- Design worker agents with specialized, focused responsibilities
- Use for complex projects requiring oversight and coordination

## Related Swarm Types

- [SequentialWorkflow](sequential_workflow.md) - For linear task progression
- [MultiAgentRouter](multi_agent_router.md) - For intelligent task routing
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic hierarchy creation

--------------------------------------------------

# File: swarms_cloud/index.md



--------------------------------------------------

# File: swarms_cloud/launch.md

# Swarms Cloud API Client Documentation

## Overview
The Swarms Cloud API Client is a production-grade Python library for interacting with the Swarms Cloud Agent API. It provides a comprehensive interface for managing, executing, and monitoring cloud-based agents.

## Installation
```bash
pip install swarms-cloud
```

## Quick Start
```python
from swarms_cloud import SwarmCloudAPI, AgentCreate

# Initialize the client
client = SwarmCloudAPI(
    base_url="https://swarmcloud-285321057562.us-central1.run.app",
    api_key="your_api_key_here"
)

# Create an agent
agent_data = AgentCreate(
    name="TranslateAgent",
    description="Translates text between languages",
    code="""
    def main(request, store):
        text = request.payload.get('text', '')
        return f'Translated: {text}'
    """,
    requirements="requests==2.25.1",
    envs="DEBUG=True"
)

new_agent = client.create_agent(agent_data)
print(f"Created agent with ID: {new_agent.id}")
```

## Client Configuration

### Constructor Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|----------|-------------|
| base_url | str | No | https://swarmcloud-285321057562.us-central1.run.app | The base URL of the SwarmCloud API |
| api_key | str | Yes | None | Your SwarmCloud API key |
| timeout | float | No | 10.0 | Request timeout in seconds |

## Data Models

### AgentCreate
Model for creating new agents.

| Field | Type | Required | Default | Description |
|-------|------|----------|----------|-------------|
| name | str | Yes | - | Name of the agent |
| description | str | No | None | Description of the agent's purpose |
| code | str | Yes | - | Python code that defines the agent's behavior |
| requirements | str | No | None | Python package requirements (pip format) |
| envs | str | No | None | Environment variables for the agent |
| autoscaling | bool | No | False | Enable/disable concurrent execution scaling |

### AgentUpdate
Model for updating existing agents.

| Field | Type | Required | Default | Description |
|-------|------|----------|----------|-------------|
| name | str | No | None | Updated name of the agent |
| description | str | No | None | Updated description |
| code | str | No | None | Updated Python code |
| requirements | str | No | None | Updated package requirements |
| autoscaling | bool | No | None | Updated autoscaling setting |

## API Methods

### List Agents
Retrieve all available agents.

```python
agents = client.list_agents()
for agent in agents:
    print(f"Agent: {agent.name} (ID: {agent.id})")
```

**Returns**: List[AgentOut]

### Create Agent
Create a new agent with the specified configuration.

```python
agent_data = AgentCreate(
    name="DataProcessor",
    description="Processes incoming data streams",
    code="""
    def main(request, store):
        data = request.payload.get('data', [])
        return {'processed': len(data)}
    """,
    requirements="pandas==1.4.0\nnumpy==1.21.0",
    envs="PROCESSING_MODE=fast",
    autoscaling=True
)

new_agent = client.create_agent(agent_data)
```

**Returns**: AgentOut

### Get Agent
Retrieve details of a specific agent.

```python
agent = client.get_agent("agent_id_here")
print(f"Agent details: {agent}")
```

**Parameters**:
- agent_id (str): The unique identifier of the agent

**Returns**: AgentOut

### Update Agent
Update an existing agent's configuration.

```python
update_data = AgentUpdate(
    name="UpdatedProcessor",
    description="Enhanced data processing capabilities",
    code="def main(request, store):\n    return {'status': 'updated'}"
)

updated_agent = client.update_agent("agent_id_here", update_data)
```

**Parameters**:
- agent_id (str): The unique identifier of the agent
- update (AgentUpdate): The update data

**Returns**: AgentOut

### Execute Agent
Manually execute an agent with optional payload data.

```python
# Execute with payload
result = client.execute_agent(
    "agent_id_here",
    payload={"text": "Hello, World!"}
)

# Execute without payload
result = client.execute_agent("agent_id_here")
```

**Parameters**:
- agent_id (str): The unique identifier of the agent
- payload (Optional[Dict[str, Any]]): Execution payload data

**Returns**: Dict[str, Any]

### Get Agent History
Retrieve the execution history and logs for an agent.

```python
history = client.get_agent_history("agent_id_here")
for execution in history.executions:
    print(f"[{execution.timestamp}] {execution.log}")
```

**Parameters**:
- agent_id (str): The unique identifier of the agent

**Returns**: AgentExecutionHistory

### Batch Execute Agents
Execute multiple agents simultaneously with the same payload.

```python
# Get list of agents
agents = client.list_agents()

# Execute batch with payload
results = client.batch_execute_agents(
    agents=agents[:3],  # Execute first three agents
    payload={"data": "test"}
)

print(f"Batch execution results: {results}")
```

**Parameters**:
- agents (List[AgentOut]): List of agents to execute
- payload (Optional[Dict[str, Any]]): Shared execution payload

**Returns**: List[Any]

### Health Check
Check the API's health status.

```python
status = client.health()
print(f"API Status: {status}")
```

**Returns**: Dict[str, Any]

## Error Handling
The client uses exception handling to manage various error scenarios:

```python
from swarms_cloud import SwarmCloudAPI
import httpx

try:
    client = SwarmCloudAPI(api_key="your_api_key_here")
    agents = client.list_agents()
except httpx.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except Exception as err:
    print(f"An unexpected error occurred: {err}")
finally:
    client.close()
```

## Context Manager Support
The client can be used with Python's context manager:

```python
with SwarmCloudAPI(api_key="your_api_key_here") as client:
    status = client.health()
    print(f"API Status: {status}")
    # Client automatically closes after the with block
```

## Best Practices

1. Always close the client when finished:
```python
client = SwarmCloudAPI(api_key="your_api_key_here")
try:
    # Your code here
finally:
    client.close()
```

2. Use context managers for automatic cleanup:
```python
with SwarmCloudAPI(api_key="your_api_key_here") as client:
    # Your code here
```

3. Handle errors appropriately:
```python
try:
    result = client.execute_agent("agent_id", payload={"data": "test"})
except httpx.HTTPError as e:
    logger.error(f"HTTP error: {e}")
    # Handle error appropriately
```

4. Set appropriate timeouts for your use case:
```python
client = SwarmCloudAPI(
    api_key="your_api_key_here",
    timeout=30.0  # Longer timeout for complex operations
)
```

## Complete Example
Here's a complete example showcasing various features of the client:

```python
from swarms_cloud import SwarmCloudAPI, AgentCreate, AgentUpdate
import httpx

def main():
    with SwarmCloudAPI(api_key="your_api_key_here") as client:
        # Create an agent
        agent_data = AgentCreate(
            name="DataAnalyzer",
            description="Analyzes incoming data streams",
            code="""
            def main(request, store):
                data = request.payload.get('data', [])
                return {
                    'count': len(data),
                    'summary': 'Data processed successfully'
                }
            """,
            requirements="pandas==1.4.0",
            autoscaling=True
        )
        
        try:
            # Create the agent
            new_agent = client.create_agent(agent_data)
            print(f"Created agent: {new_agent.name} (ID: {new_agent.id})")
            
            # Execute the agent
            result = client.execute_agent(
                new_agent.id,
                payload={"data": [1, 2, 3, 4, 5]}
            )
            print(f"Execution result: {result}")
            
            # Update the agent
            update_data = AgentUpdate(
                description="Enhanced data analysis capabilities"
            )
            updated_agent = client.update_agent(new_agent.id, update_data)
            print(f"Updated agent: {updated_agent.name}")
            
            # Get execution history
            history = client.get_agent_history(new_agent.id)
            print(f"Execution history: {history}")
            
        except httpx.HTTPError as e:
            print(f"HTTP error occurred: {e}")
        except Exception as e:
            print(f"Unexpected error: {e}")

if __name__ == "__main__":
    main()
```

## Logging
The client uses the `loguru` library for logging. You can configure the logging level and format:

```python
from loguru import logger

# Configure logging
logger.add("swarmcloud.log", rotation="500 MB")

client = SwarmCloudAPI(api_key="your_api_key_here")
```

## Performance Considerations

1. **Connection Reuse**: The client reuses HTTP connections by default, improving performance for multiple requests.

2. **Timeout Configuration**: Set appropriate timeouts based on your use case:
```python
client = SwarmCloudAPI(
    api_key="your_api_key_here",
    timeout=5.0  # Shorter timeout for time-sensitive operations
)
```

3. **Batch Operations**: Use batch_execute_agents for multiple agent executions:
```python
results = client.batch_execute_agents(
    agents=agents,
    payload=shared_payload
)
```

## Rate Limiting
The client respects API rate limits but does not implement retry logic. Implement your own retry mechanism if needed:

```python
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def execute_with_retry(client, agent_id, payload):
    return client.execute_agent(agent_id, payload)
```

## Thread Safety
The client is not thread-safe by default. For concurrent usage, create separate client instances for each thread or implement appropriate synchronization mechanisms.

--------------------------------------------------

# File: swarms_cloud/majority_voting.md

# MajorityVoting

*Implements robust decision-making through consensus and voting*

**Swarm Type**: `MajorityVoting`

## Overview

The MajorityVoting swarm type implements robust decision-making through consensus mechanisms, ideal for tasks requiring collective intelligence or verification. Multiple agents independently analyze the same problem and vote on the best solution, ensuring high-quality, well-validated outcomes through democratic consensus.

Key features:
- **Consensus-Based Decisions**: Multiple agents vote on the best solution
- **Quality Assurance**: Reduces individual agent bias through collective input
- **Democratic Process**: Fair and transparent decision-making mechanism
- **Robust Validation**: Multiple perspectives ensure thorough analysis

## Use Cases

- Critical decision-making requiring validation
- Quality assurance and verification tasks
- Complex problem solving with multiple viable solutions
- Risk assessment and evaluation scenarios

## API Usage

### Basic MajorityVoting Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Investment Decision Voting",
        "description": "Multiple financial experts vote on investment recommendations",
        "swarm_type": "MajorityVoting",
        "task": "Evaluate whether to invest $1M in a renewable energy startup. Consider market potential, financial projections, team strength, and competitive landscape.",
        "agents": [
          {
            "agent_name": "Growth Investor",
            "description": "Focuses on growth potential and market opportunity",
            "system_prompt": "You are a growth-focused venture capitalist. Evaluate investments based on market size, scalability, and growth potential. Provide a recommendation with confidence score.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Financial Analyst",
            "description": "Analyzes financial metrics and projections",
            "system_prompt": "You are a financial analyst specializing in startups. Evaluate financial projections, revenue models, and unit economics. Provide a recommendation with confidence score.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.2
          },
          {
            "agent_name": "Technical Due Diligence",
            "description": "Evaluates technology and product viability",
            "system_prompt": "You are a technical due diligence expert. Assess technology viability, intellectual property, product-market fit, and technical risks. Provide a recommendation with confidence score.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Market Analyst",
            "description": "Analyzes market conditions and competition",
            "system_prompt": "You are a market research analyst. Evaluate market dynamics, competitive landscape, regulatory environment, and market timing. Provide a recommendation with confidence score.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Risk Assessor",
            "description": "Identifies and evaluates investment risks",
            "system_prompt": "You are a risk assessment specialist. Identify potential risks, evaluate mitigation strategies, and assess overall risk profile. Provide a recommendation with confidence score.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.2
          }
        ],
        "max_loops": 1
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Investment Decision Voting",
        "description": "Multiple financial experts vote on investment recommendations",
        "swarm_type": "MajorityVoting",
        "task": "Evaluate whether to invest $1M in a renewable energy startup. Consider market potential, financial projections, team strength, and competitive landscape.",
        "agents": [
            {
                "agent_name": "Growth Investor",
                "description": "Focuses on growth potential and market opportunity",
                "system_prompt": "You are a growth-focused venture capitalist. Evaluate investments based on market size, scalability, and growth potential. Provide a recommendation with confidence score.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Financial Analyst",
                "description": "Analyzes financial metrics and projections",
                "system_prompt": "You are a financial analyst specializing in startups. Evaluate financial projections, revenue models, and unit economics. Provide a recommendation with confidence score.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.2
            },
            {
                "agent_name": "Technical Due Diligence",
                "description": "Evaluates technology and product viability",
                "system_prompt": "You are a technical due diligence expert. Assess technology viability, intellectual property, product-market fit, and technical risks. Provide a recommendation with confidence score.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Market Analyst",
                "description": "Analyzes market conditions and competition",
                "system_prompt": "You are a market research analyst. Evaluate market dynamics, competitive landscape, regulatory environment, and market timing. Provide a recommendation with confidence score.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Risk Assessor",
                "description": "Identifies and evaluates investment risks",
                "system_prompt": "You are a risk assessment specialist. Identify potential risks, evaluate mitigation strategies, and assess overall risk profile. Provide a recommendation with confidence score.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.2
            }
        ],
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("MajorityVoting completed successfully!")
        print(f"Final decision: {result['output']['consensus_decision']}")
        print(f"Vote breakdown: {result['metadata']['vote_breakdown']}")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-1WFsSJU2KcvY11lxRMjdQNWFHArI",
    "status": "success",
    "swarm_name": "Investment Decision Voting",
    "description": "Multiple financial experts vote on investment recommendations",
    "swarm_type": "MajorityVoting",
    "output": [
        {
            "role": "Financial Analyst",
            "content": [
                "To evaluate the potential investment in a renewable energy startup, we will assess the technology viability, intellectual property, product-market fit, and technical risks, along with the additional factors of market ....."
            ]
        },
        {
            "role": "Technical Due Diligence",
            "content": [
                "To evaluate the potential investment in a renewable energy startup, we will analyze the relevant market dynamics, competitive landscape, regulatory environment, and market timing. Here's the breakdown of the assessment......."
            ]
        },
        {
            "role": "Market Analyst",
            "content": [
                "To evaluate the potential investment in a renewable energy startup, let's break down the key factors:\n\n1. **Market Potential........"
            ]
        },
        {
            "role": "Growth Investor",
            "content": [
                "To evaluate the potential investment in a renewable energy startup, we need to assess various risk factors and mitigation strategies across several key areas: market potential, financial projections, team strength, and competitive landscape.\n\n### 1. Market Potential\n**Risks:**\n- **Regulatory Changes................"
            ]
        },
        {
            "role": "Risk Assessor",
            "content": [
                "To provide a comprehensive evaluation of whether to invest $1M in the renewable energy startup, let's break down the key areas.........."
            ]
        },
        {
            "role": "Risk Assessor",
            "content": "To evaluate the potential investment in a renewable energy startup, we need to assess various risk factors and mitigation strategies across several key areas....."
        }
    ],
    "number_of_agents": 5,
    "service_tier": "standard",
    "execution_time": 61.74853563308716,
    "usage": {
        "input_tokens": 39,
        "output_tokens": 8468,
        "total_tokens": 8507,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.05,
                "input_token_cost": 0.000117,
                "output_token_cost": 0.12702,
                "token_counts": {
                    "total_input_tokens": 39,
                    "total_output_tokens": 8468,
                    "total_tokens": 8507
                },
                "num_agents": 5,
                "service_tier": "standard",
                "night_time_discount_applied": false
            },
            "total_cost": 0.177137,
            "discount_active": false,
            "discount_type": "none",
            "discount_percentage": 0
        }
    }
}
```

## Best Practices

- Use odd numbers of agents to avoid tie votes
- Design agents with different perspectives for robust evaluation
- Include confidence scores in agent prompts for weighted decisions
- Ideal for high-stakes decisions requiring validation

## Related Swarm Types

- [GroupChat](group_chat.md) - For discussion-based consensus
- [MixtureOfAgents](mixture_of_agents.md) - For diverse expertise collaboration
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured decision-making

--------------------------------------------------

# File: swarms_cloud/mcp.md

# Swarms API as MCP

- Launch MCP server as a tool
- Put `SWARMS_API_KEY` in `.env`
- Client side code below


## Server Side

```python
# server.py
from datetime import datetime
import os
from typing import Any, Dict, List, Optional

import requests
import httpx
from fastmcp import FastMCP
from pydantic import BaseModel, Field
from swarms import SwarmType
from dotenv import load_dotenv

load_dotenv()

class AgentSpec(BaseModel):
    agent_name: Optional[str] = Field(
        description="The unique name assigned to the agent, which identifies its role and functionality within the swarm.",
    )
    description: Optional[str] = Field(
        description="A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.",
    )
    system_prompt: Optional[str] = Field(
        description="The initial instruction or context provided to the agent, guiding its behavior and responses during execution.",
    )
    model_name: Optional[str] = Field(
        default="gpt-4o-mini",
        description="The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini",
    )
    auto_generate_prompt: Optional[bool] = Field(
        default=False,
        description="A flag indicating whether the agent should automatically create prompts based on the task requirements.",
    )
    max_tokens: Optional[int] = Field(
        default=8192,
        description="The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.",
    )
    temperature: Optional[float] = Field(
        default=0.5,
        description="A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.",
    )
    role: Optional[str] = Field(
        default="worker",
        description="The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.",
    )
    max_loops: Optional[int] = Field(
        default=1,
        description="The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.",
    )
    # New fields for RAG functionality
    rag_collection: Optional[str] = Field(
        None,
        description="The Qdrant collection name for RAG functionality. If provided, this agent will perform RAG queries.",
    )
    rag_documents: Optional[List[str]] = Field(
        None,
        description="Documents to ingest into the Qdrant collection for RAG. (List of text strings)",
    )
    tools: Optional[List[Dict[str, Any]]] = Field(
        None,
        description="A dictionary of tools that the agent can use to complete its task.",
    )


class AgentCompletion(BaseModel):
    """
    Configuration for a single agent that works together as a swarm to accomplish tasks.
    """

    agent: AgentSpec = Field(
        ...,
        description="The agent to run.",
    )
    task: Optional[str] = Field(
        ...,
        description="The task to run.",
    )
    img: Optional[str] = Field(
        None,
        description="An optional image URL that may be associated with the swarm's task or representation.",
    )
    output_type: Optional[str] = Field(
        "list",
        description="The type of output to return.",
    )


class AgentCompletionResponse(BaseModel):
    """
    Response from an agent completion.
    """

    agent_id: str = Field(
        ...,
        description="The unique identifier for the agent that completed the task.",
    )
    agent_name: str = Field(
        ...,
        description="The name of the agent that completed the task.",
    )
    agent_description: str = Field(
        ...,
        description="The description of the agent that completed the task.",
    )
    messages: Any = Field(
        ...,
        description="The messages from the agent completion.",
    )

    cost: Dict[str, Any] = Field(
        ...,
        description="The cost of the agent completion.",
    )


class Agents(BaseModel):
    """Configuration for a collection of agents that work together as a swarm to accomplish tasks."""

    agents: List[AgentSpec] = Field(
        description="A list containing the specifications of each agent that will participate in the swarm, detailing their roles and functionalities."
    )


class ScheduleSpec(BaseModel):
    scheduled_time: datetime = Field(
        ...,
        description="The exact date and time (in UTC) when the swarm is scheduled to execute its tasks.",
    )
    timezone: Optional[str] = Field(
        "UTC",
        description="The timezone in which the scheduled time is defined, allowing for proper scheduling across different regions.",
    )


class SwarmSpec(BaseModel):
    name: Optional[str] = Field(
        None,
        description="The name of the swarm, which serves as an identifier for the group of agents and their collective task.",
        max_length=100,
    )
    description: Optional[str] = Field(
        None,
        description="A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.",
    )
    agents: Optional[List[AgentSpec]] = Field(
        None,
        description="A list of agents or specifications that define the agents participating in the swarm.",
    )
    max_loops: Optional[int] = Field(
        default=1,
        description="The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.",
    )
    swarm_type: Optional[SwarmType] = Field(
        None,
        description="The classification of the swarm, indicating its operational style and methodology.",
    )
    rearrange_flow: Optional[str] = Field(
        None,
        description="Instructions on how to rearrange the flow of tasks among agents, if applicable.",
    )
    task: Optional[str] = Field(
        None,
        description="The specific task or objective that the swarm is designed to accomplish.",
    )
    img: Optional[str] = Field(
        None,
        description="An optional image URL that may be associated with the swarm's task or representation.",
    )
    return_history: Optional[bool] = Field(
        True,
        description="A flag indicating whether the swarm should return its execution history along with the final output.",
    )
    rules: Optional[str] = Field(
        None,
        description="Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.",
    )
    schedule: Optional[ScheduleSpec] = Field(
        None,
        description="Details regarding the scheduling of the swarm's execution, including timing and timezone information.",
    )
    tasks: Optional[List[str]] = Field(
        None,
        description="A list of tasks that the swarm should complete.",
    )
    messages: Optional[List[Dict[str, Any]]] = Field(
        None,
        description="A list of messages that the swarm should complete.",
    )
    # rag_on: Optional[bool] = Field(
    #     None,
    #     description="A flag indicating whether the swarm should use RAG.",
    # )
    # collection_name: Optional[str] = Field(
    #     None,
    #     description="The name of the collection to use for RAG.",
    # )
    stream: Optional[bool] = Field(
        False,
        description="A flag indicating whether the swarm should stream its output.",
    )


class SwarmCompletionResponse(BaseModel):
    """
    Response from a swarm completion.
    """

    status: str = Field(..., description="The status of the swarm completion.")
    swarm_name: str = Field(..., description="The name of the swarm.")
    description: str = Field(..., description="Description of the swarm.")
    swarm_type: str = Field(..., description="The type of the swarm.")
    task: str = Field(
        ..., description="The task that the swarm is designed to accomplish."
    )
    output: List[Dict[str, Any]] = Field(
        ..., description="The output generated by the swarm."
    )
    number_of_agents: int = Field(
        ..., description="The number of agents involved in the swarm."
    )
    # "input_config": Optional[Dict[str, Any]] = Field(None, description="The input configuration for the swarm.")


BASE_URL = "https://swarms-api-285321057562.us-east1.run.app"


# Create an MCP server
mcp = FastMCP("swarms-api")


# Add an addition tool
@mcp.tool(name="swarm_completion", description="Run a swarm completion.")
def swarm_completion(swarm: SwarmSpec) -> Dict[str, Any]:
    api_key = os.getenv("SWARMS_API_KEY")
    headers = {"x-api-key": api_key, "Content-Type": "application/json"}

    payload = swarm.model_dump()

    response = requests.post(f"{BASE_URL}/v1/swarm/completions", json=payload, headers=headers)
    
    return response.json()

@mcp.tool(name="swarms_available", description="Get the list of available swarms.")
async def swarms_available() -> Any:
    """
    Get the list of available swarms.
    """
    headers = {"Content-Type": "application/json"}

    async with httpx.AsyncClient() as client:
        response = await client.get(f"{BASE_URL}/v1/models/available", headers=headers)
        response.raise_for_status()  # Raise an error for bad responses
        return response.json()


if __name__ == "__main__":
    mcp.run(transport="sse")
```

## Client side

- Call the tool with it's name and the payload config

```python
import asyncio
from fastmcp import Client

swarm_config = {
    "name": "Simple Financial Analysis",
    "description": "A swarm to analyze financial data",
    "agents": [
        {
            "agent_name": "Data Analyzer",
            "description": "Looks at financial data",
            "system_prompt": "Analyze the data.",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 1000,
            "temperature": 0.5,
            "auto_generate_prompt": False,
        },
        {
            "agent_name": "Risk Analyst",
            "description": "Checks risk levels",
            "system_prompt": "Evaluate the risks.",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 1000,
            "temperature": 0.5,
            "auto_generate_prompt": False,
        },
        {
            "agent_name": "Strategy Checker",
            "description": "Validates strategies",
            "system_prompt": "Review the strategy.",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 1000,
            "temperature": 0.5,
            "auto_generate_prompt": False,
        },
    ],
    "max_loops": 1,
    "swarm_type": "SequentialWorkflow",
    "task": "Analyze the financial data and provide insights.",
    "return_history": False,  # Added required field
    "stream": False,  # Added required field
    "rules": None,  # Added optional field
    "img": None,  # Added optional field
}


async def swarm_completion():
    """Connect to a server over SSE and fetch available swarms."""

    async with Client(
        transport="http://localhost:8000/sse"
    ) as client:
        # Basic connectivity testing
        # print("Ping check:", await client.ping())
        # print("Available tools:", await client.list_tools())
        # print("Swarms available:", await client.call_tool("swarms_available", None))
        result = await client.call_tool("swarm_completion", {"swarm": swarm_config})
        print("Swarm completion:", result)


# Execute the function
if __name__ == "__main__":
    asyncio.run(swarm_completion())
```

--------------------------------------------------

# File: swarms_cloud/mcs_api.md

# Medical Coder Swarm API Documentation

Base URL: `https://mcs-285321057562.us-central1.run.app`

## Table of Contents
- [Authentication](#authentication)
- [Rate Limits](#rate-limits)
- [Endpoints](#endpoints)
  - [Health Check](#health-check)
  - [Run Medical Coder](#run-medical-coder)
  - [Run Batch Medical Coder](#run-batch-medical-coder)
  - [Get Patient Data](#get-patient-data)
  - [Get All Patients](#get-all-patients)
- [Code Examples](#code-examples)
- [Error Handling](#error-handling)

## Authentication

Authentication details will be provided by the MCS team. Contact support for API credentials.

## Rate Limits

| Endpoint | GET Rate Limit Status |
|----------|----------------------|
| `GET /rate-limits` | Returns current rate limit status for your IP address |

## Endpoints

### Health Check

Check if the API is operational.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Returns 200 OK if service is running |

### Run Medical Coder

Process a single patient case through the Medical Coder Swarm.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/medical-coder/run` | Process a single patient case |

**Request Body Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| patient_id | string | Yes | Unique identifier for the patient |
| case_description | string | Yes | Medical case details to be processed |

**Response Schema:**

| Field | Type | Description |
|-------|------|-------------|
| patient_id | string | Patient identifier |
| case_data | string | Processed case data |

### Run Batch Medical Coder

Process multiple patient cases in a single request.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/medical-coder/run-batch` | Process multiple patient cases |

**Request Body Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| cases | array | Yes | Array of PatientCase objects |

### Get Patient Data

Retrieve data for a specific patient.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/medical-coder/patient/{patient_id}` | Get patient data by ID |

**Path Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| patient_id | string | Yes | Patient identifier |

### Get All Patients

Retrieve data for all patients.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/medical-coder/patients` | Get all patient data |

## Code Examples

### Python

```python
import requests
import json

class MCSClient:
    def __init__(self, base_url="https://mcs.swarms.ai", api_key=None):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {api_key}" if api_key else None
        }

    def run_medical_coder(self, patient_id, case_description):
        endpoint = f"{self.base_url}/v1/medical-coder/run"
        payload = {
            "patient_id": patient_id,
            "case_description": case_description
        }
        response = requests.post(endpoint, json=payload, headers=self.headers)
        return response.json()

    def run_batch(self, cases):
        endpoint = f"{self.base_url}/v1/medical-coder/run-batch"
        payload = {"cases": cases}
        response = requests.post(endpoint, json=payload, headers=self.headers)
        return response.json()

# Usage example
client = MCSClient(api_key="your_api_key")
result = client.run_medical_coder("P123", "Patient presents with...")
```

### Next.js (TypeScript)

```typescript
// types.ts
interface PatientCase {
  patient_id: string;
  case_description: string;
}

interface QueryResponse {
  patient_id: string;
  case_data: string;
}

// api.ts
export class MCSApi {
  private baseUrl: string;
  private apiKey: string;

  constructor(apiKey: string, baseUrl = 'https://mcs.swarms.ai') {
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
  }

  private async fetchWithAuth(endpoint: string, options: RequestInit = {}) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${this.apiKey}`,
        ...options.headers,
      },
    });
    return response.json();
  }

  async runMedicalCoder(patientCase: PatientCase): Promise<QueryResponse> {
    return this.fetchWithAuth('/v1/medical-coder/run', {
      method: 'POST',
      body: JSON.stringify(patientCase),
    });
  }

  async getPatientData(patientId: string): Promise<QueryResponse> {
    return this.fetchWithAuth(`/v1/medical-coder/patient/${patientId}`);
  }
}

// Usage in component
const mcsApi = new MCSApi(process.env.MCS_API_KEY);

export async function ProcessPatientCase({ patientId, caseDescription }) {
  const result = await mcsApi.runMedicalCoder({
    patient_id: patientId,
    case_description: caseDescription,
  });
  return result;
}
```

### Go

```go
package mcs

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type MCSClient struct {
    BaseURL string
    APIKey  string
    Client  *http.Client
}

type PatientCase struct {
    PatientID      string `json:"patient_id"`
    CaseDescription string `json:"case_description"`
}

type QueryResponse struct {
    PatientID string `json:"patient_id"`
    CaseData  string `json:"case_data"`
}

func NewMCSClient(apiKey string) *MCSClient {
    return &MCSClient{
        BaseURL: "https://mcs.swarms.ai",
        APIKey:  apiKey,
        Client:  &http.Client{},
    }
}

func (c *MCSClient) RunMedicalCoder(patientCase PatientCase) (*QueryResponse, error) {
    payload, err := json.Marshal(patientCase)
    if err != nil {
        return nil, err
    }

    req, err := http.NewRequest("POST", 
        fmt.Sprintf("%s/v1/medical-coder/run", c.BaseURL),
        bytes.NewBuffer(payload))
    if err != nil {
        return nil, err
    }

    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey))

    resp, err := c.Client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result QueryResponse
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }

    return &result, nil
}

// Usage example
func main() {
    client := NewMCSClient("your_api_key")
    
    result, err := client.RunMedicalCoder(PatientCase{
        PatientID:      "P123",
        CaseDescription: "Patient presents with...",
    })
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Result: %+v\n", result)
}
```


## C Sharp


```txt
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

namespace MedicalCoderSwarm
{
    public class PatientCase
    {
        public string PatientId { get; set; }
        public string CaseDescription { get; set; }
    }

    public class QueryResponse
    {
        public string PatientId { get; set; }
        public string CaseData { get; set; }
    }

    public class MCSClient : IDisposable
    {
        private readonly HttpClient _httpClient;
        private readonly string _baseUrl;
        
        public MCSClient(string apiKey, string baseUrl = "https://mcs-285321057562.us-central1.run.app")
        {
            _baseUrl = baseUrl;
            _httpClient = new HttpClient();
            _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
            _httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
        }

        public async Task<QueryResponse> RunMedicalCoderAsync(string patientId, string caseDescription)
        {
            var payload = new PatientCase
            {
                PatientId = patientId,
                CaseDescription = caseDescription
            };

            var content = new StringContent(
                JsonSerializer.Serialize(payload),
                Encoding.UTF8,
                "application/json"
            );

            var response = await _httpClient.PostAsync(
                $"{_baseUrl}/v1/medical-coder/run",
                content
            );

            response.EnsureSuccessStatusCode();
            
            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<QueryResponse>(responseContent);
        }

        public async Task<QueryResponse> GetPatientDataAsync(string patientId)
        {
            var response = await _httpClient.GetAsync(
                $"{_baseUrl}/v1/medical-coder/patient/{patientId}"
            );

            response.EnsureSuccessStatusCode();
            
            var responseContent = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<QueryResponse>(responseContent);
        }

        public async Task<bool> HealthCheckAsync()
        {
            var response = await _httpClient.GetAsync($"{_baseUrl}/health");
            return response.IsSuccessStatusCode;
        }

        public void Dispose()
        {
            _httpClient?.Dispose();
        }
    }

    // Example usage
    public class Program
    {
        public static async Task Main()
        {
            try
            {
                using var client = new MCSClient("your_api_key");

                // Check API health
                var isHealthy = await client.HealthCheckAsync();
                Console.WriteLine($"API Health: {(isHealthy ? "Healthy" : "Unhealthy")}");

                // Process a single case
                var result = await client.RunMedicalCoderAsync(
                    "P123",
                    "Patient presents with acute respiratory symptoms..."
                );
                Console.WriteLine($"Processed case for patient {result.PatientId}");
                Console.WriteLine($"Case data: {result.CaseData}");

                // Get patient data
                var patientData = await client.GetPatientDataAsync("P123");
                Console.WriteLine($"Retrieved data for patient {patientData.PatientId}");
            }
            catch (HttpRequestException ex)
            {
                Console.WriteLine($"API request failed: {ex.Message}");
            }
            catch (Exception ex)
            {
                Console.WriteLine($"An error occurred: {ex.Message}");
            }
        }
    }
}

```

## Error Handling

The API uses standard HTTP status codes and returns detailed error messages in JSON format.

**Common Status Codes:**

| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid or missing API key |
| 422 | Validation Error - Request validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

**Error Response Format:**

```json
{
  "detail": [
    {
      "loc": ["body", "patient_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```


# MCS Python Client Documentation

## Installation

```bash
pip install mcs
```

## Quick Start

```python
from mcs import MCSClient, PatientCase

# Using context manager (recommended)
with MCSClient() as client:
    # Process a single case
    response = client.run_medical_coder(
        patient_id="P123",
        case_description="Patient presents with acute respiratory symptoms..."
    )
    print(f"Processed case: {response.case_data}")

    # Process multiple cases
    cases = [
        PatientCase("P124", "Case 1 description..."),
        PatientCase("P125", "Case 2 description...")
    ]
    batch_response = client.run_batch(cases)
```

## Client Configuration

### Constructor Arguments

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| api_key | str | Yes | - | Authentication API key |
| base_url | str | No | "https://mcs.swarms.ai" | API base URL |
| timeout | int | No | 30 | Request timeout in seconds |
| max_retries | int | No | 3 | Maximum retry attempts |
| logger_name | str | No | "mcs" | Name for the logger instance |

### Example Configuration

```python
client = MCSClient(
    base_url="https://custom-url.example.com",
    timeout=45,
    max_retries=5,
    logger_name="custom_logger"
)
```

## Data Models

### PatientCase

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| patient_id | str | Yes | Unique identifier for the patient |
| case_description | str | Yes | Medical case details |

### QueryResponse

| Field | Type | Description |
|-------|------|-------------|
| patient_id | str | Patient identifier |
| case_data | str | Processed case data |

## Methods

### run_medical_coder

Process a single patient case.

```python
def run_medical_coder(
    self,
    patient_id: str,
    case_description: str
) -> QueryResponse:
```

**Arguments:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| patient_id | str | Yes | Patient identifier |
| case_description | str | Yes | Case details |

**Example:**
```python
response = client.run_medical_coder(
    patient_id="P123",
    case_description="Patient presents with..."
)
print(response.case_data)
```

### run_batch

Process multiple patient cases in batch.

```python
def run_batch(
    self,
    cases: List[PatientCase]
) -> List[QueryResponse]:
```

**Arguments:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| cases | List[PatientCase] | Yes | List of patient cases |

**Example:**
```python
cases = [
    PatientCase("P124", "Case 1 description..."),
    PatientCase("P125", "Case 2 description...")
]
responses = client.run_batch(cases)
for response in responses:
    print(f"Patient {response.patient_id}: {response.case_data}")
```

### get_patient_data

Retrieve data for a specific patient.

```python
def get_patient_data(
    self,
    patient_id: str
) -> QueryResponse:
```

**Example:**
```python
patient_data = client.get_patient_data("P123")
print(f"Patient data: {patient_data.case_data}")
```

### get_all_patients

Retrieve data for all patients.

```python
def get_all_patients(self) -> List[QueryResponse]:
```

**Example:**
```python
all_patients = client.get_all_patients()
for patient in all_patients:
    print(f"Patient {patient.patient_id}: {patient.case_data}")
```

### get_rate_limits

Get current rate limit status.

```python
def get_rate_limits(self) -> Dict[str, Any]:
```

**Example:**
```python
rate_limits = client.get_rate_limits()
print(f"Rate limit status: {rate_limits}")
```

### health_check

Check if the API is operational.

```python
def health_check(self) -> bool:
```

**Example:**
```python
is_healthy = client.health_check()
print(f"API health: {'Healthy' if is_healthy else 'Unhealthy'}")
```

## Error Handling

### Exception Hierarchy

| Exception | Description |
|-----------|-------------|
| MCSClientError | Base exception for all client errors |
| RateLimitError | Raised when API rate limit is exceeded |
| AuthenticationError | Raised when API authentication fails |
| ValidationError | Raised when request validation fails |

### Example Error Handling

```python
from mcs import MCSClient, MCSClientError, RateLimitError

with MCSClient() as client:
    try:
        response = client.run_medical_coder("P123", "Case description...")
    except RateLimitError:
        print("Rate limit exceeded. Please wait before retrying.")
    except MCSClientError as e:
        print(f"An error occurred: {str(e)}")
```

## Advanced Usage

### Retry Configuration

The client implements two levels of retry logic:

1. Connection-level retries (using `HTTPAdapter`):
```python
client = MCSClient(
    ,
    max_retries=5  # Adjusts connection-level retries
)
```

2. Application-level retries (using `tenacity`):
```python
from tenacity import retry, stop_after_attempt

@retry(stop=stop_after_attempt(5))
def process_with_custom_retries():
    with MCSClient() as client:
        return client.run_medical_coder("P123", "Case description...")
```

### Batch Processing with Progress Tracking

```python
from tqdm import tqdm

with MCSClient() as client:
    cases = [
        PatientCase(f"P{i}", f"Case description {i}")
        for i in range(100)
    ]
    
    # Process in smaller batches
    batch_size = 10
    results = []
    
    for i in tqdm(range(0, len(cases), batch_size)):
        batch = cases[i:i + batch_size]
        batch_results = client.run_batch(batch)
        results.extend(batch_results)
```

## Best Practices

1. **Always use context managers:**
   ```python
   with MCSClient() as client:
       # Your code here
       pass
   ```

2. **Handle rate limits appropriately:**
   ```python
   from time import sleep
   
   def process_with_rate_limit_handling():
       with MCSClient() as client:
           try:
               return client.run_medical_coder("P123", "Case...")
           except RateLimitError:
               sleep(60)  # Wait before retry
               return client.run_medical_coder("P123", "Case...")
   ```

3. **Implement proper logging:**
   ```python
   from loguru import logger
   
   logger.add("mcs.log", rotation="500 MB")
   
   with MCSClient() as client:
       try:
           response = client.run_medical_coder("P123", "Case...")
       except Exception as e:
           logger.exception(f"Error processing case: {str(e)}")
   ```

4. **Monitor API health:**
   ```python
   def ensure_healthy_api():
       with MCSClient() as client:
           if not client.health_check():
               raise SystemExit("API is not healthy")
   ```

--------------------------------------------------

# File: swarms_cloud/migration.md

# Swarms API Documentation Has Moved 🚀

We are excited to announce that the documentation for the Swarms API has been migrated to a brand new platform: [docs.swarms.ai](https://docs.swarms.ai).

Our new documentation site offers a more beautiful, user-friendly, and streamlined experience for developers and users alike. You’ll find improved navigation, clearer guides, and up-to-date references for all Swarms Cloud API features.

**What’s new at [docs.swarms.ai](https://docs.swarms.ai)?**

- Modern, easy-to-navigate interface

- Comprehensive API reference and usage examples

- Quickstart guides and best practices

- Regular updates and new content

- Enhanced search and accessibility

If you have previously bookmarked or referenced the old documentation, please update your links to point to the new site. All future updates, new features, and support resources will be available exclusively at [docs.swarms.ai](https://docs.swarms.ai).

Thank you for being part of the Swarms community! If you have any questions or feedback about the new documentation, feel free to reach out via our [Discord](https://discord.gg/EamjgSaEQf) or [GitHub](https://github.com/kyegomez/swarms).

Happy building with Swarms!

--------------------------------------------------

# File: swarms_cloud/mixture_of_agents.md

# MixtureOfAgents

*Builds diverse teams of specialized agents for complex problem solving*

**Swarm Type**: `MixtureOfAgents`

## Overview

The MixtureOfAgents swarm type combines multiple agent types with different specializations to tackle diverse aspects of complex problems. Each agent contributes unique skills and perspectives, making this architecture ideal for tasks requiring multiple types of expertise working in harmony.

Key features:
- **Diverse Expertise**: Combines agents with different specializations
- **Collaborative Problem Solving**: Agents work together leveraging their unique strengths
- **Comprehensive Coverage**: Ensures all aspects of complex tasks are addressed
- **Balanced Perspectives**: Multiple viewpoints for robust decision-making

## Use Cases

- Complex research projects requiring multiple disciplines
- Business analysis needing various functional perspectives
- Content creation requiring different expertise areas
- Strategic planning with multiple considerations

## API Usage

### Basic MixtureOfAgents Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Business Strategy Mixture",
        "description": "Diverse team analyzing business strategy from multiple perspectives",
        "swarm_type": "MixtureOfAgents",
        "task": "Develop a comprehensive market entry strategy for a new AI product in the healthcare sector",
        "agents": [
          {
            "agent_name": "Market Research Analyst",
            "description": "Analyzes market trends and opportunities",
            "system_prompt": "You are a market research expert specializing in healthcare technology. Analyze market size, trends, and competitive landscape.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Financial Analyst",
            "description": "Evaluates financial viability and projections",
            "system_prompt": "You are a financial analyst expert. Assess financial implications, ROI, and cost structures for business strategies.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.2
          },
          {
            "agent_name": "Regulatory Expert",
            "description": "Analyzes compliance and regulatory requirements",
            "system_prompt": "You are a healthcare regulatory expert. Analyze compliance requirements, regulatory pathways, and potential barriers.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.1
          },
          {
            "agent_name": "Technology Strategist",
            "description": "Evaluates technical feasibility and strategy",
            "system_prompt": "You are a technology strategy expert. Assess technical requirements, implementation challenges, and scalability.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          }
        ],
        "max_loops": 1
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Business Strategy Mixture",
        "description": "Diverse team analyzing business strategy from multiple perspectives",
        "swarm_type": "MixtureOfAgents",
        "task": "Develop a comprehensive market entry strategy for a new AI product in the healthcare sector",
        "agents": [
            {
                "agent_name": "Market Research Analyst",
                "description": "Analyzes market trends and opportunities",
                "system_prompt": "You are a market research expert specializing in healthcare technology. Analyze market size, trends, and competitive landscape.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Financial Analyst",
                "description": "Evaluates financial viability and projections",
                "system_prompt": "You are a financial analyst expert. Assess financial implications, ROI, and cost structures for business strategies.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.2
            },
            {
                "agent_name": "Regulatory Expert",
                "description": "Analyzes compliance and regulatory requirements",
                "system_prompt": "You are a healthcare regulatory expert. Analyze compliance requirements, regulatory pathways, and potential barriers.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.1
            },
            {
                "agent_name": "Technology Strategist",
                "description": "Evaluates technical feasibility and strategy",
                "system_prompt": "You are a technology strategy expert. Assess technical requirements, implementation challenges, and scalability.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            }
        ],
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("MixtureOfAgents swarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Output: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-kBZaJg1uGTkRbLCAsGztL2jrp5Mj",
    "status": "success",
    "swarm_name": "Business Strategy Mixture",
    "description": "Diverse team analyzing business strategy from multiple perspectives",
    "swarm_type": "MixtureOfAgents",
    "output": [
        {
            "role": "System",
            "content": "Team Name: Business Strategy Mixture\nTeam Description: Diverse team analyzing business strategy from multiple perspectives\nThese are the agents in your team. Each agent has a specific role and expertise to contribute to the team's objectives.\nTotal Agents: 4\n\nBelow is a summary of your team members and their primary responsibilities:\n| Agent Name | Description |\n|------------|-------------|\n| Market Research Analyst | Analyzes market trends and opportunities |\n| Financial Analyst | Evaluates financial viability and projections |\n| Regulatory Expert | Analyzes compliance and regulatory requirements |\n| Technology Strategist | Evaluates technical feasibility and strategy |\n\nEach agent is designed to handle tasks within their area of expertise. Collaborate effectively by assigning tasks according to these roles."
        },
        {
            "role": "Market Research Analyst",
            "content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we will leverage the expertise of each team member to cover all critical aspects of the strategy. Here's how each agent will contribute......."
        },
        {
            "role": "Technology Strategist",
            "content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we'll need to collaborate effectively with the team, leveraging each member's expertise. Here's how each agent can contribute to the strategy, along with a focus on the technical requirements, implementation challenges, and scalability from the technology strategist's perspective....."
        },
        {
            "role": "Financial Analyst",
            "content": "Developing a comprehensive market entry strategy for a new AI product in the healthcare sector involves a multidisciplinary approach. Each agent in the Business Strategy Mixture team will play a crucial role in ensuring a successful market entry. Here's how the team can collaborate........"
        },
        {
            "role": "Regulatory Expert",
            "content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we need to leverage the expertise of each agent in the Business Strategy Mixture team. Below is an outline of how each team member can contribute to this strategy......"
        },
        {
            "role": "Aggregator Agent",
            "content": "As the Aggregator Agent, I've observed and analyzed the responses from the Business Strategy Mixture team regarding the development of a comprehensive market entry strategy for a new AI product in the healthcare sector. Here's a summary of the key points ......"
        }
    ],
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 30.230480670928955,
    "usage": {
        "input_tokens": 30,
        "output_tokens": 3401,
        "total_tokens": 3431,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.00009,
                "output_token_cost": 0.051015,
                "token_counts": {
                    "total_input_tokens": 30,
                    "total_output_tokens": 3401,
                    "total_tokens": 3431
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.091105,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}
```

## Best Practices

- Select agents with complementary and diverse expertise
- Ensure each agent has a clear, specialized role
- Use for complex problems requiring multiple perspectives
- Design tasks that benefit from collaborative analysis

## Related Swarm Types

- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel task execution
- [GroupChat](group_chat.md) - For collaborative discussion
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic team assembly

--------------------------------------------------

# File: swarms_cloud/multi_agent_router.md

# MultiAgentRouter

*Intelligent task dispatcher distributing work based on agent capabilities*

**Swarm Type**: `MultiAgentRouter`

## Overview

The MultiAgentRouter acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. This architecture analyzes incoming tasks and automatically routes them to the most suitable agents, optimizing both efficiency and quality of outcomes.

Key features:
- **Intelligent Routing**: Automatically assigns tasks to best-suited agents
- **Capability Matching**: Matches task requirements with agent specializations
- **Load Balancing**: Distributes workload efficiently across available agents
- **Dynamic Assignment**: Adapts routing based on agent performance and availability

## Use Cases

- Customer service request routing
- Content categorization and processing
- Technical support ticket assignment
- Multi-domain question answering

## API Usage

### Basic MultiAgentRouter Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Customer Support Router",
        "description": "Route customer inquiries to specialized support agents",
        "swarm_type": "MultiAgentRouter",
        "task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question",
        "agents": [
          {
            "agent_name": "Billing Specialist",
            "description": "Handles billing, payments, and account issues",
            "system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Technical Support",
            "description": "Resolves technical issues and troubleshooting",
            "system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.2
          },
          {
            "agent_name": "Sales Consultant",
            "description": "Provides product recommendations and sales support",
            "system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.4
          },
          {
            "agent_name": "Policy Advisor",
            "description": "Explains company policies and procedures",
            "system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.1
          }
        ],
        "max_loops": 1
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Customer Support Router",
        "description": "Route customer inquiries to specialized support agents",
        "swarm_type": "MultiAgentRouter",
        "task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question",
        "agents": [
            {
                "agent_name": "Billing Specialist",
                "description": "Handles billing, payments, and account issues",
                "system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Technical Support",
                "description": "Resolves technical issues and troubleshooting",
                "system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.2
            },
            {
                "agent_name": "Sales Consultant",
                "description": "Provides product recommendations and sales support",
                "system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.4
            },
            {
                "agent_name": "Policy Advisor",
                "description": "Explains company policies and procedures",
                "system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.1
            }
        ],
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("MultiAgentRouter completed successfully!")
        print(f"Routing decisions: {result['metadata']['routing_decisions']}")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Customer responses: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-OvOZHubprE3thzLmRdNBZAxA6om4",
    "status": "success",
    "swarm_name": "Customer Support Router",
    "description": "Route customer inquiries to specialized support agents",
    "swarm_type": "MultiAgentRouter",
    "output": [
        {
            "role": "user",
            "content": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question"
        },
        {
            "role": "Agent Router",
            "content": "selected_agent='Billing Specialist' reasoning='The task involves multiple inquiries, but the first one is about a billing question regarding an overcharge. Billing issues often require immediate attention to ensure customer satisfaction and prevent further complications. Therefore, the Billing Specialist is the most appropriate agent to handle this task. They can address the billing question directly and potentially coordinate with other agents for the remaining inquiries.' modified_task='Billing question about overcharge'"
        },
        {
            "role": "Billing Specialist",
            "content": "Of course, I'd be happy to help you with your billing question regarding an overcharge. Could you please provide me with more details about the charge in question, such as the date it occurred and the amount? This information will help me look into your account and resolve the issue as quickly as possible."
        }
    ],
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 7.800086975097656,
    "usage": {
        "input_tokens": 28,
        "output_tokens": 221,
        "total_tokens": 249,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.000084,
                "output_token_cost": 0.003315,
                "token_counts": {
                    "total_input_tokens": 28,
                    "total_output_tokens": 221,
                    "total_tokens": 249
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.043399,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}
```

## Best Practices

- Define agents with clear, distinct specializations
- Use descriptive agent names and descriptions for better routing
- Ideal for handling diverse task types that require different expertise
- Monitor routing decisions to optimize agent configurations

## Related Swarm Types

- [HierarchicalSwarm](hierarchical_swarm.md) - For structured task management
- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel task processing
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic routing setup

--------------------------------------------------

# File: swarms_cloud/phala_deploy.md

# 🔐 Swarms x Phala Deployment Guide

This guide will walk you through deploying your project to Phala's Trusted Execution Environment (TEE).

## 📋 Prerequisites

- Docker installed on your system
- A DockerHub account
- Access to Phala Cloud dashboard

## 🛡️ TEE Overview

For detailed instructions about Trusted Execution Environment setup, please refer to our [TEE Documentation](./tee/README.md).

## 🚀 Deployment Steps

### 1. Build and Publish Docker Image

```bash
# Build the Docker image
docker compose build -t <your-dockerhub-username>/swarm-agent-node:latest

# Push to DockerHub
docker push <your-dockerhub-username>/swarm-agent-node:latest
```

### 2. Deploy to Phala Cloud

Choose one of these deployment methods:
- Use [tee-cloud-cli](https://github.com/Phala-Network/tee-cloud-cli) (Recommended)
- Deploy manually via the [Phala Cloud Dashboard](https://cloud.phala.network/)

### 3. Verify TEE Attestation

Visit the [TEE Attestation Explorer](https://proof.t16z.com/) to check and verify your agent's TEE proof.

## 📝 Docker Configuration

Below is a sample Docker Compose configuration for your Swarms agent:

```yaml
services:
  swarms-agent-server:
    image: swarms-agent-node:latest
    platform: linux/amd64
    volumes:
      - /var/run/tappd.sock:/var/run/tappd.sock
      - swarms:/app
    restart: always
    ports:
      - 8000:8000
    command: # Sample MCP Server
      - /bin/sh
      - -c
      - |
        cd /app/mcp_example
        python mcp_test.py
volumes:
  swarms:
```

## 📚 Additional Resources

For more comprehensive documentation and examples, visit our [Official Documentation](https://docs.swarms.world/en/latest/).

---

> **Note**: Make sure to replace `<your-dockerhub-username>` with your actual DockerHub username when building and pushing the image.

--------------------------------------------------

# File: swarms_cloud/production_deployment.md

# Enterprise Guide to High-Performance Multi-Agent LLM Deployments
-------

As large language models (LLMs) continue to advance and enable a wide range of powerful applications, enterprises are increasingly exploring multi-agent architectures to leverage the collective capabilities of multiple LLMs. However, coordinating and optimizing the performance of these complex multi-agent systems presents significant challenges.

This comprehensive guide provides enterprise architects, engineering leaders, and technical decision-makers with a strategic framework for maximizing performance across multi-agent LLM deployments. Developed through extensive research and collaboration with industry partners, this guide distills best practices, proven techniques, and cutting-edge methodologies into seven core principles.

By implementing the recommendations outlined in this guide, organizations can achieve superior latency, throughput, and resource utilization while ensuring scalability, cost-effectiveness, and optimal user experiences. Whether powering customer-facing conversational agents, driving internal knowledge management systems, or fueling mission-critical decision support tools, high-performance multi-agent LLM deployments will be pivotal to unlocking the full potential of this transformative technology.

## Introduction

The rise of large language models (LLMs) has ushered in a new era of human-machine interaction, enabling enterprises to develop sophisticated natural language processing (NLP) applications that can understand, generate, and reason with human-like text. However, as the complexity and scale of LLM deployments grow, traditional monolithic architectures are increasingly challenged to meet the stringent performance, scalability, and cost requirements of enterprise environments.

Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLMs, have emerged as a powerful paradigm for addressing these challenges. By distributing workloads across a cohort of agents, each optimized for specific tasks or domains, multi-agent systems can deliver superior performance, resilience, and adaptability compared to single-model solutions.

However, realizing the full potential of multi-agent LLM deployments requires a strategic approach to system design, optimization, and ongoing management. This guide presents a comprehensive framework for maximizing performance across seven core principles, each underpinned by a range of proven techniques and methodologies.

Whether you are architecting a customer-facing conversational agent, building an internal knowledge management platform, or developing a mission-critical decision support system, this guide will equip you with the insights and best practices necessary to unlock the full potential of multi-agent LLM deployments within your enterprise.

## Principle 1: Distribute Token Processing
----------------------------------------

At the heart of every LLM deployment lies the fundamental challenge of optimizing token processing -- the rate at which the model consumes and generates text inputs and outputs. In multi-agent architectures, distributing and parallelizing token processing across multiple agents is a critical performance optimization strategy.

### Agent Specialization

One of the key advantages of multi-agent architectures is the ability to dedicate specific agents to specialized tasks or domains. By carefully matching agents to the workloads they are optimized for, enterprises can maximize overall throughput and minimize latency.

For example, in a conversational agent deployment, one agent may be optimized for intent recognition and query understanding, while another is fine-tuned for generating coherent, context-aware responses. In a document processing pipeline, separate agents could be dedicated to tasks such as named entity recognition, sentiment analysis, and summarization.

To effectively leverage agent specialization, enterprises should:

-   Conduct a thorough analysis of their application's workflow and identify distinct tasks or domains that could benefit from dedicated agents.
-   Evaluate the strengths and weaknesses of available LLM models and agents, and map them to the identified tasks or domains based on their capabilities and performance characteristics.
-   Implement continuous monitoring and performance tuning processes to ensure agents remain optimized for their assigned workloads as models evolve and domain requirements shift.

### Load Balancing

Even with a well-designed allocation of tasks across specialized agents, fluctuations in workload and demand can create bottlenecks and performance degradation. Effective load balancing strategies are essential to ensure that token processing capacity is dynamically distributed across available agents based on real-time conditions.

Load balancing in multi-agent LLM deployments can be accomplished through a combination of techniques, including:

-   **Round-Robin**: Distributing incoming requests across agents in a cyclical fashion, ensuring an even distribution of workload.
-   **Least Connections**: Routing requests to the agent with the fewest active connections or outstanding tasks, minimizing the risk of overloading any single agent.
-   **Response Time Monitoring**: Continuously monitoring the response times of each agent and dynamically adjusting request routing to favor faster-responding agents.
-   **Resource-Based Routing**: Factoring in agent-level resource consumption (e.g., CPU, memory) when making routing decisions, ensuring that overloaded agents are relieved of additional workload.

Implementing effective load balancing requires careful consideration of the specific characteristics and requirements of your multi-agent deployment, as well as the integration of robust monitoring and analytics capabilities to inform dynamic routing decisions.

### Horizontal Scaling

While load balancing optimizes the utilization of existing agent resources, horizontal scaling strategies enable organizations to dynamically provision additional token processing capacity to meet demand spikes or handle larger overall workloads.

In multi-agent LLM deployments, horizontal scaling can be achieved through:

-   **Agent Replication**: Spin up additional instances of existing agents to increase parallel processing capacity for specific tasks or domains.
-   **Hybrid Scaling**: Combine agent replication with the dynamic provisioning of additional compute resources (e.g., CPU, GPU) to support the increased agent count.
-   **Serverless Deployment**: Leverage serverless computing platforms (e.g., AWS Lambda, Google Cloud Functions) to automatically scale agent instances based on real-time demand, minimizing idle resource consumption.

Effective horizontal scaling requires robust orchestration and management capabilities, as well as seamless integration with load balancing mechanisms to ensure that incoming workloads are efficiently distributed across the dynamically scaled agent pool.

## Principle 2: Optimize Agent Communication
-----------------------------------------

In multi-agent LLM deployments, efficient inter-agent communication is crucial for coordinating tasks, exchanging context and intermediate results, and maintaining overall system coherence. However, communication overhead can quickly become a performance bottleneck if not carefully managed.

### Minimizing Overhead

Reducing the volume and complexity of information exchanged between agents is a key strategy for optimizing communication performance. Techniques for minimizing overhead include:

-   **Data Compression**: Applying lossless or lossy compression algorithms to reduce the size of data payloads exchanged between agents, lowering bandwidth requirements and transmission latencies.
-   **Information Summarization**: Distilling and summarizing context, results, or other data exchanged between agents to its essential elements, minimizing redundant or non-critical information.
-   **Differential Updates**: Rather than transmitting entire data payloads, agents can exchange only the differential updates or deltas required to synchronize their respective states.

Implementing these techniques requires careful analysis of the specific data exchange patterns and communication requirements within your multi-agent deployment, as well as the integration of appropriate compression, summarization, and differential update algorithms.

### Prioritizing Critical Information

In scenarios where communication bandwidth or latency constraints cannot be fully alleviated through overhead reduction techniques, enterprises can prioritize the exchange of critical information over non-essential data.

This can be achieved through:

-   **Prioritized Queuing**: Implementing queuing mechanisms that prioritize the transmission of high-priority, time-sensitive data over lower-priority, non-critical information.
-   **Selective Communication**: Dynamically determining which agents require specific pieces of information based on their roles and responsibilities, and selectively transmitting data only to those agents that truly need it.
-   **Progressive Information Exchange**: Exchanging information in a progressive or staged manner, with critical elements transmitted first, followed by supplementary or contextual data as bandwidth becomes available.

Effective prioritization requires a deep understanding of the interdependencies and information flow within your multi-agent system, as well as the ability to dynamically assess and prioritize data based on its criticality and urgency.

### Caching and Reusing Context

In many multi-agent LLM deployments, agents frequently exchange or operate on shared context, such as user profiles, conversation histories, or domain-specific knowledge bases. Caching and reusing this context information can significantly reduce redundant communication and processing overhead.

Strategies for optimizing context caching and reuse include:

-   **Agent-Level Caching**: Implementing caching mechanisms within individual agents to store and retrieve frequently accessed context data, minimizing the need for inter-agent communication.
-   **Centralized Context Management**: Deploying a dedicated context management service or data store that agents can query and update, ensuring consistent access to the latest context information across the system.
-   **Context Versioning and Invalidation**: Implementing versioning and invalidation mechanisms to ensure that cached context data remains fresh and consistent, avoiding stale or outdated information from propagating through the system.


### Principle 3: Leverage Agent Specialization
------------------------------------------

One of the key advantages of multi-agent architectures is the ability to optimize individual agents for specific tasks, domains, or capabilities. By leveraging agent specialization, enterprises can ensure that each component of their LLM system is finely tuned for maximum performance and quality.

### Task-Specific Optimization

Within a multi-agent LLM deployment, different agents may be responsible for distinct tasks such as language understanding, knowledge retrieval, response generation, or post-processing. Optimizing each agent for its designated task can yield significant performance gains and quality improvements.

Techniques for task-specific optimization include:

-   **Prompt Engineering**: Crafting carefully designed prompts that provide the necessary context, instructions, and examples to guide an agent towards optimal performance for its assigned task.
-   **Fine-Tuning**: Adapting a pre-trained LLM to a specific task or domain by fine-tuning it on a curated dataset, allowing the agent to specialize and improve its performance on that particular workload.
-   **Model Distillation**: Transferring the knowledge and capabilities of a larger, more capable LLM into a smaller, more efficient model specialized for a specific task, balancing performance and quality trade-offs.

Implementing these optimization techniques requires a deep understanding of the capabilities and requirements of each task within your multi-agent system, as well as access to relevant training data and computational resources for fine-tuning and distillation processes.

### Domain Adaptation

Many enterprise applications operate within specific domains or verticals, such as finance, healthcare, or legal. Adapting agents to these specialized domains can significantly improve their performance, accuracy, and compliance within the target domain.

Strategies for domain adaptation include:

-   **Domain-Specific Pre-Training**: Leveraging domain-specific corpora to pre-train LLM agents, imbuing them with a foundational understanding of the language, concepts, and nuances specific to the target domain.
-   **Transfer Learning**: Fine-tuning agents that have been pre-trained on general or adjacent domains, transferring their existing knowledge and capabilities to the target domain while optimizing for its specific characteristics.
-   **Domain Persona Injection**: Injecting domain-specific personas, traits, or constraints into agents during fine-tuning or deployment, shaping their behavior and outputs to align with domain-specific norms and requirements.

Effective domain adaptation requires access to high-quality, domain-specific training data, as well as close collaboration with subject matter experts to ensure that agents are properly calibrated to meet the unique demands of the target domain.

### Ensemble Techniques

In complex multi-agent deployments, individual agents may excel at specific subtasks or aspects of the overall workflow. Ensemble techniques that combine the outputs or predictions of multiple specialized agents can often outperform any single agent, leveraging the collective strengths of the ensemble.

Common ensemble techniques for multi-agent LLM systems include:

-   **Voting**: Combining the outputs or predictions of multiple agents through majority voting, weighted voting, or other consensus mechanisms.
-   **Stacking**: Training a meta-agent to combine and optimize the outputs of multiple base agents, effectively learning to leverage their collective strengths.
-   **Blending**: Combining the outputs of multiple agents through weighted averaging, linear interpolation, or other blending techniques, allowing for nuanced integration of diverse perspectives.

Implementing effective ensemble techniques requires careful analysis of the strengths, weaknesses, and complementary capabilities of individual agents, as well as the development of robust combination strategies that can optimally leverage the ensemble's collective intelligence.

### Principle 4: Implement Dynamic Scaling
--------------------------------------

The demand and workload patterns of enterprise LLM deployments can be highly dynamic, with significant fluctuations driven by factors such as user activity, data ingestion schedules, or periodic batch processing. Implementing dynamic scaling strategies allows organizations to optimally provision and allocate resources in response to these fluctuations, ensuring consistent performance while minimizing unnecessary costs.

### Autoscaling

Autoscaling is a core capability that enables the automatic adjustment of compute resources (e.g., CPU, GPU, memory) and agent instances based on real-time demand patterns and workload metrics. By dynamically scaling resources up or down, enterprises can maintain optimal performance and resource utilization, avoiding both over-provisioning and under-provisioning scenarios.

Effective autoscaling in multi-agent LLM deployments requires:

-   **Monitoring and Metrics**: Implementing robust monitoring and metrics collection mechanisms to track key performance indicators (KPIs) such as request rates, response times, resource utilization, and agent-level metrics.
-   **Scaling Policies**: Defining scaling policies that specify the conditions and thresholds for triggering automatic scaling actions, such as provisioning additional agents or compute resources when certain KPIs are breached.
-   **Scaling Orchestration**: Integrating autoscaling capabilities with resource orchestration and management tools (e.g., Kubernetes, AWS Auto Scaling) to seamlessly provision, configure, and integrate new resources into the existing multi-agent deployment.

By automating the scaling process, enterprises can respond rapidly to workload fluctuations, ensuring consistent performance and optimal resource utilization without the need for manual intervention.

### Spot Instance Utilization

Many cloud providers offer spot instances or preemptible resources at significantly discounted prices compared to on-demand or reserved instances. While these resources may be reclaimed with little notice, they can be leveraged judiciously within multi-agent LLM deployments to reduce operational costs.

Strategies for leveraging spot instances include:

-   **Fault-Tolerant Agent Deployment**: Deploying certain agents or components of the multi-agent system on spot instances, while ensuring that these components can be rapidly and seamlessly replaced or migrated in the event of instance preemption.
-   **Batch Workload Offloading**: Offloading batch processing workloads or non-time-sensitive tasks to spot instances, leveraging their cost-effectiveness while minimizing the impact of potential disruptions.
-   **Hybrid Provisioning**: Implementing a hybrid approach that combines on-demand or reserved instances for mission-critical components with spot instances for more flexible or elastic workloads.

Effective spot instance utilization requires careful architectural considerations to ensure fault tolerance and minimize the impact of potential disruptions, as well as robust monitoring and automation capabilities to seamlessly replace or migrate workloads in response to instance preemption events.

### Serverless Deployments

Serverless computing platforms, such as AWS Lambda, Google Cloud Functions, or Azure Functions, offer a compelling alternative to traditional server-based deployments. By automatically scaling compute resources based on real-time demand and charging only for the resources consumed, serverless architectures can provide significant cost savings and operational simplicity.

Leveraging serverless deployments for multi-agent LLM systems can be achieved through:

-   **Function-as-a-Service (FaaS) Agents**: Deploying individual agents or components of the multi-agent system as serverless functions, allowing for rapid and automatic scaling in response to fluctuating workloads.
-   **Event-Driven Architectures**: Designing the multi-agent system to operate in an event-driven manner, with agents triggered and executed in response to specific events or data ingestion, aligning with the serverless execution model.
-   **Hybrid Deployments**: Combining serverless components with traditional server-based components, leveraging the strengths and cost advantages of each deployment model for different aspects of the multi-agent system.

Adopting serverless architectures requires careful consideration of factors such as execution duration limits, cold start latencies, and integration with other components of the multi-agent deployment. However, when implemented effectively, serverless deployments can provide unparalleled scalability, cost-efficiency, and operational simplicity for dynamic, event-driven workloads.


### Principle 5: Employ Selective Execution
---------------------------------------

Not every input or request within a multi-agent LLM deployment requires the full execution of all agents or the complete processing pipeline. Selectively invoking agents or tasks based on input characteristics or intermediate results can significantly optimize performance by avoiding unnecessary computation and resource consumption.

### Input Filtering

Implementing input filtering mechanisms allows enterprises to reject or bypass certain inputs before they are processed by the multi-agent system. This can be achieved through techniques such as:

-   **Blacklisting/Whitelisting**: Maintaining lists of inputs (e.g., specific phrases, URLs, or content types) that should be automatically rejected or allowed, based on predefined criteria.
-   **Rules-Based Filtering**: Defining a set of rules or heuristics to assess the suitability or relevance of an input for further processing, based on factors such as language, content, or metadata.
-   **Confidence Thresholding**: Leveraging pre-processing agents or models to assess the likelihood that an input is relevant or valuable, and filtering out inputs that fall below a predetermined confidence threshold.

Effective input filtering requires careful consideration of the specific requirements, constraints, and objectives of your multi-agent deployment, as well as ongoing monitoring and adjustment of filtering rules and thresholds to maintain optimal performance and accuracy.

### Early Stopping

In many multi-agent LLM deployments, intermediate results or predictions generated by early-stage agents can be used to determine whether further processing is required or valuable. Early stopping mechanisms allow enterprises to terminate execution pipelines when specific conditions or thresholds are met, avoiding unnecessary downstream processing.

Techniques for implementing early stopping include:

-   **Confidence-Based Stopping**: Monitoring the confidence scores or probabilities associated with intermediate results, and terminating execution if a predefined confidence threshold is exceeded.
-   **Exception-Based Stopping**: Defining specific intermediate results or conditions that indicate that further processing is unnecessary or undesirable, and terminating execution upon encountering these exceptions.
-   **Adaptive Stopping**: Employing machine learning models or reinforcement learning agents to dynamically determine when to terminate execution based on learned patterns and trade-offs between accuracy, latency, and resource consumption.

Effective early stopping requires a deep understanding of the interdependencies and decision points within your multi-agent workflow, as well as careful tuning and monitoring to ensure that stopping conditions are calibrated to maintain an optimal balance between performance and accuracy.

### Conditional Branching

Rather than executing a linear, fixed pipeline of agents, conditional branching allows multi-agent systems to dynamically invoke different agents or execution paths based on input characteristics or intermediate results. This can significantly optimize resource utilization by ensuring that only the necessary agents and processes are executed for a given input or scenario.

Implementing conditional branching involves:

-   **Decision Points**: Identifying key points within the multi-agent workflow where branching decisions can be made based on input or intermediate data.
-   **Branching Logic**: Defining the rules, conditions, or machine learning models that will evaluate the input or intermediate data and determine the appropriate execution path or agent invocation.
-   **Execution Routing**: Integrating mechanisms to dynamically route inputs or intermediate data to the appropriate agents or processes based on the branching decision.

Conditional branching can be particularly effective in scenarios where inputs or workloads exhibit distinct characteristics or require significantly different processing pipelines, allowing enterprises to optimize resource allocation and minimize unnecessary computation.

### Principle 6: Optimize User Experience
-------------------------------------

While many of the principles outlined in this guide focus on optimizing backend performance and resource utilization, delivering an exceptional user experience is also a critical consideration for enterprise multi-agent LLM deployments. By minimizing perceived wait times and providing real-time progress updates, organizations can ensure that users remain engaged and satisfied, even during periods of high workload or resource constraints.

### Streaming Responses

One of the most effective techniques for minimizing perceived wait times is to stream responses or outputs to users as they are generated, rather than waiting for the entire response to be completed before delivering it. This approach is particularly valuable in conversational agents, document summarization, or other scenarios where outputs can be naturally segmented and delivered incrementally.

Implementing streaming responses requires:

-   **Partial Output Generation**: Modifying agents or models to generate and emit outputs in a streaming or incremental fashion, rather than producing the entire output in a single, monolithic operation.
-   **Streaming Data Pipelines**: Integrating streaming data pipelines and message queues to enable the efficient and reliable transmission of partial outputs from agents to user-facing interfaces or applications.
-   **Incremental Rendering**: Updating user interfaces and displays to incrementally render or populate with newly streamed output segments, providing a seamless and real-time experience for end-users.

By delivering outputs as they are generated, streaming responses can significantly improve the perceived responsiveness and interactivity of multi-agent LLM deployments, even in scenarios where the overall processing time remains unchanged.

### Progress Indicators

In cases where streaming responses may not be feasible or appropriate, providing visual or textual indicators of ongoing processing and progress can help manage user expectations and improve the overall experience. Progress indicators can be implemented through techniques such as:

-   **Loader Animations**: Displaying simple animations or spinner graphics to indicate that processing is underway and provide a sense of activity and progress.
-   **Progress Bars**: Rendering progress bars or completion indicators based on estimated or actual progress through multi-agent workflows or processing pipelines.
-   **Status Updates**: Periodically updating user interfaces with textual status messages or descriptions of the current processing stage, providing users with a more detailed understanding of the system's activities.

Effective progress indicators require careful integration with monitoring and telemetry capabilities to accurately track and communicate the progress of multi-agent workflows, as well as thoughtful user experience design to ensure that indicators are clear, unobtrusive, and aligned with user expectations.

### Chunked Delivery

In scenarios where outputs or responses cannot be effectively streamed or rendered incrementally, chunked delivery can provide a middle ground between delivering the entire output at once and streaming individual tokens or characters. By breaking larger outputs into smaller, more manageable chunks and delivering them individually, enterprises can improve perceived responsiveness and provide a more engaging user experience.

Implementing chunked delivery involves:

-   **Output Segmentation**: Identifying logical breakpoints or segmentation boundaries within larger outputs, such as paragraphs, sections, or other structural elements.
-   **Chunking Mechanisms**: Integrating mechanisms to efficiently break outputs into individual chunks and transmit or render them sequentially, with minimal delay between chunks.
-   **Chunk Rendering**: Updating user interfaces or displays to seamlessly render or append new output chunks as they are received, providing a sense of continuous progress and minimizing the perception of extended waiting periods.

Chunked delivery can be particularly effective in scenarios where outputs are inherently structured or segmented, such as document generation, report creation, or multi-step instructions or workflows.

## Principle 7: Leverage Hybrid Approaches
---------------------------------------

While multi-agent LLM architectures offer numerous advantages, they should not be viewed as a one-size-fits-all solution. In many cases, combining LLM agents with traditional techniques, optimized components, or external services can yield superior performance, cost-effectiveness, and resource utilization compared to a pure LLM-based approach.

### Task Offloading

Certain tasks or subtasks within a larger multi-agent workflow may be more efficiently handled by dedicated, optimized components or external services, rather than relying solely on LLM agents. Task offloading involves identifying these opportunities and integrating the appropriate components or services into the overall architecture.

Examples of task offloading in multi-agent LLM deployments include:

-   **Regular Expression Matching**: Offloading pattern matching or text extraction tasks to dedicated regular expression engines, which can often outperform LLM-based approaches in terms of speed and efficiency.
-   **Structured Data Processing**: Leveraging specialized data processing engines or databases for tasks involving structured data, such as querying, filtering, or transforming tabular or relational data.
-   **External APIs and Services**: Integrating with external APIs or cloud services for specific tasks, such as speech recognition, translation, or knowledge base lookup, leveraging the specialized capabilities and optimizations of these dedicated services.

Effective task offloading requires a thorough understanding of the strengths and limitations of both LLM agents and traditional components, as well as careful consideration of integration points, data flows, and performance trade-offs within the overall multi-agent architecture.

### Caching and Indexing

While LLMs excel at generating dynamic, context-aware outputs, they can be less efficient when dealing with static or frequently accessed information or knowledge. Caching and indexing strategies can help mitigate this limitation by minimizing redundant LLM processing and enabling faster retrieval of commonly accessed data.

Techniques for leveraging caching and indexing in multi-agent LLM deployments include:

**Output Caching**: Caching the outputs or responses generated by LLM agents, allowing for rapid retrieval and reuse in cases where the same or similar input is encountered in the future.

**Knowledge Base Indexing**: Indexing domain-specific knowledge bases, data repositories, or other static information sources using traditional search and information retrieval techniques. This allows LLM agents to efficiently query and incorporate relevant information into their outputs, without needing to process or generate this content from scratch.

**Contextual Caching**: Caching not only outputs but also the contextual information and intermediate results generated during multi-agent workflows. This enables more efficient reuse and continuation of previous processing in scenarios where contexts are long-lived or recurring.

Implementing effective caching and indexing strategies requires careful consideration of data freshness, consistency, and invalidation mechanisms, as well as seamless integration with LLM agents and multi-agent workflows to ensure that cached or indexed data is appropriately leveraged and updated.

### Pre-computation and Lookup

In certain scenarios, especially those involving constrained or well-defined inputs, pre-computing and lookup strategies can be leveraged to minimize or entirely avoid the need for real-time LLM processing. By generating and storing potential outputs or responses in advance, enterprises can significantly improve performance and reduce resource consumption.

Approaches for pre-computation and lookup include:

**Output Pre-generation**: For inputs or scenarios with a limited set of potential outputs, pre-generating and storing all possible responses, allowing for rapid retrieval and delivery without the need for real-time LLM execution.

**Retrieval-Based Responses**: Developing retrieval models or techniques that can identify and surface pre-computed or curated responses based on input characteristics, leveraging techniques such as nearest neighbor search, embedding-based retrieval, or example-based generation.

**Hybrid Approaches**: Combining pre-computed or retrieved responses with real-time LLM processing, allowing for the generation of dynamic, context-aware content while still leveraging pre-computed components to optimize performance and resource utilization.

Effective implementation of pre-computation and lookup strategies requires careful analysis of input patterns, output distributions, and potential performance gains, as well as robust mechanisms for managing and updating pre-computed data as application requirements or domain knowledge evolves.

# Conclusion
----------

As enterprises increasingly embrace the transformative potential of large language models, optimizing the performance, scalability, and cost-effectiveness of these deployments has become a critical imperative. Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLM agents, offer a powerful paradigm for addressing these challenges.

By implementing the seven principles outlined in this guide -- distributing token processing, optimizing agent communication, leveraging agent specialization, implementing dynamic scaling, employing selective execution, optimizing user experience, and leveraging hybrid approaches -- organizations can unlock the full potential of multi-agent LLM deployments.

However, realizing these benefits requires a strategic and holistic approach that accounts for the unique requirements, constraints, and objectives of each enterprise. From task-specific optimizations and domain adaptation to dynamic scaling and user experience considerations, maximizing the performance of multi-agent LLM systems demands a deep understanding of the underlying technologies, as well as the ability to navigate the inherent complexities of these sophisticated architectures.

To learn more about how Swarm Corporation can assist your organization in architecting, deploying, and optimizing high-performance multi-agent LLM solutions, we invite you to book a consultation with one of our agent specialists. Visit <https://calendly.com/swarm-corp/30min> to schedule a 30-minute call and explore how our expertise and cutting-edge technologies can drive transformative outcomes for your business.

In the rapidly evolving landscape of artificial intelligence and natural language processing, staying ahead of the curve is essential. Partner with Swarm Corporation, and unlock the full potential of multi-agent LLM deployments, today.

[Book a call with us now:](https://calendly.com/swarm-corp/30min)

--------------------------------------------------

# File: swarms_cloud/python_client.md

# Swarms Cloud API Client Documentation

## Introduction

The Swarms Cloud API client is a production-grade Python package for interacting with the Swarms API. It provides both synchronous and asynchronous interfaces, making it suitable for a wide range of applications from simple scripts to high-performance, scalable services.

Key features include:
- Connection pooling and efficient session management
- Automatic retries with exponential backoff
- Circuit breaker pattern for improved reliability
- In-memory caching for frequently accessed resources
- Comprehensive error handling with detailed exceptions
- Full support for asynchronous operations
- Type checking with Pydantic

This documentation covers all available client methods with detailed descriptions, parameter references, and usage examples.

## Installation

```bash
pip install swarms-client
```

## Authentication

To use the Swarms API, you need an API key. You can obtain your API key from the [Swarms Platform API Keys page](https://swarms.world/platform/api-keys).

## Client Initialization

The `SwarmsClient` is the main entry point for interacting with the Swarms API. It can be initialized with various configuration options to customize its behavior.

```python
from swarms_client import SwarmsClient

# Initialize with default settings
client = SwarmsClient(api_key="your-api-key")

# Or with custom settings
client = SwarmsClient(
    api_key="your-api-key",
    base_url="https://swarms-api-285321057562.us-east1.run.app",
    timeout=60,
    max_retries=3,
    retry_delay=1,
    log_level="INFO",
    pool_connections=100,
    pool_maxsize=100,
    keep_alive_timeout=5,
    max_concurrent_requests=100,
    circuit_breaker_threshold=5,
    circuit_breaker_timeout=60,
    enable_cache=True
)
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | Environment variable `SWARMS_API_KEY` | API key for authentication |
| `base_url` | `str` | `"https://swarms-api-285321057562.us-east1.run.app"` | Base URL for the API |
| `timeout` | `int` | `60` | Timeout for API requests in seconds |
| `max_retries` | `int` | `3` | Maximum number of retry attempts for failed requests |
| `retry_delay` | `int` | `1` | Initial delay between retries in seconds (uses exponential backoff) |
| `log_level` | `str` | `"INFO"` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| `pool_connections` | `int` | `100` | Number of connection pools to cache |
| `pool_maxsize` | `int` | `100` | Maximum number of connections to save in the pool |
| `keep_alive_timeout` | `int` | `5` | Keep-alive timeout for connections in seconds |
| `max_concurrent_requests` | `int` | `100` | Maximum number of concurrent requests |
| `circuit_breaker_threshold` | `int` | `5` | Failure threshold for the circuit breaker |
| `circuit_breaker_timeout` | `int` | `60` | Reset timeout for the circuit breaker in seconds |
| `enable_cache` | `bool` | `True` | Whether to enable in-memory caching |

## Client Methods

### clear_cache

Clears the in-memory cache used for caching API responses.

```python
client.clear_cache()
```

## Agent Resource

The Agent resource provides methods for creating and managing agent completions.

<a name="agent-create"></a>
### create

Creates an agent completion.

```python
response = client.agent.create(
    agent_config={
        "agent_name": "Researcher",
        "description": "Conducts in-depth research on topics",
        "model_name": "gpt-4o",
        "temperature": 0.7
    },
    task="Research the latest advancements in quantum computing and summarize the key findings"
)

print(f"Agent ID: {response.id}")
print(f"Output: {response.outputs}")
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_config` | `dict` or `AgentSpec` | Yes | Configuration for the agent |
| `task` | `str` | Yes | The task for the agent to complete |
| `history` | `dict` | No | Optional conversation history |

The `agent_config` parameter can include the following fields:

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `agent_name` | `str` | Required | Name of the agent |
| `description` | `str` | `None` | Description of the agent's purpose |
| `system_prompt` | `str` | `None` | System prompt to guide the agent's behavior |
| `model_name` | `str` | `"gpt-4o-mini"` | Name of the model to use |
| `auto_generate_prompt` | `bool` | `False` | Whether to automatically generate a prompt |
| `max_tokens` | `int` | `8192` | Maximum tokens in the response |
| `temperature` | `float` | `0.5` | Temperature for sampling (0-1) |
| `role` | `str` | `None` | Role of the agent |
| `max_loops` | `int` | `1` | Maximum number of reasoning loops |
| `tools_dictionary` | `List[Dict]` | `None` | Tools available to the agent |

#### Returns

`AgentCompletionResponse` object with the following properties:

- `id`: Unique identifier for the completion
- `success`: Whether the completion was successful
- `name`: Name of the agent
- `description`: Description of the agent
- `temperature`: Temperature used for the completion
- `outputs`: Output from the agent
- `usage`: Token usage information
- `timestamp`: Timestamp of the completion

<a name="agent-create_batch"></a>
### create_batch

Creates multiple agent completions in batch.

```python
responses = client.agent.create_batch([
    {
        "agent_config": {
            "agent_name": "Researcher",
            "model_name": "gpt-4o-mini",
            "temperature": 0.5
        },
        "task": "Summarize the latest quantum computing research"
    },
    {
        "agent_config": {
            "agent_name": "Writer",
            "model_name": "gpt-4o",
            "temperature": 0.7
        },
        "task": "Write a blog post about AI safety"
    }
])

for i, response in enumerate(responses):
    print(f"Agent {i+1} ID: {response.id}")
    print(f"Output: {response.outputs}")
    print("---")
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `completions` | `List[Dict or AgentCompletion]` | Yes | List of agent completion requests |

Each item in the `completions` list should have the same structure as the parameters for the `create` method.

#### Returns

List of `AgentCompletionResponse` objects with the same properties as the return value of the `create` method.

<a name="agent-acreate"></a>
### acreate

Creates an agent completion asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient(api_key="your-api-key") as client:
        response = await client.agent.acreate(
            agent_config={
                "agent_name": "Researcher",
                "description": "Conducts in-depth research",
                "model_name": "gpt-4o"
            },
            task="Research the impact of quantum computing on cryptography"
        )
        
        print(f"Agent ID: {response.id}")
        print(f"Output: {response.outputs}")

asyncio.run(main())
```

#### Parameters

Same as the `create` method.

#### Returns

Same as the `create` method.

<a name="agent-acreate_batch"></a>
### acreate_batch

Creates multiple agent completions in batch asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient(api_key="your-api-key") as client:
        responses = await client.agent.acreate_batch([
            {
                "agent_config": {
                    "agent_name": "Researcher",
                    "model_name": "gpt-4o-mini"
                },
                "task": "Summarize the latest quantum computing research"
            },
            {
                "agent_config": {
                    "agent_name": "Writer",
                    "model_name": "gpt-4o"
                },
                "task": "Write a blog post about AI safety"
            }
        ])
        
        for i, response in enumerate(responses):
            print(f"Agent {i+1} ID: {response.id}")
            print(f"Output: {response.outputs}")
            print("---")

asyncio.run(main())
```

#### Parameters

Same as the `create_batch` method.

#### Returns

Same as the `create_batch` method.

## Swarm Resource

The Swarm resource provides methods for creating and managing swarm completions.

<a name="swarm-create"></a>
### create

Creates a swarm completion.

```python
response = client.swarm.create(
    name="Research Swarm",
    description="A swarm for research tasks",
    swarm_type="SequentialWorkflow",
    task="Research quantum computing advances in 2024 and summarize the key findings",
    agents=[
        {
            "agent_name": "Researcher",
            "description": "Conducts in-depth research",
            "model_name": "gpt-4o",
            "temperature": 0.5
        },
        {
            "agent_name": "Critic",
            "description": "Evaluates arguments for flaws",
            "model_name": "gpt-4o-mini",
            "temperature": 0.3
        }
    ],
    max_loops=3,
    return_history=True
)

print(f"Job ID: {response.job_id}")
print(f"Status: {response.status}")
print(f"Output: {response.output}")
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `str` | No | Name of the swarm |
| `description` | `str` | No | Description of the swarm |
| `agents` | `List[Dict or AgentSpec]` | No | List of agent specifications |
| `max_loops` | `int` | No | Maximum number of loops (default: 1) |
| `swarm_type` | `str` | No | Type of swarm (see available types) |
| `task` | `str` | Conditional | The task to complete (required if tasks and messages are not provided) |
| `tasks` | `List[str]` | Conditional | List of tasks for batch processing (required if task and messages are not provided) |
| `messages` | `List[Dict]` | Conditional | List of messages to process (required if task and tasks are not provided) |
| `return_history` | `bool` | No | Whether to return the execution history (default: True) |
| `rules` | `str` | No | Rules for the swarm |
| `schedule` | `Dict` | No | Schedule specification for delayed execution |
| `stream` | `bool` | No | Whether to stream the response (default: False) |
| `service_tier` | `str` | No | Service tier ('standard' or 'flex', default: 'standard') |

#### Returns

`SwarmCompletionResponse` object with the following properties:

- `job_id`: Unique identifier for the job
- `status`: Status of the job
- `swarm_name`: Name of the swarm
- `description`: Description of the swarm
- `swarm_type`: Type of swarm used
- `output`: Output from the swarm
- `number_of_agents`: Number of agents in the swarm
- `service_tier`: Service tier used
- `tasks`: List of tasks processed (if applicable)
- `messages`: List of messages processed (if applicable)

<a name="swarm-create_batch"></a>
### create_batch

Creates multiple swarm completions in batch.

```python
responses = client.swarm.create_batch([
    {
        "name": "Research Swarm",
        "swarm_type": "auto",
        "task": "Research quantum computing advances",
        "agents": [
            {"agent_name": "Researcher", "model_name": "gpt-4o"}
        ]
    },
    {
        "name": "Writing Swarm",
        "swarm_type": "SequentialWorkflow",
        "task": "Write a blog post about AI safety",
        "agents": [
            {"agent_name": "Writer", "model_name": "gpt-4o"},
            {"agent_name": "Editor", "model_name": "gpt-4o-mini"}
        ]
    }
])

for i, response in enumerate(responses):
    print(f"Swarm {i+1} Job ID: {response.job_id}")
    print(f"Status: {response.status}")
    print(f"Output: {response.output}")
    print("---")
```

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `swarms` | `List[Dict or SwarmSpec]` | Yes | List of swarm specifications |

Each item in the `swarms` list should have the same structure as the parameters for the `create` method.

#### Returns

List of `SwarmCompletionResponse` objects with the same properties as the return value of the `create` method.

<a name="swarm-list_types"></a>
### list_types

Lists available swarm types.

```python
response = client.swarm.list_types()

print(f"Available swarm types:")
for swarm_type in response.swarm_types:
    print(f"- {swarm_type}")
```

#### Returns

`SwarmTypesResponse` object with the following properties:

- `success`: Whether the request was successful
- `swarm_types`: List of available swarm types

<a name="swarm-alist_types"></a>
### alist_types

Lists available swarm types asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient(api_key="your-api-key") as client:
        response = await client.swarm.alist_types()
        
        print(f"Available swarm types:")
        for swarm_type in response.swarm_types:
            print(f"- {swarm_type}")

asyncio.run(main())
```

#### Returns

Same as the `list_types` method.

<a name="swarm-acreate"></a>
### acreate

Creates a swarm completion asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient(api_key="your-api-key") as client:
        response = await client.swarm.acreate(
            name="Research Swarm",
            swarm_type="SequentialWorkflow",
            task="Research quantum computing advances in 2024",
            agents=[
                {
                    "agent_name": "Researcher",
                    "description": "Conducts in-depth research",
                    "model_name": "gpt-4o"
                },
                {
                    "agent_name": "Critic",
                    "description": "Evaluates arguments for flaws",
                    "model_name": "gpt-4o-mini"
                }
            ]
        )
        
        print(f"Job ID: {response.job_id}")
        print(f"Status: {response.status}")
        print(f"Output: {response.output}")

asyncio.run(main())
```

#### Parameters

Same as the `create` method.

#### Returns

Same as the `create` method.

<a name="swarm-acreate_batch"></a>
### acreate_batch

Creates multiple swarm completions in batch asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient(api_key="your-api-key") as client:
        responses = await client.swarm.acreate_batch([
            {
                "name": "Research Swarm",
                "swarm_type": "auto",
                "task": "Research quantum computing",
                "agents": [
                    {"agent_name": "Researcher", "model_name": "gpt-4o"}
                ]
            },
            {
                "name": "Writing Swarm",
                "swarm_type": "SequentialWorkflow",
                "task": "Write a blog post about AI safety",
                "agents": [
                    {"agent_name": "Writer", "model_name": "gpt-4o"}
                ]
            }
        ])
        
        for i, response in enumerate(responses):
            print(f"Swarm {i+1} Job ID: {response.job_id}")
            print(f"Status: {response.status}")
            print(f"Output: {response.output}")
            print("---")

asyncio.run(main())
```

#### Parameters

Same as the `create_batch` method.

#### Returns

Same as the `create_batch` method.

## Models Resource

The Models resource provides methods for retrieving information about available models.

<a name="models-list"></a>
### list

Lists available models.

```python
response = client.models.list()

print(f"Available models:")
for model in response.models:
    print(f"- {model}")
```

#### Returns

`ModelsResponse` object with the following properties:

- `success`: Whether the request was successful
- `models`: List of available model names

<a name="models-alist"></a>
### alist

Lists available models asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient(api_key="your-api-key") as client:
        response = await client.models.alist()
        
        print(f"Available models:")
        for model in response.models:
            print(f"- {model}")

asyncio.run(main())
```

#### Returns

Same as the `list` method.

## Logs Resource

The Logs resource provides methods for retrieving API request logs.

<a name="logs-list"></a>
### list

Lists API request logs.

```python
response = client.logs.list()

print(f"Found {response.count} logs:")
for log in response.logs:
    print(f"- ID: {log.id}, Created at: {log.created_at}")
    print(f"  Data: {log.data}")
```

#### Returns

`LogsResponse` object with the following properties:

- `status`: Status of the request
- `count`: Number of logs
- `logs`: List of log entries
- `timestamp`: Timestamp of the request

Each log entry is a `LogEntry` object with the following properties:

- `id`: Unique identifier for the log entry
- `api_key`: API key used for the request
- `data`: Request data
- `created_at`: Timestamp when the log entry was created

<a name="logs-alist"></a>
### alist

Lists API request logs asynchronously.

```python
import asyncio
from swarms_client import SwarmsClient

async def main():
    async with SwarmsClient() as client:
        response = await client.logs.alist()
        
        print(f"Found {response.count} logs:")
        for log in response.logs:
            print(f"- ID: {log.id}, Created at: {log.created_at}")
            print(f"  Data: {log.data}")

asyncio.run(main())
```

#### Returns

Same as the `list` method.

## Error Handling

The Swarms API client provides detailed error handling with specific exception types for different error scenarios. All exceptions inherit from the base `SwarmsError` class.

```python
from swarms_client import SwarmsClient, SwarmsError, AuthenticationError, RateLimitError, APIError

try:
    client = SwarmsClient(api_key="invalid-api-key")
    response = client.agent.create(
        agent_config={"agent_name": "Researcher", "model_name": "gpt-4o"},
        task="Research quantum computing"
    )
except AuthenticationError as e:
    print(f"Authentication error: {e}")
except RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
except APIError as e:
    print(f"API error: {e}")
except SwarmsError as e:
    print(f"Swarms error: {e}")
```

### Exception Types

| Exception | Description |
|-----------|-------------|
| `SwarmsError` | Base exception for all Swarms API errors |
| `AuthenticationError` | Raised when there's an issue with authentication |
| `RateLimitError` | Raised when the rate limit is exceeded |
| `APIError` | Raised when the API returns an error |
| `InvalidRequestError` | Raised when the request is invalid |
| `InsufficientCreditsError` | Raised when the user doesn't have enough credits |
| `TimeoutError` | Raised when a request times out |
| `NetworkError` | Raised when there's a network issue |

## Advanced Features

### Connection Pooling

The Swarms API client uses connection pooling to efficiently manage HTTP connections, which can significantly improve performance when making multiple requests.

```python
client = SwarmsClient(
    api_key="your-api-key",
    pool_connections=100,  # Number of connection pools to cache
    pool_maxsize=100,      # Maximum number of connections to save in the pool
    keep_alive_timeout=5   # Keep-alive timeout for connections in seconds
)
```

### Circuit Breaker Pattern

The client implements the circuit breaker pattern to prevent cascading failures when the API is experiencing issues.

```python
client = SwarmsClient(
    api_key="your-api-key",
    circuit_breaker_threshold=5,  # Number of failures before the circuit opens
    circuit_breaker_timeout=60    # Time in seconds before attempting to close the circuit
)
```

### Caching

The client includes in-memory caching for frequently accessed resources to reduce API calls and improve performance.

```python
client = SwarmsClient(
    api_key="your-api-key",
    enable_cache=True  # Enable in-memory caching
)

# Clear the cache manually if needed
client.clear_cache()
```

## Complete Example

Here's a complete example that demonstrates how to use the Swarms API client to create a research swarm and process its output:

```python
import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv

# Load API key from environment
load_dotenv()
api_key = os.getenv("SWARMS_API_KEY")

# Initialize client
client = SwarmsClient(api_key=api_key)

# Create a research swarm
try:
    # Define the agents
    researcher = {
        "agent_name": "Researcher",
        "description": "Conducts thorough research on specified topics",
        "model_name": "gpt-4o",
        "temperature": 0.5,
        "system_prompt": "You are a diligent researcher focused on finding accurate and comprehensive information."
    }
    
    analyst = {
        "agent_name": "Analyst",
        "description": "Analyzes research findings and identifies key insights",
        "model_name": "gpt-4o",
        "temperature": 0.3,
        "system_prompt": "You are an insightful analyst who can identify patterns and extract meaningful insights from research data."
    }
    
    summarizer = {
        "agent_name": "Summarizer",
        "description": "Creates concise summaries of complex information",
        "model_name": "gpt-4o-mini",
        "temperature": 0.4,
        "system_prompt": "You specialize in distilling complex information into clear, concise summaries."
    }
    
    # Create the swarm
    response = client.swarm.create(
        name="Quantum Computing Research Swarm",
        description="A swarm for researching and analyzing quantum computing advancements",
        swarm_type="SequentialWorkflow",
        task="Research the latest advancements in quantum computing in 2024, analyze their potential impact on cryptography and data security, and provide a concise summary of the findings.",
        agents=[researcher, analyst, summarizer],
        max_loops=2,
        return_history=True
    )
    
    # Process the response
    print(f"Job ID: {response.job_id}")
    print(f"Status: {response.status}")
    print(f"Number of agents: {response.number_of_agents}")
    print(f"Swarm type: {response.swarm_type}")
    
    # Print the output
    if "final_output" in response.output:
        print("\nFinal Output:")
        print(response.output["final_output"])
    else:
        print("\nOutput:")
        print(response.output)
    
    # Access agent-specific outputs if available
    if "agent_outputs" in response.output:
        print("\nAgent Outputs:")
        for agent, output in response.output["agent_outputs"].items():
            print(f"\n{agent}:")
            print(output)

except Exception as e:
    print(f"Error: {e}")
```

This example creates a sequential workflow swarm with three agents to research quantum computing, analyze the findings, and create a summary of the results.


--------------------------------------------------

# File: swarms_cloud/quickstart.md


# Swarms Quickstart Guide

This guide will help you get started with both single agent and multi-agent functionalities in Swarms API.

## Prerequisites

!!! info "Requirements"

    - Python 3.7+
    - API key from [Swarms Platform](https://swarms.world/platform/api-keys)
    - `requests` library for Python
    - `axios` for TypeScript/JavaScript
    - `curl` for shell commands

## Installation

=== "pip"

    ```bash
    pip install requests python-dotenv
    ```

=== "npm"

    ```bash
    npm install axios dotenv
    ```

## Authentication

!!! warning "API Key Security"

    Never hardcode your API key in your code. Always use environment variables or secure configuration management.

The API is accessible through two base URLs:

- Production: `https://api.swarms.world`
- Alternative: `https://swarms-api-285321057562.us-east1.run.app`

## Single Agent Usage

### Health Check

=== "Python"

    ```python linenums="1" title="health_check.py"
    import os
    import requests
    from dotenv import load_dotenv

    load_dotenv()
    API_KEY = os.getenv("SWARMS_API_KEY")
    BASE_URL = "https://api.swarms.world"

    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }

    response = requests.get(f"{BASE_URL}/health", headers=headers)
    print(response.json())
    ```

=== "cURL"

    ```bash title="health_check.sh"
    curl -X GET "https://api.swarms.world/health" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json"
    ```

=== "TypeScript"

    ```typescript linenums="1" title="health_check.ts"
    import axios from 'axios';
    import * as dotenv from 'dotenv';

    dotenv.config();
    const API_KEY = process.env.SWARMS_API_KEY;
    const BASE_URL = 'https://api.swarms.world';

    async function checkHealth() {
      try {
        const response = await axios.get(`${BASE_URL}/health`, {
          headers: {
            'x-api-key': API_KEY,
            'Content-Type': 'application/json'
          }
        });
        console.log(response.data);
      } catch (error) {
        console.error('Error:', error);
      }
    }

    checkHealth();
    ```

### Basic Agent

=== "Python"

    ```python linenums="1" title="single_agent.py"
    import os
    import requests
    from dotenv import load_dotenv

    load_dotenv()

    API_KEY = os.getenv("SWARMS_API_KEY")  # (1)
    BASE_URL = "https://api.swarms.world"

    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }

    def run_single_agent():
        """Run a single agent with the AgentCompletion format"""
        payload = {
            "agent_config": {
                "agent_name": "Research Analyst",  # (2)
                "description": "An expert in analyzing and synthesizing research data",
                "system_prompt": (  # (3)
                    "You are a Research Analyst with expertise in data analysis and synthesis. "
                    "Your role is to analyze provided information, identify key insights, "
                    "and present findings in a clear, structured format."
                ),
                "model_name": "claude-3-5-sonnet-20240620",  # (4)
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 1,
                "auto_generate_prompt": False,
                "tools_list_dictionary": None,
            },
            "task": "What are the key trends in renewable energy adoption?",  # (5)
        }

        response = requests.post(
            f"{BASE_URL}/v1/agent/completions",
            headers=headers,
            json=payload
        )
        return response.json()

    # Run the agent
    result = run_single_agent()
    print(result)
    ```

    1. Load API key from environment variables
    2. Give your agent a descriptive name
    3. Define the agent's capabilities and role
    4. Choose from available models
    5. Specify the task for the agent

=== "cURL"

    ```bash title="single_agent.sh"
    curl -X POST "https://api.swarms.world/v1/agent/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "agent_config": {
          "agent_name": "Research Analyst",
          "description": "An expert in analyzing and synthesizing research data",
          "system_prompt": "You are a Research Analyst with expertise in data analysis and synthesis. Your role is to analyze provided information, identify key insights, and present findings in a clear, structured format.",
          "model_name": "claude-3-5-sonnet-20240620",
          "role": "worker",
          "max_loops": 1,
          "max_tokens": 8192,
          "temperature": 1,
          "auto_generate_prompt": false,
          "tools_list_dictionary": null
        },
        "task": "What are the key trends in renewable energy adoption?"
      }'
    ```

=== "TypeScript"

    ```typescript linenums="1" title="single_agent.ts"
    import axios from 'axios';
    import * as dotenv from 'dotenv';

    dotenv.config();

    const API_KEY = process.env.SWARMS_API_KEY;
    const BASE_URL = 'https://api.swarms.world';

    interface AgentConfig {
      agent_name: string;
      description: string;
      system_prompt: string;
      model_name: string;
      role: string;
      max_loops: number;
      max_tokens: number;
      temperature: number;
      auto_generate_prompt: boolean;
      tools_list_dictionary: null | object[];
    }

    interface AgentPayload {
      agent_config: AgentConfig;
      task: string;
    }

    async function runSingleAgent() {
      const payload: AgentPayload = {
        agent_config: {
          agent_name: "Research Analyst",
          description: "An expert in analyzing and synthesizing research data",
          system_prompt: "You are a Research Analyst with expertise in data analysis and synthesis.",
          model_name: "claude-3-5-sonnet-20240620",
          role: "worker",
          max_loops: 1,
          max_tokens: 8192,
          temperature: 1,
          auto_generate_prompt: false,
          tools_list_dictionary: null
        },
        task: "What are the key trends in renewable energy adoption?"
      };

      try {
        const response = await axios.post(
          `${BASE_URL}/v1/agent/completions`,
          payload,
          {
            headers: {
              'x-api-key': API_KEY,
              'Content-Type': 'application/json'
            }
          }
        );
        return response.data;
      } catch (error) {
        console.error('Error:', error);
        throw error;
      }
    }

    // Run the agent
    runSingleAgent()
      .then(result => console.log(result))
      .catch(error => console.error(error));
    ```

### Agent with History

=== "Python"

    ```python linenums="1" title="agent_with_history.py"
    def run_agent_with_history():
        payload = {
            "agent_config": {
                "agent_name": "Conversation Agent",
                "description": "An agent that maintains conversation context",
                "system_prompt": "You are a helpful assistant that maintains context.",
                "model_name": "claude-3-5-sonnet-20240620",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.7,
                "auto_generate_prompt": False,
            },
            "task": "What's the weather like?",
            "history": [  # (1)
                {
                    "role": "user",
                    "content": "I'm planning a trip to New York."
                },
                {
                    "role": "assistant",
                    "content": "That's great! When are you planning to visit?"
                },
                {
                    "role": "user",
                    "content": "Next week."
                }
            ]
        }

        response = requests.post(
            f"{BASE_URL}/v1/agent/completions",
            headers=headers,
            json=payload
        )
        return response.json()
    ```

    1. Include conversation history for context

=== "cURL"

    ```bash title="agent_with_history.sh"
    curl -X POST "https://api.swarms.world/v1/agent/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "agent_config": {
          "agent_name": "Conversation Agent",
          "description": "An agent that maintains conversation context",
          "system_prompt": "You are a helpful assistant that maintains context.",
          "model_name": "claude-3-5-sonnet-20240620",
          "role": "worker",
          "max_loops": 1,
          "max_tokens": 8192,
          "temperature": 0.7,
          "auto_generate_prompt": false
        },
        "task": "What'\''s the weather like?",
        "history": [
          {
            "role": "user",
            "content": "I'\''m planning a trip to New York."
          },
          {
            "role": "assistant",
            "content": "That'\''s great! When are you planning to visit?"
          },
          {
            "role": "user",
            "content": "Next week."
          }
        ]
      }'
    ```

=== "TypeScript"

    ```typescript linenums="1" title="agent_with_history.ts"
    interface Message {
      role: 'user' | 'assistant';
      content: string;
    }

    interface AgentWithHistoryPayload extends AgentPayload {
      history: Message[];
    }

    async function runAgentWithHistory() {
      const payload: AgentWithHistoryPayload = {
        agent_config: {
          agent_name: "Conversation Agent",
          description: "An agent that maintains conversation context",
          system_prompt: "You are a helpful assistant that maintains context.",
          model_name: "claude-3-5-sonnet-20240620",
          role: "worker",
          max_loops: 1,
          max_tokens: 8192,
          temperature: 0.7,
          auto_generate_prompt: false,
          tools_list_dictionary: null
        },
        task: "What's the weather like?",
        history: [
          {
            role: "user",
            content: "I'm planning a trip to New York."
          },
          {
            role: "assistant",
            content: "That's great! When are you planning to visit?"
          },
          {
            role: "user",
            content: "Next week."
          }
        ]
      };

      try {
        const response = await axios.post(
          `${BASE_URL}/v1/agent/completions`,
          payload,
          {
            headers: {
              'x-api-key': API_KEY,
              'Content-Type': 'application/json'
            }
          }
        );
        return response.data;
      } catch (error) {
        console.error('Error:', error);
        throw error;
      }
    }
    ```

## Multi-Agent Swarms

!!! tip "Swarm Types"

    Swarms API supports two types of agent workflows:
    
    1. `SequentialWorkflow`: Agents work in sequence, each building on previous output
    2. `ConcurrentWorkflow`: Agents work in parallel on the same task

### Sequential Workflow

=== "Python"

    ```python linenums="1" title="sequential_swarm.py"
    def run_sequential_swarm():
        payload = {
            "name": "Financial Analysis Swarm",
            "description": "Market analysis swarm",
            "agents": [
                {
                    "agent_name": "Market Analyst",  # (1)
                    "description": "Analyzes market trends",
                    "system_prompt": "You are a financial analyst expert.",
                    "model_name": "gpt-4o",
                    "role": "worker",
                    "max_loops": 1,
                    "max_tokens": 8192,
                    "temperature": 0.5,
                    "auto_generate_prompt": False
                },
                {
                    "agent_name": "Economic Forecaster",  # (2)
                    "description": "Predicts economic trends",
                    "system_prompt": "You are an expert in economic forecasting.",
                    "model_name": "gpt-4o",
                    "role": "worker",
                    "max_loops": 1,
                    "max_tokens": 8192,
                    "temperature": 0.5,
                    "auto_generate_prompt": False
                }
            ],
            "max_loops": 1,
            "swarm_type": "SequentialWorkflow",  # (3)
            "task": "Analyze the current market conditions and provide economic forecasts."
        }

        response = requests.post(
            f"{BASE_URL}/v1/swarm/completions",
            headers=headers,
            json=payload
        )
        return response.json()
    ```

    1. First agent analyzes market trends
    2. Second agent builds on first agent's analysis
    3. Sequential workflow ensures ordered execution

=== "cURL"

    ```bash title="sequential_swarm.sh"
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Financial Analysis Swarm",
        "description": "Market analysis swarm",
        "agents": [
          {
            "agent_name": "Market Analyst",
            "description": "Analyzes market trends",
            "system_prompt": "You are a financial analyst expert.",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5,
            "auto_generate_prompt": false
          },
          {
            "agent_name": "Economic Forecaster",
            "description": "Predicts economic trends",
            "system_prompt": "You are an expert in economic forecasting.",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5,
            "auto_generate_prompt": false
          }
        ],
        "max_loops": 1,
        "swarm_type": "SequentialWorkflow",
        "task": "Analyze the current market conditions and provide economic forecasts."
      }'
    ```

=== "TypeScript"

    ```typescript linenums="1" title="sequential_swarm.ts"
    interface SwarmAgent {
      agent_name: string;
      description: string;
      system_prompt: string;
      model_name: string;
      role: string;
      max_loops: number;
      max_tokens: number;
      temperature: number;
      auto_generate_prompt: boolean;
    }

    interface SwarmPayload {
      name: string;
      description: string;
      agents: SwarmAgent[];
      max_loops: number;
      swarm_type: 'SequentialWorkflow' | 'ConcurrentWorkflow';
      task: string;
    }

    async function runSequentialSwarm() {
      const payload: SwarmPayload = {
        name: "Financial Analysis Swarm",
        description: "Market analysis swarm",
        agents: [
          {
            agent_name: "Market Analyst",
            description: "Analyzes market trends",
            system_prompt: "You are a financial analyst expert.",
            model_name: "gpt-4o",
            role: "worker",
            max_loops: 1,
            max_tokens: 8192,
            temperature: 0.5,
            auto_generate_prompt: false
          },
          {
            agent_name: "Economic Forecaster",
            description: "Predicts economic trends",
            system_prompt: "You are an expert in economic forecasting.",
            model_name: "gpt-4o",
            role: "worker",
            max_loops: 1,
            max_tokens: 8192,
            temperature: 0.5,
            auto_generate_prompt: false
          }
        ],
        max_loops: 1,
        swarm_type: "SequentialWorkflow",
        task: "Analyze the current market conditions and provide economic forecasts."
      };

      try {
        const response = await axios.post(
          `${BASE_URL}/v1/swarm/completions`,
          payload,
          {
            headers: {
              'x-api-key': API_KEY,
              'Content-Type': 'application/json'
            }
          }
        );
        return response.data;
      } catch (error) {
        console.error('Error:', error);
        throw error;
      }
    }
    ```

### Concurrent Workflow

=== "Python"

    ```python linenums="1" title="concurrent_swarm.py"
    def run_concurrent_swarm():
        payload = {
            "name": "Medical Analysis Swarm",
            "description": "Analyzes medical data concurrently",
            "agents": [
                {
                    "agent_name": "Lab Data Analyzer",  # (1)
                    "description": "Analyzes lab report data",
                    "system_prompt": "You are a medical data analyst specializing in lab results.",
                    "model_name": "claude-3-5-sonnet-20240620",
                    "role": "worker",
                    "max_loops": 1,
                    "max_tokens": 8192,
                    "temperature": 0.5,
                    "auto_generate_prompt": False
                },
                {
                    "agent_name": "Clinical Specialist",  # (2)
                    "description": "Provides clinical interpretations",
                    "system_prompt": "You are an expert in clinical diagnosis.",
                    "model_name": "claude-3-5-sonnet-20240620",
                    "role": "worker",
                    "max_loops": 1,
                    "max_tokens": 8192,
                    "temperature": 0.5,
                    "auto_generate_prompt": False
                }
            ],
            "max_loops": 1,
            "swarm_type": "ConcurrentWorkflow",  # (3)
            "task": "Analyze these lab results and provide clinical interpretations."
        }

        response = requests.post(
            f"{BASE_URL}/v1/swarm/completions",
            headers=headers,
            json=payload
        )
        return response.json()
    ```

    1. First agent processes lab data
    2. Second agent works simultaneously
    3. Concurrent workflow for parallel processing

=== "cURL"

    ```bash title="concurrent_swarm.sh"
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Medical Analysis Swarm",
        "description": "Analyzes medical data concurrently",
        "agents": [
          {
            "agent_name": "Lab Data Analyzer",
            "description": "Analyzes lab report data",
            "system_prompt": "You are a medical data analyst specializing in lab results.",
            "model_name": "claude-3-5-sonnet-20240620",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5,
            "auto_generate_prompt": false
          },
          {
            "agent_name": "Clinical Specialist",
            "description": "Provides clinical interpretations",
            "system_prompt": "You are an expert in clinical diagnosis.",
            "model_name": "claude-3-5-sonnet-20240620",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5,
            "auto_generate_prompt": false
          }
        ],
        "max_loops": 1,
        "swarm_type": "ConcurrentWorkflow",
        "task": "Analyze these lab results and provide clinical interpretations."
      }'
    ```

=== "TypeScript"

    ```typescript linenums="1" title="concurrent_swarm.ts"
    async function runConcurrentSwarm() {
      const payload: SwarmPayload = {
        name: "Medical Analysis Swarm",
        description: "Analyzes medical data concurrently",
        agents: [
          {
            agent_name: "Lab Data Analyzer",
            description: "Analyzes lab report data",
            system_prompt: "You are a medical data analyst specializing in lab results.",
            model_name: "claude-3-5-sonnet-20240620",
            role: "worker",
            max_loops: 1,
            max_tokens: 8192,
            temperature: 0.5,
            auto_generate_prompt: false
          },
          {
            agent_name: "Clinical Specialist",
            description: "Provides clinical interpretations",
            system_prompt: "You are an expert in clinical diagnosis.",
            model_name: "claude-3-5-sonnet-20240620",
            role: "worker",
            max_loops: 1,
            max_tokens: 8192,
            temperature: 0.5,
            auto_generate_prompt: false
          }
        ],
        max_loops: 1,
        swarm_type: "ConcurrentWorkflow",
        task: "Analyze these lab results and provide clinical interpretations."
      };

      try {
        const response = await axios.post(
          `${BASE_URL}/v1/swarm/completions`,
          payload,
          {
            headers: {
              'x-api-key': API_KEY,
              'Content-Type': 'application/json'
            }
          }
        );
        return response.data;
      } catch (error) {
        console.error('Error:', error);
        throw error;
      }
    }
    ```

### Batch Processing

!!! example "Batch Processing"

    Process multiple swarms in a single request for improved efficiency.

=== "Python"

    ```python linenums="1" title="batch_swarms.py"
    def run_batch_swarms():
        payload = [
            {
                "name": "Batch Swarm 1",
                "description": "First swarm in batch",
                "agents": [
                    {
                        "agent_name": "Research Agent",
                        "description": "Conducts research",
                        "system_prompt": "You are a research assistant.",
                        "model_name": "gpt-4",
                        "role": "worker",
                        "max_loops": 1
                    },
                    {
                        "agent_name": "Analysis Agent",
                        "description": "Analyzes data",
                        "system_prompt": "You are a data analyst.",
                        "model_name": "gpt-4",
                        "role": "worker",
                        "max_loops": 1
                    }
                ],
                "max_loops": 1,
                "swarm_type": "SequentialWorkflow",
                "task": "Research AI advancements."
            }
        ]

        response = requests.post(
            f"{BASE_URL}/v1/swarm/batch/completions",
            headers=headers,
            json=payload
        )
        return response.json()
    ```

=== "cURL"

    ```bash title="batch_swarms.sh"
    curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '[
        {
          "name": "Batch Swarm 1",
          "description": "First swarm in batch",
          "agents": [
            {
              "agent_name": "Research Agent",
              "description": "Conducts research",
              "system_prompt": "You are a research assistant.",
              "model_name": "gpt-4",
              "role": "worker",
              "max_loops": 1
            },
            {
              "agent_name": "Analysis Agent",
              "description": "Analyzes data",
              "system_prompt": "You are a data analyst.",
              "model_name": "gpt-4",
              "role": "worker",
              "max_loops": 1
            }
          ],
          "max_loops": 1,
          "swarm_type": "SequentialWorkflow",
          "task": "Research AI advancements."
        }
      ]'
    ```

=== "TypeScript"

    ```typescript linenums="1" title="batch_swarms.ts"
    async function runBatchSwarms() {
      const payload: SwarmPayload[] = [
        {
          name: "Batch Swarm 1",
          description: "First swarm in batch",
          agents: [
            {
              agent_name: "Research Agent",
              description: "Conducts research",
              system_prompt: "You are a research assistant.",
              model_name: "gpt-4",
              role: "worker",
              max_loops: 1,
              max_tokens: 8192,
              temperature: 0.7,
              auto_generate_prompt: false
            },
            {
              agent_name: "Analysis Agent",
              description: "Analyzes data",
              system_prompt: "You are a data analyst.",
              model_name: "gpt-4",
              role: "worker",
              max_loops: 1,
              max_tokens: 8192,
              temperature: 0.7,
              auto_generate_prompt: false
            }
          ],
          max_loops: 1,
          swarm_type: "SequentialWorkflow",
          task: "Research AI advancements."
        }
      ];

      try {
        const response = await axios.post(
          `${BASE_URL}/v1/swarm/batch/completions`,
          payload,
          {
            headers: {
              'x-api-key': API_KEY,
              'Content-Type': 'application/json'
            }
          }
        );
        return response.data;
      } catch (error) {
        console.error('Error:', error);
        throw error;
      }
    }
    ```

## Advanced Features

### Tools Integration

!!! note "Tools"

    Enhance agent capabilities by providing them with specialized tools.

=== "Python"

    ```python linenums="1" title="tools_example.py"
    def run_agent_with_tools():
        tools_dictionary = [
            {
                "type": "function",
                "function": {
                    "name": "search_topic",
                    "description": "Conduct an in-depth search on a topic",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "depth": {
                                "type": "integer",
                                "description": "Search depth (1-3)"
                            },
                            "detailed_queries": {
                                "type": "array",
                                "description": "Specific search queries",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "required": ["depth", "detailed_queries"]
                    }
                }
            }
        ]

        payload = {
            "agent_config": {
                "agent_name": "Research Assistant",
                "description": "Expert in research with search capabilities",
                "system_prompt": "You are a research assistant with search capabilities.",
                "model_name": "gpt-4",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.7,
                "auto_generate_prompt": False,
                "tools_dictionary": tools_dictionary
            },
            "task": "Research the latest developments in quantum computing."
        }

        response = requests.post(
            f"{BASE_URL}/v1/agent/completions",
            headers=headers,
            json=payload
        )
        return response.json()
    ```

=== "cURL"

    ```bash title="tools_example.sh"
    curl -X POST "https://api.swarms.world/v1/agent/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "agent_config": {
          "agent_name": "Research Assistant",
          "description": "Expert in research with search capabilities",
          "system_prompt": "You are a research assistant with search capabilities.",
          "model_name": "gpt-4",
          "role": "worker",
          "max_loops": 1,
          "max_tokens": 8192,
          "temperature": 0.7,
          "auto_generate_prompt": false,
          "tools_dictionary": [
            {
              "type": "function",
              "function": {
                "name": "search_topic",
                "description": "Conduct an in-depth search on a topic",
                "parameters": {
                  "type": "object",
                  "properties": {
                    "depth": {
                      "type": "integer",
                      "description": "Search depth (1-3)"
                    },
                    "detailed_queries": {
                      "type": "array",
                      "description": "Specific search queries",
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "required": ["depth", "detailed_queries"]
                }
              }
            }
          ]
        },
        "task": "Research the latest developments in quantum computing."
      }'
    ```

=== "TypeScript"

    ```typescript linenums="1" title="tools_example.ts"
    interface ToolFunction {
      name: string;
      description: string;
      parameters: {
        type: string;
        properties: {
          [key: string]: {
            type: string;
            description: string;
            items?: {
              type: string;
            };
          };
        };
        required: string[];
      };
    }

    interface Tool {
      type: string;
      function: ToolFunction;
    }

    interface AgentWithToolsConfig extends AgentConfig {
      tools_dictionary: Tool[];
    }

    interface AgentWithToolsPayload {
      agent_config: AgentWithToolsConfig;
      task: string;
    }

    async function runAgentWithTools() {
      const toolsDictionary: Tool[] = [
        {
          type: "function",
          function: {
            name: "search_topic",
            description: "Conduct an in-depth search on a topic",
            parameters: {
              type: "object",
              properties: {
                depth: {
                  type: "integer",
                  description: "Search depth (1-3)"
                },
                detailed_queries: {
                  type: "array",
                  description: "Specific search queries",
                  items: {
                    type: "string"
                  }
                }
              },
              required: ["depth", "detailed_queries"]
            }
          }
        }
      ];

      const payload: AgentWithToolsPayload = {
        agent_config: {
          agent_name: "Research Assistant",
          description: "Expert in research with search capabilities",
          system_prompt: "You are a research assistant with search capabilities.",
          model_name: "gpt-4",
          role: "worker",
          max_loops: 1,
          max_tokens: 8192,
          temperature: 0.7,
          auto_generate_prompt: false,
          tools_dictionary: toolsDictionary
        },
        task: "Research the latest developments in quantum computing."
      };

      try {
        const response = await axios.post(
          `${BASE_URL}/v1/agent/completions`,
          payload,
          {
            headers: {
              'x-api-key': API_KEY,
              'Content-Type': 'application/json'
            }
          }
        );
        return response.data;
      } catch (error) {
        console.error('Error:', error);
        throw error;
      }
    }
    ```

### Available Models

!!! info "Supported Models"

    Choose the right model for your use case:

    === "OpenAI"
        - `gpt-4`
        - `gpt-4o`
        - `gpt-4o-mini`

    === "Anthropic"
        - `claude-3-5-sonnet-20240620`
        - `claude-3-7-sonnet-latest`

    === "Groq"
        - `groq/llama3-70b-8192`
        - `groq/deepseek-r1-distill-llama-70b`

## Best Practices

!!! danger "Security"
    Never commit API keys or sensitive credentials to version control.

!!! warning "Rate Limits"
    Implement proper rate limiting and error handling in production.

!!! tip "Testing"
    Start with simple tasks and gradually increase complexity.

=== "Python"

    ```python linenums="1" title="best_practices.py"
    # Error Handling
    try:
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")

    # Rate Limiting
    import time
    from tenacity import retry, wait_exponential

    @retry(wait=wait_exponential(multiplier=1, min=4, max=10))
    def make_api_call():
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
        return response

    # Input Validation
    def validate_payload(payload):
        required_fields = ["agent_config", "task"]
        if not all(field in payload for field in required_fields):
            raise ValueError("Missing required fields")
    ```

=== "TypeScript"

    ```typescript linenums="1" title="best_practices.ts"
    // Error Handling
    try {
      const response = await axios.post(url, payload, { headers });
    } catch (error) {
      if (axios.isAxiosError(error)) {
        console.error('API Error:', error.response?.data);
      }
      throw error;
    }

    // Rate Limiting
    import { rateLimit } from 'axios-rate-limit';

    const http = rateLimit(axios.create(), { 
      maxRequests: 2,
      perMilliseconds: 1000
    });

    // Input Validation
    function validatePayload(payload: unknown): asserts payload is AgentPayload {
      if (!payload || typeof payload !== 'object') {
        throw new Error('Invalid payload');
      }

      const { agent_config, task } = payload as Partial<AgentPayload>;
      
      if (!agent_config || !task) {
        throw new Error('Missing required fields');
      }
    }
    ```

## Connect With Us

Join our community of agent engineers and researchers for technical support, cutting-edge updates, and exclusive access to world-class agent engineering insights!

| Platform | Description | Link |
|----------|-------------|------|
| 📚 Documentation | Official documentation and guides | [docs.swarms.world](https://docs.swarms.world) |
| 📝 Blog | Latest updates and technical articles | [Medium](https://medium.com/@kyeg) |
| 💬 Discord | Live chat and community support | [Join Discord](https://discord.gg/EamjgSaEQf) |
| 🐦 Twitter | Latest news and announcements | [@kyegomez](https://twitter.com/kyegomez) |
| 👥 LinkedIn | Professional network and updates | [The Swarm Corporation](https://www.linkedin.com/company/the-swarm-corporation) |
| 📺 YouTube | Tutorials and demos | [Swarms Channel](https://www.youtube.com/channel/UC9yXyitkbU_WSy7bd_41SqQ) |
| 🎫 Events | Join our community events | [Sign up here](https://lu.ma/5p2jnc2v) |
| 🚀 Onboarding Session | Get onboarded with Kye Gomez, creator and lead maintainer of Swarms | [Book Session](https://cal.com/swarms/swarms-onboarding-session) |

--------------------------------------------------

# File: swarms_cloud/rate_limits.md

# Swarms API Rate Limits 

The Swarms API implements a comprehensive rate limiting system that tracks API requests across multiple time windows and enforces various limits to ensure fair usage and system stability.

## Rate Limits Summary

| Rate Limit Type | Free Tier | Premium Tier | Time Window | Description |
|----------------|-----------|--------------|-------------|-------------|
| **Requests per Minute** | 100 | 2,000 | 1 minute | Maximum API calls per minute |
| **Requests per Hour** | 50 | 10,000 | 1 hour | Maximum API calls per hour |
| **Requests per Day** | 1,200 | 100,000 | 24 hours | Maximum API calls per day |
| **Tokens per Agent** | 200,000 | 2,000,000 | Per request | Maximum tokens per agent |
| **Prompt Length** | 200,000 | 200,000 | Per request | Maximum input tokens per request |
| **Batch Size** | 10 | 10 | Per request | Maximum agents in batch requests |
| **IP-based Fallback** | 100 | 100 | 60 seconds | For requests without API keys |

## Detailed Rate Limit Explanations

### 1. **Request Rate Limits**

These limits control how many API calls you can make within specific time windows.

#### **Per-Minute Limit**

| Tier         | Requests per Minute | Reset Interval         | Applies To         |
|--------------|--------------------|------------------------|--------------------|
| Free         | 100                | Every minute (sliding) | All API endpoints  |
| Premium      | 2,000              | Every minute (sliding) | All API endpoints  |

#### **Per-Hour Limit**

- **Free Tier**: 50 requests per hour
- **Premium Tier**: 10,000 requests per hour
- **Reset**: Every hour (sliding window)
- **Applies to**: All API endpoints

#### **Per-Day Limit**

- **Free Tier**: 1,200 requests per day (50 × 24)

- **Premium Tier**: 100,000 requests per day

- **Reset**: Every 24 hours (sliding window)

- **Applies to**: All API endpoints

### 2. **Token Limits**

These limits control the amount of text processing allowed per request.

#### **Tokens per Agent**

- **Free Tier**: 200,000 tokens per agent

- **Premium Tier**: 2,000,000 tokens per agent

- **Applies to**: Individual agent configurations

- **Includes**: System prompts, task descriptions, and agent names

#### **Prompt Length Limit**

- **All Tiers**: 200,000 tokens maximum

- **Applies to**: Combined input text (task + history + system prompts)

- **Error**: Returns 400 error if exceeded

- **Message**: "Prompt is too long. Please provide a prompt that is less than 10000 tokens."

### 3. **Batch Processing Limits**

These limits control concurrent processing capabilities.

#### **Batch Size Limit**

- **All Tiers**: 10 agents maximum per batch

- **Applies to**: `/v1/agent/batch/completions` endpoint

- **Error**: Returns 400 error if exceeded

- **Message**: "ERROR: BATCH SIZE EXCEEDED - You can only run up to 10 batch agents at a time."

## How Rate Limiting Works

### Database-Based Tracking

The system uses a database-based approach for API key requests:

1. **Request Logging**: Every API request is logged to the `swarms_api_logs` table
2. **Time Window Queries**: The system queries for requests in the last minute, hour, and day
3. **Limit Comparison**: Current counts are compared against configured limits
4. **Request Blocking**: Requests are blocked if any limit is exceeded

### Sliding Windows

Rate limits use sliding windows rather than fixed windows:

- **Minute**: Counts requests in the last 60 seconds

- **Hour**: Counts requests in the last 60 minutes  

- **Day**: Counts requests in the last 24 hours

This provides more accurate rate limiting compared to fixed time windows.

## Checking Your Rate Limits

### API Endpoint

Use the `/v1/rate/limits` endpoint to check your current usage:

```bash
curl -H "x-api-key: your-api-key" \
     https://api.swarms.world/v1/rate/limits
```

### Response Format

```json
{
  "success": true,
  "rate_limits": {
    "minute": {
      "count": 5,
      "limit": 100,
      "exceeded": false,
      "remaining": 95,
      "reset_time": "2024-01-15T10:30:00Z"
    },
    "hour": {
      "count": 25,
      "limit": 50,
      "exceeded": false,
      "remaining": 25,
      "reset_time": "2024-01-15T11:00:00Z"
    },
    "day": {
      "count": 150,
      "limit": 1200,
      "exceeded": false,
      "remaining": 1050,
      "reset_time": "2024-01-16T10:00:00Z"
    }
  },
  "limits": {
    "maximum_requests_per_minute": 100,
    "maximum_requests_per_hour": 50,
    "maximum_requests_per_day": 1200,
    "tokens_per_agent": 200000
  },
  "timestamp": "2024-01-15T10:29:30Z"
}
```

## Handling Rate Limit Errors

### Error Response

When rate limits are exceeded, you'll receive a 429 status code:

```json
{
  "detail": "Rate limit exceeded for minute window(s). Upgrade to Premium for increased limits (2,000/min, 10,000/hour, 100,000/day) at https://swarms.world/platform/account for just $99/month."
}
```

### Best Practices

1. **Monitor Usage**: Regularly check your rate limits using the `/v1/rate/limits` endpoint
2. **Implement Retry Logic**: Use exponential backoff when hitting rate limits
3. **Optimize Requests**: Combine multiple operations into single requests when possible
4. **Upgrade When Needed**: Consider upgrading to Premium for higher limits

## Premium Tier Benefits

Upgrade to Premium for significantly higher limits:

- **20x more requests per minute** (2,000 vs 100)

- **200x more requests per hour** (10,000 vs 50)

- **83x more requests per day** (100,000 vs 1,200)

- **10x more tokens per agent** (2M vs 200K)

Visit [Swarms Platform Account](https://swarms.world/platform/account) to upgrade for just $99/month.

## Performance Considerations

- Database queries are optimized to only count request IDs
- Rate limit checks are cached per request
- Fallback mechanisms ensure system reliability
- Minimal impact on request latency
- Persistent tracking across server restarts 

--------------------------------------------------

# File: swarms_cloud/rust_client.md

# Swarms Client - Production Grade Rust SDK

A high-performance, production-ready Rust client for the Swarms API with comprehensive features for building multi-agent AI systems.

## Features

- **🚀 High Performance**: Built with `reqwest` and `tokio` for maximum throughput
- **🔄 Connection Pooling**: Automatic HTTP connection reuse and pooling
- **⚡ Circuit Breaker**: Automatic failure detection and recovery
- **💾 Intelligent Caching**: TTL-based in-memory caching with concurrent access
- **📊 Rate Limiting**: Configurable concurrent request limits
- **🔄 Retry Logic**: Exponential backoff with jitter
- **📝 Comprehensive Logging**: Structured logging with `tracing`
- **✅ Type Safety**: Full compile-time type checking with `serde`

## Installation

Install `swarms-rs` globally using cargo:

```bash
cargo install swarms-rs
```





## Quick Start

```rust
use swarms_client::SwarmsClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the client with API key from environment
    let client = SwarmsClient::builder()
        .unwrap()
        .from_env()?  // Loads API key from SWARMS_API_KEY environment variable
        .timeout(std::time::Duration::from_secs(60))
        .max_retries(3)
        .build()?;

    // Make a simple swarm completion request
    let response = client.swarm()
        .completion()
        .name("My First Swarm")
        .swarm_type(SwarmType::Auto)
        .task("Analyze the pros and cons of quantum computing")
        .agent(|agent| {
            agent
                .name("Researcher")
                .description("Conducts in-depth research")
                .model("gpt-4o")
        })
        .send()
        .await?;

    println!("Swarm output: {}", response.output);
    Ok(())
}
```

## API Reference

### SwarmsClient

The main client for interacting with the Swarms API.

#### Constructor Methods

##### `SwarmsClient::builder()`

Creates a new client builder for configuring the client.

**Returns**: `Result<ClientBuilder, SwarmsError>`

**Example**:
```rust
let client = SwarmsClient::builder()
    .unwrap()
    .api_key("your-api-key")
    .timeout(Duration::from_secs(60))
    .build()?;
```

##### `SwarmsClient::with_config(config: ClientConfig)`

Creates a client with custom configuration.

| Parameter | Type | Description |
|-----------|------|-------------|
| `config` | `ClientConfig` | Client configuration settings |

**Returns**: `Result<SwarmsClient, SwarmsError>`

**Example**:
```rust
let config = ClientConfig {
    api_key: "your-api-key".to_string(),
    base_url: "https://api.swarms.com/".parse().unwrap(),
    timeout: Duration::from_secs(120),
    max_retries: 5,
    ..Default::default()
};

let client = SwarmsClient::with_config(config)?;
```

#### Resource Access Methods

| Method | Returns | Description |
|--------|---------|-------------|
| `agent()` | `AgentResource` | Access agent-related operations |
| `swarm()` | `SwarmResource` | Access swarm-related operations |
| `models()` | `ModelsResource` | Access model listing operations |
| `logs()` | `LogsResource` | Access logging operations |

#### Cache Management Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `clear_cache()` | None | `()` | Clears all cached responses |
| `cache_stats()` | None | `Option<(usize, usize)>` | Returns (valid_entries, total_entries) |

### ClientBuilder

Builder for configuring the Swarms client.

#### Configuration Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `new()` | None | `ClientBuilder` | Creates a new builder with defaults |
| `from_env()` | None | `Result<ClientBuilder, SwarmsError>` | Loads API key from environment |
| `api_key(key)` | `String` | `ClientBuilder` | Sets the API key |
| `base_url(url)` | `&str` | `Result<ClientBuilder, SwarmsError>` | Sets the base URL |
| `timeout(duration)` | `Duration` | `ClientBuilder` | Sets request timeout |
| `max_retries(count)` | `usize` | `ClientBuilder` | Sets maximum retry attempts |
| `retry_delay(duration)` | `Duration` | `ClientBuilder` | Sets retry delay duration |
| `max_concurrent_requests(count)` | `usize` | `ClientBuilder` | Sets concurrent request limit |
| `enable_cache(enabled)` | `bool` | `ClientBuilder` | Enables/disables caching |
| `cache_ttl(duration)` | `Duration` | `ClientBuilder` | Sets cache TTL |
| `build()` | None | `Result<SwarmsClient, SwarmsError>` | Builds the client |

**Example**:
```rust
let client = SwarmsClient::builder()
    .unwrap()
    .from_env()?
    .timeout(Duration::from_secs(120))
    .max_retries(5)
    .max_concurrent_requests(50)
    .enable_cache(true)
    .cache_ttl(Duration::from_secs(600))
    .build()?;
```

### SwarmResource

Resource for swarm-related operations.

#### Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `completion()` | None | `SwarmCompletionBuilder` | Creates a new swarm completion builder |
| `create(request)` | `SwarmSpec` | `Result<SwarmCompletionResponse, SwarmsError>` | Creates a swarm completion directly |
| `create_batch(requests)` | `Vec<SwarmSpec>` | `Result<Vec<SwarmCompletionResponse>, SwarmsError>` | Creates multiple swarm completions |
| `list_types()` | None | `Result<SwarmTypesResponse, SwarmsError>` | Lists available swarm types |

### SwarmCompletionBuilder

Builder for creating swarm completion requests.

#### Configuration Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `name(name)` | `String` | `SwarmCompletionBuilder` | Sets the swarm name |
| `description(desc)` | `String` | `SwarmCompletionBuilder` | Sets the swarm description |
| `swarm_type(type)` | `SwarmType` | `SwarmCompletionBuilder` | Sets the swarm type |
| `task(task)` | `String` | `SwarmCompletionBuilder` | Sets the main task |
| `agent(builder_fn)` | `Fn(AgentSpecBuilder) -> AgentSpecBuilder` | `SwarmCompletionBuilder` | Adds an agent using a builder function |
| `max_loops(count)` | `u32` | `SwarmCompletionBuilder` | Sets maximum execution loops |
| `service_tier(tier)` | `String` | `SwarmCompletionBuilder` | Sets the service tier |
| `send()` | None | `Result<SwarmCompletionResponse, SwarmsError>` | Sends the request |

### AgentResource

Resource for agent-related operations.

#### Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `completion()` | None | `AgentCompletionBuilder` | Creates a new agent completion builder |
| `create(request)` | `AgentCompletion` | `Result<AgentCompletionResponse, SwarmsError>` | Creates an agent completion directly |
| `create_batch(requests)` | `Vec<AgentCompletion>` | `Result<Vec<AgentCompletionResponse>, SwarmsError>` | Creates multiple agent completions |

### AgentCompletionBuilder

Builder for creating agent completion requests.

#### Configuration Methods

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `agent_name(name)` | `String` | `AgentCompletionBuilder` | Sets the agent name |
| `task(task)` | `String` | `AgentCompletionBuilder` | Sets the task |
| `model(model)` | `String` | `AgentCompletionBuilder` | Sets the AI model |
| `description(desc)` | `String` | `AgentCompletionBuilder` | Sets the agent description |
| `system_prompt(prompt)` | `String` | `AgentCompletionBuilder` | Sets the system prompt |
| `temperature(temp)` | `f32` | `AgentCompletionBuilder` | Sets the temperature (0.0-1.0) |
| `max_tokens(tokens)` | `u32` | `AgentCompletionBuilder` | Sets maximum tokens |
| `max_loops(loops)` | `u32` | `AgentCompletionBuilder` | Sets maximum loops |
| `send()` | None | `Result<AgentCompletionResponse, SwarmsError>` | Sends the request |

### SwarmType Enum

Available swarm types for different execution patterns.

| Variant | Description |
|---------|-------------|
| `AgentRearrange` | Agents can be rearranged based on task requirements |
| `MixtureOfAgents` | Combines multiple agents with different specializations |
| `SpreadSheetSwarm` | Organized like a spreadsheet with structured data flow |
| `SequentialWorkflow` | Agents execute in a sequential order |
| `ConcurrentWorkflow` | Agents execute concurrently |
| `GroupChat` | Agents interact in a group chat format |
| `MultiAgentRouter` | Routes tasks between multiple agents |
| `AutoSwarmBuilder` | Automatically builds swarm structure |
| `HiearchicalSwarm` | Hierarchical organization of agents |
| `Auto` | Automatically selects the best swarm type |
| `MajorityVoting` | Agents vote on decisions |
| `Malt` | Multi-Agent Language Tasks |

## Detailed Examples

### 1. Simple Agent Completion

```rust
use swarms_client::{SwarmsClient};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SwarmsClient::builder()
        .unwrap()
        .from_env()?
        .build()?;

    let response = client.agent()
        .completion()
        .agent_name("Content Writer")
        .task("Write a blog post about sustainable technology")
        .model("gpt-4o")
        .temperature(0.7)
        .max_tokens(2000)
        .description("An expert content writer specializing in technology topics")
        .system_prompt("You are a professional content writer with expertise in technology and sustainability. Write engaging, informative content that is well-structured and SEO-friendly.")
        .send()
        .await?;

    println!("Agent Response: {}", response.outputs);
    println!("Tokens Used: {}", response.usage.total_tokens);
    
    Ok(())
}
```

### 2. Multi-Agent Research Swarm

```rust
use swarms_client::{SwarmsClient, SwarmType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SwarmsClient::builder()
        .unwrap()
        .from_env()?
        .timeout(Duration::from_secs(300)) // 5 minutes for complex tasks
        .build()?;

    let response = client.swarm()
        .completion()
        .name("AI Research Swarm")
        .description("A comprehensive research team analyzing AI trends and developments")
        .swarm_type(SwarmType::SequentialWorkflow)
        .task("Conduct a comprehensive analysis of the current state of AI in healthcare, including recent developments, challenges, and future prospects")
        
        // Data Collection Agent
        .agent(|agent| {
            agent
                .name("Data Collector")
                .description("Gathers comprehensive data and recent developments")
                .model("gpt-4o")
                .system_prompt("You are a research data collector specializing in AI and healthcare. Your job is to gather the most recent and relevant information about AI applications in healthcare, including clinical trials, FDA approvals, and industry developments.")
                .temperature(0.3)
                .max_tokens(3000)
        })
        
        // Technical Analyst
        .agent(|agent| {
            agent
                .name("Technical Analyst")
                .description("Analyzes technical aspects and implementation details")
                .model("gpt-4o")
                .system_prompt("You are a technical analyst with deep expertise in AI/ML technologies. Analyze the technical feasibility, implementation challenges, and technological requirements of AI solutions in healthcare.")
                .temperature(0.4)
                .max_tokens(3000)
        })
        
        // Market Analyst
        .agent(|agent| {
            agent
                .name("Market Analyst")
                .description("Analyzes market trends, adoption rates, and economic factors")
                .model("gpt-4o")
                .system_prompt("You are a market research analyst specializing in healthcare technology markets. Analyze market size, growth projections, key players, investment trends, and economic factors affecting AI adoption in healthcare.")
                .temperature(0.5)
                .max_tokens(3000)
        })
        
        // Regulatory Expert
        .agent(|agent| {
            agent
                .name("Regulatory Expert")
                .description("Analyzes regulatory landscape and compliance requirements")
                .model("gpt-4o")
                .system_prompt("You are a regulatory affairs expert with deep knowledge of healthcare regulations and AI governance. Analyze regulatory challenges, compliance requirements, ethical considerations, and policy developments affecting AI in healthcare.")
                .temperature(0.3)
                .max_tokens(3000)
        })
        
        // Report Synthesizer
        .agent(|agent| {
            agent
                .name("Report Synthesizer")
                .description("Synthesizes all analyses into a comprehensive report")
                .model("gpt-4o")
                .system_prompt("You are an expert report writer and strategic analyst. Synthesize all the previous analyses into a comprehensive, well-structured executive report with clear insights, recommendations, and future outlook.")
                .temperature(0.6)
                .max_tokens(4000)
        })
        
        .max_loops(1)
        .service_tier("premium")
        .send()
        .await?;

    println!("Research Report:");
    println!("{}", response.output);
    println!("\nSwarm executed with {} agents", response.number_of_agents);
    
    Ok(())
}
```

### 3. Financial Analysis Swarm (From Example)

```rust
use swarms_client::{SwarmsClient, SwarmType};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SwarmsClient::builder()
        .unwrap()
        .from_env()?
        .timeout(Duration::from_secs(120))
        .max_retries(3)
        .build()?;

    let response = client.swarm()
        .completion()
        .name("Financial Health Analysis Swarm")
        .description("A sequential workflow of specialized financial agents analyzing company health")
        .swarm_type(SwarmType::ConcurrentWorkflow)
        .task("Analyze the financial health of Apple Inc. (AAPL) based on their latest quarterly report")
        
        // Financial Data Collector Agent
        .agent(|agent| {
            agent
                .name("Financial Data Collector")
                .description("Specializes in gathering and organizing financial data from various sources")
                .model("gpt-4o")
                .system_prompt("You are a financial data collection specialist. Your role is to gather and organize relevant financial data, including revenue, expenses, profit margins, and key financial ratios. Present the data in a clear, structured format.")
                .temperature(0.7)
                .max_tokens(2000)
        })
        
        // Financial Ratio Analyzer Agent
        .agent(|agent| {
            agent
                .name("Ratio Analyzer")
                .description("Analyzes key financial ratios and metrics")
                .model("gpt-4o")
                .system_prompt("You are a financial ratio analysis expert. Your role is to calculate and interpret key financial ratios such as P/E ratio, debt-to-equity, current ratio, and return on equity. Provide insights on what these ratios indicate about the company's financial health.")
                .temperature(0.7)
                .max_tokens(2000)
        })
        
        // Additional agents...
        .agent(|agent| {
            agent
                .name("Investment Advisor")
                .description("Provides investment recommendations based on analysis")
                .model("gpt-4o")
                .system_prompt("You are an investment advisory specialist. Your role is to synthesize the analysis from previous agents and provide clear, actionable investment recommendations. Consider both short-term and long-term investment perspectives.")
                .temperature(0.7)
                .max_tokens(2000)
        })
        
        .max_loops(1)
        .service_tier("standard")
        .send()
        .await?;

    println!("Financial Analysis Results:");
    println!("{}", response.output);
    
    Ok(())
}
```

### 4. Batch Processing

```rust
use swarms_client::{SwarmsClient, AgentCompletion, AgentSpec};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = SwarmsClient::builder()
        .unwrap()
        .from_env()?
        .max_concurrent_requests(20) // Allow more concurrent requests for batch
        .build()?;

    // Create multiple agent completion requests
    let requests = vec![
        AgentCompletion {
            agent_config: AgentSpec {
                agent_name: "Content Creator 1".to_string(),
                model_name: "gpt-4o-mini".to_string(),
                temperature: 0.7,
                max_tokens: 1000,
                ..Default::default()
            },
            task: "Write a social media post about renewable energy".to_string(),
            history: None,
        },
        AgentCompletion {
            agent_config: AgentSpec {
                agent_name: "Content Creator 2".to_string(),
                model_name: "gpt-4o-mini".to_string(),
                temperature: 0.8,
                max_tokens: 1000,
                ..Default::default()
            },
            task: "Write a social media post about electric vehicles".to_string(),
            history: None,
        },
        // Add more requests...
    ];

    // Process all requests in batch
    let responses = client.agent()
        .create_batch(requests)
        .await?;

    for (i, response) in responses.iter().enumerate() {
        println!("Response {}: {}", i + 1, response.outputs);
        println!("Tokens used: {}\n", response.usage.total_tokens);
    }
    
    Ok(())
}
```

### 5. Custom Configuration with Error Handling

```rust
use swarms_client::{SwarmsClient, SwarmsError, ClientConfig};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Custom configuration for production use
    let config = ClientConfig {
        api_key: std::env::var("SWARMS_API_KEY")?,
        base_url: "https://swarms-api-285321057562.us-east1.run.app/".parse()?,
        timeout: Duration::from_secs(180),
        max_retries: 5,
        retry_delay: Duration::from_secs(2),
        max_concurrent_requests: 50,
        circuit_breaker_threshold: 10,
        circuit_breaker_timeout: Duration::from_secs(120),
        enable_cache: true,
        cache_ttl: Duration::from_secs(600),
    };

    let client = SwarmsClient::with_config(config)?;

    // Example with comprehensive error handling
    match client.swarm()
        .completion()
        .name("Production Swarm")
        .swarm_type(SwarmType::Auto)
        .task("Analyze market trends for Q4 2024")
        .agent(|agent| {
            agent
                .name("Market Analyst")
                .model("gpt-4o")
                .temperature(0.5)
        })
        .send()
        .await
    {
        Ok(response) => {
            println!("Success! Job ID: {}", response.job_id);
            println!("Output: {}", response.output);
        },
        Err(SwarmsError::Authentication { message, .. }) => {
            eprintln!("Authentication error: {}", message);
        },
        Err(SwarmsError::RateLimit { message, .. }) => {
            eprintln!("Rate limit exceeded: {}", message);
            // Implement backoff strategy
        },
        Err(SwarmsError::InsufficientCredits { message, .. }) => {
            eprintln!("Insufficient credits: {}", message);
        },
        Err(SwarmsError::CircuitBreakerOpen) => {
            eprintln!("Circuit breaker is open - service temporarily unavailable");
        },
        Err(e) => {
            eprintln!("Other error: {}", e);
        }
    }
    
    Ok(())
}
```

### 6. Monitoring and Observability

```rust
use swarms_client::SwarmsClient;
use tracing::{info, warn, error};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize tracing for observability
    tracing_subscriber::init();

    let client = SwarmsClient::builder()
        .unwrap()
        .from_env()?
        .enable_cache(true)
        .build()?;

    // Monitor cache performance
    if let Some((valid, total)) = client.cache_stats() {
        info!("Cache stats: {}/{} entries valid", valid, total);
    }

    // Make request with monitoring
    let start = std::time::Instant::now();
    
    let response = client.swarm()
        .completion()
        .name("Monitored Swarm")
        .task("Analyze system performance metrics")
        .agent(|agent| {
            agent
                .name("Performance Analyst")
                .model("gpt-4o-mini")
        })
        .send()
        .await?;

    let duration = start.elapsed();
    info!("Request completed in {:?}", duration);
    
    if duration > Duration::from_secs(30) {
        warn!("Request took longer than expected: {:?}", duration);
    }

    // Clear cache periodically in production
    client.clear_cache();
    
    Ok(())
}
```

## Error Handling

The client provides comprehensive error handling with specific error types:

### SwarmsError Types

| Error Type | Description | Recommended Action |
|------------|-------------|-------------------|
| `Authentication` | Invalid API key or authentication failure | Check API key and permissions |
| `RateLimit` | Rate limit exceeded | Implement exponential backoff |
| `InvalidRequest` | Malformed request parameters | Validate input parameters |
| `InsufficientCredits` | Not enough credits for operation | Check account balance |
| `Api` | General API error | Check API status and retry |
| `Network` | Network connectivity issues | Check internet connection |
| `Timeout` | Request timeout | Increase timeout or retry |
| `CircuitBreakerOpen` | Circuit breaker preventing requests | Wait for recovery period |
| `Serialization` | JSON serialization/deserialization error | Check data format |

### Error Handling Best Practices

```rust
use swarms_client::{SwarmsClient, SwarmsError};

async fn handle_swarm_request(client: &SwarmsClient, task: &str) -> Result<String, SwarmsError> {
    match client.swarm()
        .completion()
        .task(task)
        .agent(|agent| agent.name("Worker").model("gpt-4o-mini"))
        .send()
        .await
    {
        Ok(response) => Ok(response.output.to_string()),
        Err(SwarmsError::RateLimit { .. }) => {
            // Implement exponential backoff
            tokio::time::sleep(Duration::from_secs(5)).await;
            Err(SwarmsError::RateLimit {
                message: "Rate limited - should retry".to_string(),
                status: Some(429),
                request_id: None,
            })
        },
        Err(e) => Err(e),
    }
}
```

## Performance Features

### Connection Pooling
The client automatically manages HTTP connection pooling for optimal performance:

```rust
// Connections are automatically pooled and reused
let client = SwarmsClient::builder()
    .unwrap()
    .from_env()?
    .max_concurrent_requests(100) // Allow up to 100 concurrent requests
    .build()?;
```

### Caching
Intelligent caching reduces redundant API calls:

```rust
let client = SwarmsClient::builder()
    .unwrap()
    .from_env()?
    .enable_cache(true)
    .cache_ttl(Duration::from_secs(300)) // 5-minute TTL
    .build()?;

// GET requests are automatically cached
let models = client.models().list().await?; // First call hits API
let models_cached = client.models().list().await?; // Second call uses cache
```

### Circuit Breaker
Automatic failure detection and recovery:

```rust
let client = SwarmsClient::builder()
    .unwrap()
    .from_env()?
    .build()?;

// Circuit breaker automatically opens after 5 failures
// and recovers after 60 seconds
```

## Configuration Reference

### ClientConfig Structure

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | `String` | `""` | Swarms API key |
| `base_url` | `Url` | `https://swarms-api-285321057562.us-east1.run.app/` | API base URL |
| `timeout` | `Duration` | `60s` | Request timeout |
| `max_retries` | `usize` | `3` | Maximum retry attempts |
| `retry_delay` | `Duration` | `1s` | Base retry delay |
| `max_concurrent_requests` | `usize` | `100` | Concurrent request limit |
| `circuit_breaker_threshold` | `usize` | `5` | Failure threshold for circuit breaker |
| `circuit_breaker_timeout` | `Duration` | `60s` | Circuit breaker recovery time |
| `enable_cache` | `bool` | `true` | Enable response caching |
| `cache_ttl` | `Duration` | `300s` | Cache time-to-live |

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `SWARMS_API_KEY` | Your Swarms API key | `sk-xxx...` |
| `SWARMS_BASE_URL` | Custom API base URL (optional) | `https://api.custom.com/` |

## Testing

Run the test suite:

```bash
cargo test
```

Run specific tests:

```bash
cargo test test_cache
cargo test test_circuit_breaker
```

## 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

This project is licensed under the MIT License - see the LICENSE file for details.

--------------------------------------------------

# File: swarms_cloud/sequential_workflow.md

# SequentialWorkflow

*Executes tasks in a strict, predefined order for step-by-step processing*

**Swarm Type**: `SequentialWorkflow`

## Overview

The SequentialWorkflow swarm type executes tasks in a strict, predefined order where each step depends on the completion of the previous one. This architecture is perfect for workflows that require a linear progression of tasks, ensuring that each agent builds upon the work of the previous agent.

Key features:
- **Ordered Execution**: Agents execute in a specific, predefined sequence
- **Step Dependencies**: Each step builds upon previous results
- **Predictable Flow**: Clear, linear progression through the workflow
- **Quality Control**: Each agent can validate and enhance previous work

## Use Cases

- Document processing pipelines
- Multi-stage analysis workflows
- Content creation and editing processes
- Data transformation and validation pipelines

## API Usage

### Basic SequentialWorkflow Example

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Content Creation Pipeline",
        "description": "Sequential content creation from research to final output",
        "swarm_type": "SequentialWorkflow",
        "task": "Create a comprehensive blog post about the future of renewable energy",
        "agents": [
          {
            "agent_name": "Research Specialist",
            "description": "Conducts thorough research on the topic",
            "system_prompt": "You are a research specialist. Gather comprehensive, accurate information on the given topic from reliable sources.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.3
          },
          {
            "agent_name": "Content Writer",
            "description": "Creates engaging written content",
            "system_prompt": "You are a skilled content writer. Transform research into engaging, well-structured articles that are informative and readable.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.6
          },
          {
            "agent_name": "Editor",
            "description": "Reviews and polishes the content",
            "system_prompt": "You are a professional editor. Review content for clarity, grammar, flow, and overall quality. Make improvements while maintaining the author's voice.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.4
          },
          {
            "agent_name": "SEO Optimizer",
            "description": "Optimizes content for search engines",
            "system_prompt": "You are an SEO expert. Optimize content for search engines while maintaining readability and quality.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "temperature": 0.2
          }
        ],
        "max_loops": 1
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Content Creation Pipeline",
        "description": "Sequential content creation from research to final output",
        "swarm_type": "SequentialWorkflow",
        "task": "Create a comprehensive blog post about the future of renewable energy",
        "agents": [
            {
                "agent_name": "Research Specialist",
                "description": "Conducts thorough research on the topic",
                "system_prompt": "You are a research specialist. Gather comprehensive, accurate information on the given topic from reliable sources.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.3
            },
            {
                "agent_name": "Content Writer",
                "description": "Creates engaging written content",
                "system_prompt": "You are a skilled content writer. Transform research into engaging, well-structured articles that are informative and readable.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.6
            },
            {
                "agent_name": "Editor",
                "description": "Reviews and polishes the content",
                "system_prompt": "You are a professional editor. Review content for clarity, grammar, flow, and overall quality. Make improvements while maintaining the author's voice.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.4
            },
            {
                "agent_name": "SEO Optimizer",
                "description": "Optimizes content for search engines",
                "system_prompt": "You are an SEO expert. Optimize content for search engines while maintaining readability and quality.",
                "model_name": "gpt-4o",
                "max_loops": 1,
                "temperature": 0.2
            }
        ],
        "max_loops": 1
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("SequentialWorkflow swarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
        print(f"Final output: {result['output']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

**Example Response**:
```json
{
    "job_id": "swarms-pbM8wqUwxq8afGeROV2A4xAcncd1",
    "status": "success",
    "swarm_name": "Content Creation Pipeline",
    "description": "Sequential content creation from research to final output",
    "swarm_type": "SequentialWorkflow",
    "output": [
        {
            "role": "Research Specialist",
            "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we navigate the complexities of the 21st century, the transition to renewable energy stands out as a critical endeavor to ensure a sustainable future......"
        },
        {
            "role": "SEO Optimizer",
            "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nThe transition to renewable energy is crucial as we face the challenges of the 21st century, including climate change and dwindling fossil fuel resources......."
        },
        {
            "role": "Editor",
            "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we confront the challenges of the 21st century, transitioning to renewable energy is essential for a sustainable future. With climate change concerns escalating and fossil fuel reserves depleting, renewable energy is not just an option but a necessity...."
        },
        {
            "role": "Content Writer",
            "content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we face the multifaceted challenges of the 21st century, transitioning to renewable energy emerges as not just an option but an essential step toward a sustainable future...."
        }
    ],
    "number_of_agents": 4,
    "service_tier": "standard",
    "execution_time": 72.23084282875061,
    "usage": {
        "input_tokens": 28,
        "output_tokens": 3012,
        "total_tokens": 3040,
        "billing_info": {
            "cost_breakdown": {
                "agent_cost": 0.04,
                "input_token_cost": 0.000084,
                "output_token_cost": 0.04518,
                "token_counts": {
                    "total_input_tokens": 28,
                    "total_output_tokens": 3012,
                    "total_tokens": 3040
                },
                "num_agents": 4,
                "service_tier": "standard",
                "night_time_discount_applied": true
            },
            "total_cost": 0.085264,
            "discount_active": true,
            "discount_type": "night_time",
            "discount_percentage": 75
        }
    }
}
```

## Best Practices

- Design agents with clear, sequential dependencies
- Ensure each agent builds meaningfully on the previous work
- Use for linear workflows where order matters
- Validate outputs at each step before proceeding

## Related Swarm Types

- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel execution
- [AgentRearrange](agent_rearrange.md) - For dynamic sequencing
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured workflows

--------------------------------------------------

# File: swarms_cloud/subscription_tiers.md

# Swarms Cloud Subscription Tiers

!!! abstract "Overview"
    Choose the perfect plan for your agent infrastructure needs. All plans include our core features with additional benefits as you scale up.

## Pricing Plans

### Free Tier

!!! example "Free"
    **$0/year**
    
    Perfect for getting started with AI development.

    [Get Started](https://swarms.world/platform/account){ .md-button .md-button--primary }

    **What's Included:**
    
    - [x] Sign up Bonus!
    
    - [x] Basic Access
    
    - [x] Pay-Per-Use Pricing
    
    - [x] Community Support
    
    - [x] Standard Processing Speed

### Premium Tier

!!! success "Premium"

    **Monthly $100/month**

    **Yearly $1,020/year** (Save 15% on annual billing)
    
    [Subscribe Now](https://swarms.world/platform/account){ .md-button .md-button--primary }

    **Everything in Free, plus:**
    
    - [x] Full Access to Explorer and Agents
    
    - [x] Access to Premium Multi-Modality Models
    
    - [x] Priority Access to Swarms
    
    - [x] High-Performance Infrastructure
    
    - [x] Exclusive Webinars and Tutorials
    
    - [x] Priority Support
    
    - [x] Enhanced Security Features
    
    - [x] Early Access to New Models and Features

### Enterprise Tier

!!! tip "Enterprise"
    **Contact for more Information**
    
    [Book a Call](https://cal.com/swarms){ .md-button .md-button--primary }

    **Everything in Premium, plus:**
    
    - [x] High-Performance Infrastructure
    
    - [x] Batch API
    
    - [x] Early Access to New Swarms
    
    - [x] Dedicated 24/7 Support
    
    - [x] Custom Solutions Engineering
    
    - [x] Advanced Security Features
    
    - [x] Onsite Training and Onboarding
    
    - [x] Custom Model Training
    
    - [x] Priority Support
    
    - [x] Pay-Per-Use Pricing

    - [x] Enterprise Telemetry Platform

    - [x] Regular Check-In Strategy Sessions

## Feature Comparison

| Feature | Free | Premium | Enterprise |
|---------|------|---------|------------|
| Sign up Bonus | ✅ | ✅ | ✅ |
| Basic Access | ✅ | ✅ | ✅ |
| Pay-Per-Use Pricing | ✅ | ✅ | ✅ |
| Community Support | ✅ | ✅ | ✅ |
| Standard Processing Speed | ✅ | ✅ | ✅ |
| Full Access to Explorer and Agents | ❌ | ✅ | ✅ |
| Premium Multi-Modality Models | ❌ | ✅ | ✅ |
| Priority Access to Swarms | ❌ | ✅ | ✅ |
| High-Performance GPUs | ❌ | ✅ | ✅ |
| Exclusive Webinars and Tutorials | ❌ | ✅ | ✅ |
| Priority Support | ❌ | ✅ | ✅ |
| Enhanced Security Features | ❌ | ✅ | ✅ |
| Early Access to New Models | ❌ | ✅ | ✅ |
| Batch API | ❌ | ❌ | ✅ |
| Dedicated 24/7 Support | ❌ | ❌ | ✅ |
| Custom Solutions Engineering | ❌ | ❌ | ✅ |
| Onsite Training and Onboarding | ❌ | ❌ | ✅ |
| Custom Model Training | ❌ | ❌ | ✅ |

## Rate Limits

!!! info "Rate Limit Increases"
    - **Premium**: 100% increase in rate limits
    - **Enterprise**: Custom rate limits based on your needs (contact us for details)

## Getting Started

1. Choose your plan
2. Create your account
3. Start building with Swarms!

!!! success "Need Help?"
    - For general questions: [Contact Support](mailto:kye@swarms.world)
    - For enterprise inquiries: [Book a Call](https://cal.com/swarms)
    - Upgrade Your Membership: [Upgrade Now](https://swarms.world/platform/account)


--------------------------------------------------

# File: swarms_cloud/swarm_types.md

# Multi-Agent Architectures

Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems. Below is an overview of each available swarm type:

| Swarm Type           | Description                                                                  | Learn More |
|----------------------|------------------------------------------------------------------------------|------------|
| AgentRearrange       | Dynamically reorganizes agents to optimize task performance and efficiency. Useful when agent effectiveness depends on their sequence or arrangement. | [Learn More](agent_rearrange.md) |
| MixtureOfAgents      | Builds diverse teams of specialized agents, each contributing unique skills to solve complex problems. Excels at tasks requiring multiple types of expertise. | [Learn More](mixture_of_agents.md) |
| SequentialWorkflow   | Executes tasks in a strict, predefined order. Perfect for workflows where each step depends on the completion of the previous one. | [Learn More](sequential_workflow.md) |
| ConcurrentWorkflow   | Runs independent tasks in parallel, significantly reducing processing time for complex operations. Ideal for tasks that can be processed simultaneously. | [Learn More](concurrent_workflow.md) |
| GroupChat            | Enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. | [Learn More](group_chat.md) |
| HierarchicalSwarm    | Implements a structured, multi-level approach to task management, with clear lines of authority and delegation. | [Learn More](hierarchical_swarm.md) |
| MultiAgentRouter     | Acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. | [Learn More](multi_agent_router.md) |
| MajorityVoting       | Implements robust decision-making through consensus, ideal for tasks requiring collective intelligence or verification. | [Learn More](majority_voting.md) |


<!-- | AutoSwarmBuilder     | Automatically configures agent architectures based on task requirements and performance metrics, simplifying swarm creation. | [Learn More](auto_swarm_builder.md) |
<!-- | Auto                | Intelligently selects the most effective swarm architecture for a given task based on context. | [Learn More](auto.md) | -->


# Learn More

To explore Swarms architecture and how different swarm types work together, check out our comprehensive guides:

- [Introduction to Multi-Agent Architectures](/swarms/concept/swarm_architectures)
- [How to Choose the Right Multi-Agent Architecture](/swarms/concept/how_to_choose_swarms)
- [Framework Architecture Overview](/swarms/concept/framework_architecture)
- [Building Custom Swarms](/swarms/structs/custom_swarm)


--------------------------------------------------

# File: swarms_cloud/swarms_api.md

# Swarms API Documentation

*Enterprise-Grade Agent Swarm Management API*

**Base URL**: `https://api.swarms.world` or `https://swarms-api-285321057562.us-east1.run.app`

**API Key Management**: [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)  

## Overview

The Swarms API provides a robust, scalable infrastructure for deploying and managing intelligent agent swarms in the cloud. This enterprise-grade API enables organizations to create, execute, and orchestrate sophisticated AI agent workflows without managing the underlying infrastructure.

Key capabilities include:

- **Intelligent Swarm Management**: Create and execute swarms of specialized AI agents that collaborate to solve complex tasks

- **Automatic Agent Generation**: Dynamically create optimized agents based on task requirements

- **Multiple Swarm Architectures**: Choose from various swarm patterns to match your specific workflow needs

- **Comprehensive Logging**: Track and analyze all API interactions

- **Cost Management**: Predictable, transparent pricing with optimized resource utilization

- **Enterprise Security**: Full API key authentication and management

Swarms API is designed for production use cases requiring sophisticated AI orchestration, with applications in finance, healthcare, legal, research, and other domains where complex reasoning and multi-agent collaboration are needed.

## Authentication

All API requests require a valid API key, which must be included in the header of each request:

```
x-api-key: your_api_key_here
```

API keys can be obtained and managed at [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys).

## API Reference

### Endpoints Summary

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Simple health check endpoint |
| `/v1/swarm/completions` | POST | Run a swarm with specified configuration |
| `/v1/swarm/batch/completions` | POST | Run multiple swarms in batch mode |
| `/v1/swarm/logs` | GET | Retrieve API request logs |
| `/v1/swarms/available` | GET | Get all available swarms as a list of strings |
| `/v1/models/available` | GET | Get all available models as a list of strings |
| `/v1/agent/completions` | POST | Run a single agent with specified configuration |
| `/v1/agent/batch/completions` | POST | Run a batch of individual agent completions|



### SwarmType Reference

The `swarm_type` parameter defines the architecture and collaboration pattern of the agent swarm:

| SwarmType | Description |
|-----------|-------------|
| `AgentRearrange` | Dynamically reorganizes the workflow between agents based on task requirements |
| `MixtureOfAgents` | Combines multiple agent types to tackle diverse aspects of a problem |
| `SpreadSheetSwarm` | Specialized for spreadsheet data analysis and manipulation |
| `SequentialWorkflow` | Agents work in a predefined sequence, each handling specific subtasks |
| `ConcurrentWorkflow` | Multiple agents work simultaneously on different aspects of the task |
| `GroupChat` | Agents collaborate in a discussion format to solve problems |
| `MultiAgentRouter` | Routes subtasks to specialized agents based on their capabilities |
| `AutoSwarmBuilder` | Automatically designs and builds an optimal swarm based on the task |
| `HiearchicalSwarm` | Organizes agents in a hierarchical structure with managers and workers |
| `MajorityVoting` | Uses a consensus mechanism where multiple agents vote on the best solution |
| `auto` | Automatically selects the most appropriate swarm type for the given task |



## Data Models

### SwarmSpec

The `SwarmSpec` model defines the configuration of a swarm.

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| name | string | Identifier for the swarm | No |
| description | string | Description of the swarm's purpose | No |
| agents | Array<AgentSpec> | List of agent specifications | No |
| max_loops | integer | Maximum number of execution loops | No |
| swarm_type | SwarmType | Architecture of the swarm | No |
| rearrange_flow | string | Instructions for rearranging task flow | No |
| task | string | The main task for the swarm to accomplish | Yes |
| img | string | Optional image URL for the swarm | No |
| return_history | boolean | Whether to return execution history | No |
| rules | string | Guidelines for swarm behavior | No |
| service_tier | string | Service tier for processing ("standard" or "flex") | No |

### AgentSpec

The `AgentSpec` model defines the configuration of an individual agent.

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| agent_name | string | Unique name for the agent | Yes* |
| description | string | Description of the agent's purpose | No |
| system_prompt | string | Instructions for the agent | No |
| model_name | string | AI model to use (e.g., "gpt-4o") | Yes* |
| auto_generate_prompt | boolean | Whether to auto-generate prompts | No |
| max_tokens | integer | Maximum tokens in response | No |
| temperature | float | Randomness of responses (0-1) | No |
| role | string | Agent's role in the swarm | No |
| max_loops | integer | Maximum iterations for this agent | No |

*Required if agents are manually specified; not required if using auto-generated agents


### Endpoint Details

#### Health Check

Check if the API service is available and functioning correctly.

**Endpoint**: `/health`  
**Method**: GET  
**Rate Limit**: 100 requests per 60 seconds

=== "Shell (curl)"
    ```bash
    curl -X GET "https://api.swarms.world/health" \
         -H "x-api-key: your_api_key_here"
    ```

=== "Python (requests)"
    ```python
    import requests

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY
    }
    
    response = requests.get(f"{API_BASE_URL}/health", headers=headers)
    
    if response.status_code == 200:
        print("API is healthy:", response.json())
    else:
        print(f"Error: {response.status_code}")
    ```

=== "TypeScript (fetch)"
    ```typescript
    const API_BASE_URL = "https://api.swarms.world";
    const API_KEY = "your_api_key_here";

    async function checkHealth(): Promise<void> {
        try {
            const response = await fetch(`${API_BASE_URL}/health`, {
                method: 'GET',
                headers: {
                    'x-api-key': API_KEY
                }
            });

            if (response.ok) {
                const data = await response.json();
                console.log("API is healthy:", data);
            } else {
                console.error(`Error: ${response.status}`);
            }
        } catch (error) {
            console.error("Request failed:", error);
        }
    }

    checkHealth();
    ```

**Example Response**:
```json
{
  "status": "ok"
}
```

#### Run Swarm

Run a swarm with the specified configuration to complete a task.

**Endpoint**: `/v1/swarm/completions`  
**Method**: POST  
**Rate Limit**: 100 requests per 60 seconds

**Request Parameters**:

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| name | string | Identifier for the swarm | No |
| description | string | Description of the swarm's purpose | No |
| agents | Array<AgentSpec> | List of agent specifications | No |
| max_loops | integer | Maximum number of execution loops | No |
| swarm_type | SwarmType | Architecture of the swarm | No |
| rearrange_flow | string | Instructions for rearranging task flow | No |
| task | string | The main task for the swarm to accomplish | Yes |
| img | string | Optional image URL for the swarm | No |
| return_history | boolean | Whether to return execution history | No |
| rules | string | Guidelines for swarm behavior | No |

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Financial Analysis Swarm",
        "description": "Market analysis swarm",
        "agents": [
          {
            "agent_name": "Market Analyst",
            "description": "Analyzes market trends",
            "system_prompt": "You are a financial analyst expert.",
            "model_name": "openai/gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5,
            "auto_generate_prompt": false
          },
          {
            "agent_name": "Economic Forecaster",
            "description": "Predicts economic trends",
            "system_prompt": "You are an expert in economic forecasting.",
            "model_name": "gpt-4o",
            "role": "worker",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5,
            "auto_generate_prompt": false
          }
        ],
        "max_loops": 1,
        "swarm_type": "ConcurrentWorkflow",
        "task": "What are the best etfs and index funds for ai and tech?",
        "output_type": "dict"
      }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    swarm_config = {
        "name": "Financial Analysis Swarm",
        "description": "Market analysis swarm",
        "agents": [
            {
                "agent_name": "Market Analyst",
                "description": "Analyzes market trends",
                "system_prompt": "You are a financial analyst expert.",
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False
            },
            {
                "agent_name": "Economic Forecaster",
                "description": "Predicts economic trends",
                "system_prompt": "You are an expert in economic forecasting.",
                "model_name": "gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False
            }
        ],
        "max_loops": 1,
        "swarm_type": "ConcurrentWorkflow",
        "task": "What are the best etfs and index funds for ai and tech?",
        "output_type": "dict"
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=swarm_config
    )
    
    if response.status_code == 200:
        result = response.json()
        print("Swarm completed successfully!")
        print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
        print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

=== "TypeScript (fetch)"
    ```typescript
    interface AgentSpec {
        agent_name: string;
        description: string;
        system_prompt: string;
        model_name: string;
        role: string;
        max_loops: number;
        max_tokens: number;
        temperature: number;
        auto_generate_prompt: boolean;
    }

    interface SwarmConfig {
        name: string;
        description: string;
        agents: AgentSpec[];
        max_loops: number;
        swarm_type: string;
        task: string;
        output_type: string;
    }

    const API_BASE_URL = "https://api.swarms.world";
    const API_KEY = "your_api_key_here";

    async function runSwarm(): Promise<void> {
        const swarmConfig: SwarmConfig = {
            name: "Financial Analysis Swarm",
            description: "Market analysis swarm",
            agents: [
                {
                    agent_name: "Market Analyst",
                    description: "Analyzes market trends",
                    system_prompt: "You are a financial analyst expert.",
                    model_name: "openai/gpt-4o",
                    role: "worker",
                    max_loops: 1,
                    max_tokens: 8192,
                    temperature: 0.5,
                    auto_generate_prompt: false
                },
                {
                    agent_name: "Economic Forecaster",
                    description: "Predicts economic trends",
                    system_prompt: "You are an expert in economic forecasting.",
                    model_name: "gpt-4o",
                    role: "worker",
                    max_loops: 1,
                    max_tokens: 8192,
                    temperature: 0.5,
                    auto_generate_prompt: false
                }
            ],
            max_loops: 1,
            swarm_type: "ConcurrentWorkflow",
            task: "What are the best etfs and index funds for ai and tech?",
            output_type: "dict"
        };

        try {
            const response = await fetch(`${API_BASE_URL}/v1/swarm/completions`, {
                method: 'POST',
                headers: {
                    'x-api-key': API_KEY,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(swarmConfig)
            });

            if (response.ok) {
                const result = await response.json();
                console.log("Swarm completed successfully!");
                console.log(`Cost: $${result.metadata.billing_info.total_cost}`);
                console.log(`Execution time: ${result.metadata.execution_time_seconds} seconds`);
            } else {
                console.error(`Error: ${response.status} - ${await response.text()}`);
            }
        } catch (error) {
            console.error("Request failed:", error);
        }
    }

    runSwarm();
    ```

**Example Response**:
```json
{
  "status": "success",
  "swarm_name": "financial-analysis-swarm",
  "description": "Analyzes financial data for risk assessment",
  "swarm_type": "SequentialWorkflow",
  "task": "Analyze the provided quarterly financials for Company XYZ and identify potential risk factors. Summarize key insights and provide recommendations for risk mitigation.",
  "output": {
    "financial_analysis": {
      "risk_factors": [...],
      "key_insights": [...],
      "recommendations": [...]
    }
  },
  "metadata": {
    "max_loops": 2,
    "num_agents": 3,
    "execution_time_seconds": 12.45,
    "completion_time": 1709563245.789,
    "billing_info": {
      "cost_breakdown": {
        "agent_cost": 0.03,
        "input_token_cost": 0.002134,
        "output_token_cost": 0.006789,
        "token_counts": {
          "total_input_tokens": 1578,
          "total_output_tokens": 3456,
          "total_tokens": 5034,
          "per_agent": {...}
        },
        "num_agents": 3,
        "execution_time_seconds": 12.45
      },
      "total_cost": 0.038923
    }
  }
}
```

#### Run Batch Completions

Run multiple swarms as a batch operation.

**Endpoint**: `/v1/swarm/batch/completions`  
**Method**: POST  
**Rate Limit**: 100 requests per 60 seconds

**Request Parameters**:

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| swarms | Array<SwarmSpec> | List of swarm specifications | Yes |

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/swarm/batch/completions" \
      -H "x-api-key: $SWARMS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '[
        {
          "name": "Batch Swarm 1",
          "description": "First swarm in the batch",
          "agents": [
            {
              "agent_name": "Research Agent",
              "description": "Conducts research",
              "system_prompt": "You are a research assistant.",
              "model_name": "gpt-4o",
              "role": "worker",
              "max_loops": 1
            },
            {
              "agent_name": "Analysis Agent",
              "description": "Analyzes data",
              "system_prompt": "You are a data analyst.",
              "model_name": "gpt-4o",
              "role": "worker",
              "max_loops": 1
            }
          ],
          "max_loops": 1,
          "swarm_type": "SequentialWorkflow",
          "task": "Research AI advancements."
        },
        {
          "name": "Batch Swarm 2",
          "description": "Second swarm in the batch",
          "agents": [
            {
              "agent_name": "Writing Agent",
              "description": "Writes content",
              "system_prompt": "You are a content writer.",
              "model_name": "gpt-4o",
              "role": "worker",
              "max_loops": 1
            },
            {
              "agent_name": "Editing Agent",
              "description": "Edits content",
              "system_prompt": "You are an editor.",
              "model_name": "gpt-4o",
              "role": "worker",
              "max_loops": 1
            }
          ],
          "max_loops": 1,
          "swarm_type": "SequentialWorkflow",
          "task": "Write a summary of AI research."
        }
      ]'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    batch_swarms = [
        {
            "name": "Batch Swarm 1",
            "description": "First swarm in the batch",
            "agents": [
                {
                    "agent_name": "Research Agent",
                    "description": "Conducts research",
                    "system_prompt": "You are a research assistant.",
                    "model_name": "gpt-4o",
                    "role": "worker",
                    "max_loops": 1
                },
                {
                    "agent_name": "Analysis Agent",
                    "description": "Analyzes data",
                    "system_prompt": "You are a data analyst.",
                    "model_name": "gpt-4o",
                    "role": "worker",
                    "max_loops": 1
                }
            ],
            "max_loops": 1,
            "swarm_type": "SequentialWorkflow",
            "task": "Research AI advancements."
        },
        {
            "name": "Batch Swarm 2",
            "description": "Second swarm in the batch",
            "agents": [
                {
                    "agent_name": "Writing Agent",
                    "description": "Writes content",
                    "system_prompt": "You are a content writer.",
                    "model_name": "gpt-4o",
                    "role": "worker",
                    "max_loops": 1
                },
                {
                    "agent_name": "Editing Agent",
                    "description": "Edits content",
                    "system_prompt": "You are an editor.",
                    "model_name": "gpt-4o",
                    "role": "worker",
                    "max_loops": 1
                }
            ],
            "max_loops": 1,
            "swarm_type": "SequentialWorkflow",
            "task": "Write a summary of AI research."
        }
    ]
    
    response = requests.post(
        f"{API_BASE_URL}/v1/swarm/batch/completions",
        headers=headers,
        json=batch_swarms
    )
    
    if response.status_code == 200:
        results = response.json()
        print(f"Batch completed with {len(results)} swarms")
        for i, result in enumerate(results):
            print(f"Swarm {i+1}: {result['swarm_name']} - {result['status']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

=== "TypeScript (fetch)"
    ```typescript
    interface AgentSpec {
        agent_name: string;
        description: string;
        system_prompt: string;
        model_name: string;
        role: string;
        max_loops: number;
    }

    interface SwarmSpec {
        name: string;
        description: string;
        agents: AgentSpec[];
        max_loops: number;
        swarm_type: string;
        task: string;
    }

    const API_BASE_URL = "https://api.swarms.world";
    const API_KEY = "your_api_key_here";

    async function runBatchSwarms(): Promise<void> {
        const batchSwarms: SwarmSpec[] = [
            {
                name: "Batch Swarm 1",
                description: "First swarm in the batch",
                agents: [
                    {
                        agent_name: "Research Agent",
                        description: "Conducts research",
                        system_prompt: "You are a research assistant.",
                        model_name: "gpt-4o",
                        role: "worker",
                        max_loops: 1
                    },
                    {
                        agent_name: "Analysis Agent",
                        description: "Analyzes data",
                        system_prompt: "You are a data analyst.",
                        model_name: "gpt-4o",
                        role: "worker",
                        max_loops: 1
                    }
                ],
                max_loops: 1,
                swarm_type: "SequentialWorkflow",
                task: "Research AI advancements."
            },
            {
                name: "Batch Swarm 2",
                description: "Second swarm in the batch",
                agents: [
                    {
                        agent_name: "Writing Agent",
                        description: "Writes content",
                        system_prompt: "You are a content writer.",
                        model_name: "gpt-4o",
                        role: "worker",
                        max_loops: 1
                    },
                    {
                        agent_name: "Editing Agent",
                        description: "Edits content",
                        system_prompt: "You are an editor.",
                        model_name: "gpt-4o",
                        role: "worker",
                        max_loops: 1
                    }
                ],
                max_loops: 1,
                swarm_type: "SequentialWorkflow",
                task: "Write a summary of AI research."
            }
        ];

        try {
            const response = await fetch(`${API_BASE_URL}/v1/swarm/batch/completions`, {
                method: 'POST',
                headers: {
                    'x-api-key': API_KEY,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(batchSwarms)
            });

            if (response.ok) {
                const results = await response.json();
                console.log(`Batch completed with ${results.length} swarms`);
                results.forEach((result: any, index: number) => {
                    console.log(`Swarm ${index + 1}: ${result.swarm_name} - ${result.status}`);
                });
            } else {
                console.error(`Error: ${response.status} - ${await response.text()}`);
            }
        } catch (error) {
            console.error("Request failed:", error);
        }
    }

    runBatchSwarms();
    ```

**Example Response**:
```json
[
  {
    "status": "success",
    "swarm_name": "risk-analysis",
    "task": "Analyze risk factors for investment portfolio",
    "output": {...},
    "metadata": {...}
  },
  {
    "status": "success",
    "swarm_name": "market-sentiment",
    "task": "Assess current market sentiment for technology sector",
    "output": {...},
    "metadata": {...}
  }
]
```

## Individual Agent Endpoints

### Run Single Agent

Run a single agent with the specified configuration.

**Endpoint**: `/v1/agent/completions`  
**Method**: POST  
**Rate Limit**: 100 requests per 60 seconds

**Request Parameters**:

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| agent_config | AgentSpec | Configuration for the agent | Yes |
| task | string | The task to be completed by the agent | Yes |

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/agent/completions" \
         -H "x-api-key: your_api_key_here" \
         -H "Content-Type: application/json" \
         -d '{
           "agent_config": {
             "agent_name": "Research Assistant",
             "description": "Helps with research tasks",
             "system_prompt": "You are a research assistant expert.",
             "model_name": "gpt-4o",
             "max_loops": 1,
             "max_tokens": 8192,
             "temperature": 0.5
           },
           "task": "Research the latest developments in quantum computing."
         }'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    agent_request = {
        "agent_config": {
            "agent_name": "Research Assistant",
            "description": "Helps with research tasks",
            "system_prompt": "You are a research assistant expert.",
            "model_name": "gpt-4o",
            "max_loops": 1,
            "max_tokens": 8192,
            "temperature": 0.5
        },
        "task": "Research the latest developments in quantum computing."
    }
    
    response = requests.post(
        f"{API_BASE_URL}/v1/agent/completions",
        headers=headers,
        json=agent_request
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f"Agent {result['name']} completed successfully!")
        print(f"Usage: {result['usage']['total_tokens']} tokens")
        print(f"Output: {result['outputs']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

=== "TypeScript (fetch)"
    ```typescript
    interface AgentConfig {
        agent_name: string;
        description: string;
        system_prompt: string;
        model_name: string;
        max_loops: number;
        max_tokens: number;
        temperature: number;
    }

    interface AgentRequest {
        agent_config: AgentConfig;
        task: string;
    }

    const API_BASE_URL = "https://api.swarms.world";
    const API_KEY = "your_api_key_here";

    async function runSingleAgent(): Promise<void> {
        const agentRequest: AgentRequest = {
            agent_config: {
                agent_name: "Research Assistant",
                description: "Helps with research tasks",
                system_prompt: "You are a research assistant expert.",
                model_name: "gpt-4o",
                max_loops: 1,
                max_tokens: 8192,
                temperature: 0.5
            },
            task: "Research the latest developments in quantum computing."
        };

        try {
            const response = await fetch(`${API_BASE_URL}/v1/agent/completions`, {
                method: 'POST',
                headers: {
                    'x-api-key': API_KEY,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(agentRequest)
            });

            if (response.ok) {
                const result = await response.json();
                console.log(`Agent ${result.name} completed successfully!`);
                console.log(`Usage: ${result.usage.total_tokens} tokens`);
                console.log(`Output:`, result.outputs);
            } else {
                console.error(`Error: ${response.status} - ${await response.text()}`);
            }
        } catch (error) {
            console.error("Request failed:", error);
        }
    }

    runSingleAgent();
    ```

**Example Response**:
```json
{
  "id": "agent-abc123",
  "success": true,
  "name": "Research Assistant",
  "description": "Helps with research tasks",
  "temperature": 0.5,
  "outputs": {},
  "usage": {
    "input_tokens": 150,
    "output_tokens": 450,
    "total_tokens": 600
  },
  "timestamp": "2024-03-05T12:34:56.789Z"
}
```

### AgentCompletion Model

The `AgentCompletion` model defines the configuration for running a single agent task.

| Field | Type | Description | Required |
|-------|------|-------------|----------|
| `agent_config` | AgentSpec | The configuration of the agent to be completed | Yes |
| `task` | string | The task to be completed by the agent | Yes |
| `history` | Dict[str, Any] | The history of the agent's previous tasks and responses | No |


### AgentSpec Model

The `AgentSpec` model defines the configuration for an individual agent.

| Field | Type | Default | Description | Required |
|-------|------|---------|-------------|----------|
| `agent_name` | string | None | The unique name assigned to the agent | Yes |
| `description` | string | None | Detailed explanation of the agent's purpose | No |
| `system_prompt` | string | None | Initial instruction provided to the agent | No |
| `model_name` | string | "gpt-4o-mini" | Name of the AI model to use | No |
| `auto_generate_prompt` | boolean | false | Whether to auto-generate prompts | No |
| `max_tokens` | integer | 8192 | Maximum tokens in response | No |
| `temperature` | float | 0.5 | Controls randomness (0-1) | No |
| `role` | string | "worker" | Role of the agent | No |
| `max_loops` | integer | 1 | Maximum iterations | No |
| `tools_list_dictionary` | List[Dict] | None | Available tools for the agent | No |
| `mcp_url` | string | None | URL for Model Control Protocol | No |


Execute a task using a single agent with specified configuration.

**Endpoint**: `/v1/agent/completions`  
**Method**: POST  
**Rate Limit**: 100 requests per 60 seconds

**Request Body**:
```json
{
  "agent_config": {
    "agent_name": "Research Assistant",
    "description": "Specialized in research and analysis",
    "system_prompt": "You are an expert research assistant.",
    "model_name": "gpt-4o",
    "auto_generate_prompt": false,
    "max_tokens": 8192,
    "temperature": 0.5,
    "role": "worker",
    "max_loops": 1,
    "tools_list_dictionary": [
      {
        "name": "search",
        "description": "Search the web for information",
        "parameters": {
          "query": "string"
        }
      }
    ],
    "mcp_url": "https://example-mcp.com"
  },
  "task": "Research the latest developments in quantum computing and summarize key findings",
  "history": {
    "previous_research": "Earlier findings on quantum computing basics...",
    "user_preferences": "Focus on practical applications..."
  }
}
```

**Response**:
```json
{
  "id": "agent-abc123xyz",
  "success": true,
  "name": "Research Assistant",
  "description": "Specialized in research and analysis",
  "temperature": 0.5,
  "outputs": {
    "research_summary": "...",
    "key_findings": [
      "..."
    ]
  },
  "usage": {
    "input_tokens": 450,
    "output_tokens": 850,
    "total_tokens": 1300,
    "mcp_url": 0.1
  },
  "timestamp": "2024-03-05T12:34:56.789Z"
}
```

#### Run Batch Agents

Execute multiple agent tasks in parallel.

**Endpoint**: `/v1/agent/batch/completions`  
**Method**: POST  
**Rate Limit**: 100 requests per 60 seconds  
**Maximum Batch Size**: 10 requests
**Input** A list of `AgentCompeletion` inputs

=== "Shell (curl)"
    ```bash
    curl -X POST "https://api.swarms.world/v1/agent/batch/completions" \
         -H "x-api-key: your_api_key_here" \
         -H "Content-Type: application/json" \
         -d '[
           {
             "agent_config": {
               "agent_name": "Market Analyst",
               "description": "Expert in market analysis",
               "system_prompt": "You are a financial market analyst.",
               "model_name": "gpt-4o",
               "temperature": 0.3
             },
             "task": "Analyze the current market trends in AI technology sector"
           },
           {
             "agent_config": {
               "agent_name": "Technical Writer",
               "description": "Specialized in technical documentation",
               "system_prompt": "You are a technical documentation expert.",
               "model_name": "gpt-4o",
               "temperature": 0.7
             },
             "task": "Create a technical guide for implementing OAuth2 authentication"
           }
         ]'
    ```

=== "Python (requests)"
    ```python
    import requests
    import json

    API_BASE_URL = "https://api.swarms.world"
    API_KEY = "your_api_key_here"
    
    headers = {
        "x-api-key": API_KEY,
        "Content-Type": "application/json"
    }
    
    batch_agents = [
        {
            "agent_config": {
                "agent_name": "Market Analyst",
                "description": "Expert in market analysis",
                "system_prompt": "You are a financial market analyst.",
                "model_name": "gpt-4o",
                "temperature": 0.3
            },
            "task": "Analyze the current market trends in AI technology sector"
        },
        {
            "agent_config": {
                "agent_name": "Technical Writer",
                "description": "Specialized in technical documentation",
                "system_prompt": "You are a technical documentation expert.",
                "model_name": "gpt-4o",
                "temperature": 0.7
            },
            "task": "Create a technical guide for implementing OAuth2 authentication"
        }
    ]
    
    response = requests.post(
        f"{API_BASE_URL}/v1/agent/batch/completions",
        headers=headers,
        json=batch_agents
    )
    
    if response.status_code == 200:
        result = response.json()
        print(f"Batch completed with {result['total_requests']} agents")
        print(f"Execution time: {result['execution_time']} seconds")
        print("\nResults:")
        for i, agent_result in enumerate(result['results']):
            print(f"  Agent {i+1}: {agent_result['name']} - {agent_result['success']}")
    else:
        print(f"Error: {response.status_code} - {response.text}")
    ```

=== "TypeScript (fetch)"
    ```typescript
    interface AgentConfig {
        agent_name: string;
        description: string;
        system_prompt: string;
        model_name: string;
        temperature: number;
    }

    interface AgentCompletion {
        agent_config: AgentConfig;
        task: string;
    }

    const API_BASE_URL = "https://api.swarms.world";
    const API_KEY = "your_api_key_here";

    async function runBatchAgents(): Promise<void> {
        const batchAgents: AgentCompletion[] = [
            {
                agent_config: {
                    agent_name: "Market Analyst",
                    description: "Expert in market analysis",
                    system_prompt: "You are a financial market analyst.",
                    model_name: "gpt-4o",
                    temperature: 0.3
                },
                task: "Analyze the current market trends in AI technology sector"
            },
            {
                agent_config: {
                    agent_name: "Technical Writer",
                    description: "Specialized in technical documentation",
                    system_prompt: "You are a technical documentation expert.",
                    model_name: "gpt-4o",
                    temperature: 0.7
                },
                task: "Create a technical guide for implementing OAuth2 authentication"
            }
        ];

        try {
            const response = await fetch(`${API_BASE_URL}/v1/agent/batch/completions`, {
                method: 'POST',
                headers: {
                    'x-api-key': API_KEY,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(batchAgents)
            });

            if (response.ok) {
                const result = await response.json();
                console.log(`Batch completed with ${result.total_requests} agents`);
                console.log(`Execution time: ${result.execution_time} seconds`);
                console.log("\nResults:");
                result.results.forEach((agentResult: any, index: number) => {
                    console.log(`  Agent ${index + 1}: ${agentResult.name} - ${agentResult.success}`);
                });
            } else {
                console.error(`Error: ${response.status} - ${await response.text()}`);
            }
        } catch (error) {
            console.error("Request failed:", error);
        }
    }

    runBatchAgents();
    ```

**Response**:
```json
{
  "batch_id": "agent-batch-xyz789",
  "total_requests": 2,
  "execution_time": 15.5,
  "timestamp": "2024-03-05T12:34:56.789Z",
  "results": [
    {
      "id": "agent-abc123",
      "success": true,
      "name": "Market Analyst",
      "outputs": {
        "market_analysis": "..."
      },
      "usage": {
        "input_tokens": 300,
        "output_tokens": 600,
        "total_tokens": 900
      }
    },
    {
      "id": "agent-def456",
      "success": true,
      "name": "Technical Writer",
      "outputs": {
        "technical_guide": "..."
      },
      "usage": {
        "input_tokens": 400,
        "output_tokens": 800,
        "total_tokens": 1200
      }
    }
  ]
}
```

-----

## Production Examples

## Error Handling

The Swarms API follows standard HTTP status codes for error responses:

| Status Code | Meaning | Handling Strategy |
|-------------|---------|-------------------|
| 400 | Bad Request | Validate request parameters before sending |
| 401 | Unauthorized | Check API key validity |
| 403 | Forbidden | Verify API key permissions |
| 404 | Not Found | Check endpoint URL and resource IDs |
| 429 | Too Many Requests | Implement exponential backoff retry logic |
| 500 | Internal Server Error | Retry with backoff, then contact support |

Error responses include a detailed message explaining the issue:

```json
{
  "detail": "Failed to create swarm: Invalid swarm_type specified"
}
```

## Rate Limiting

| Description | Details |
|-------------|---------|
| Rate Limit | 100 requests per 60-second window |
| Exceed Consequence | 429 status code returned |
| Recommended Action | Implement retry logic with exponential backoff |

## Billing & Cost Management

| Cost Factor | Description |
|-------------|-------------|
| Agent Count | Base cost per agent |
| Input Tokens | Cost based on size of input data and prompts |
| Output Tokens | Cost based on length of generated responses |
| Time of Day | Reduced rates during nighttime hours (8 PM to 6 AM PT) |
| Cost Information | Included in each response's metadata |

## Best Practices

### Task Description

| Practice | Description |
|----------|-------------|
| Detail | Provide detailed, specific task descriptions |
| Context | Include all necessary context and constraints |
| Structure | Structure complex inputs for easier processing |

### Agent Configuration

| Practice | Description |
|----------|-------------|
| Simple Tasks | Use `AutoSwarmBuilder` for automatic agent generation |
| Complex Tasks | Manually define agents with specific expertise |
| Workflow | Use appropriate `swarm_type` for your workflow pattern |

### Production Implementation

| Practice | Description |
|----------|-------------|
| Error Handling | Implement robust error handling and retries |
| Logging | Log API responses for debugging and auditing |
| Cost Monitoring | Monitor costs closely during development and testing |

### Cost Optimization

| Practice | Description |
|----------|-------------|
| Batching | Batch related tasks when possible |
| Scheduling | Schedule non-urgent tasks during discount hours |
| Scoping | Carefully scope task descriptions to reduce token usage |
| Caching | Cache results when appropriate |

## Support

| Support Type | Contact Information |
|--------------|---------------------|
| Documentation | [https://docs.swarms.world](https://docs.swarms.world) |
| Email | kye@swarms.world |
| Community | [https://discord.gg/EamjgSaEQf](https://discord.gg/EamjgSaEQf) |
| Marketplace | [https://swarms.world](https://swarms.world) |
| Website | [https://swarms.ai](https://swarms.ai) |

## Service Tiers

### Standard Tier

| Feature | Description |
|---------|-------------|
| Processing | Default processing tier |
| Execution | Immediate execution |
| Priority | Higher priority processing |
| Pricing | Standard pricing |
| Timeout | 5-minute timeout limit |

### Flex Tier

| Feature | Description |
|---------|-------------|
| Cost | Lower cost processing |
| Retries | Automatic retries (up to 3 attempts) |
| Timeout | 15-minute timeout |
| Discount | 75% discount on token costs |
| Suitability | Best for non-urgent tasks |
| Backoff | Exponential backoff on resource contention |
| Configuration | Set `service_tier: "flex"` in SwarmSpec |

--------------------------------------------------

# File: swarms_cloud/swarms_api_tools.md

# Swarms API with Tools Guide


Swarms API allows you to create and manage AI agent swarms with optional tool integration. This guide will walk you through setting up and using the Swarms API with tools.

## Prerequisites

- Python 3.7+
- Swarms API key
- Required Python packages:
  - `requests`

  - `python-dotenv`

## Installation & Setup

1. Install required packages:

```bash
pip install requests python-dotenv
```

2. Create a `.env` file in your project root:

```bash
SWARMS_API_KEY=your_api_key_here
```

3. Basic setup code:

```python
import os
import requests
from dotenv import load_dotenv
import json

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
```

## Creating a Swarm with Tools

### Step-by-Step Guide

1. Define your tool dictionary:
```python
tool_dictionary = {
    "type": "function",
    "function": {
        "name": "search_topic",
        "description": "Conduct an in-depth search on a specified topic",
        "parameters": {
            "type": "object",
            "properties": {
                "depth": {
                    "type": "integer",
                    "description": "Search depth (1-3)"
                },
                "detailed_queries": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "description": "Specific search queries"
                    }
                }
            },
            "required": ["depth", "detailed_queries"]
        }
    }
}
```

2. Create agent configurations:
```python
agent_config = {
    "agent_name": "Market Analyst",
    "description": "Analyzes market trends",
    "system_prompt": "You are a financial analyst expert.",
    "model_name": "openai/gpt-4",
    "role": "worker",
    "max_loops": 1,
    "max_tokens": 8192,
    "temperature": 0.5,
    "auto_generate_prompt": False,
    "tools_dictionary": [tool_dictionary]  # Optional: Add tools if needed
}
```

3. Create the swarm payload:
```python
payload = {
    "name": "Your Swarm Name",
    "description": "Swarm description",
    "agents": [agent_config],
    "max_loops": 1,
    "swarm_type": "ConcurrentWorkflow",
    "task": "Your task description",
    "output_type": "dict"
}
```

4. Make the API request:
```python
def run_swarm(payload):
    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload
    )
    return response.json()
```

## FAQ

### Do all agents need tools?
No, tools are optional for each agent. You can choose which agents have tools based on your specific needs. Simply omit the `tools_dictionary` field for agents that don't require tools.

### What types of tools can I use?
Currently, the API supports function-type tools. Each tool must have:
- A unique name

- A clear description

- Well-defined parameters with types and descriptions

### Can I mix agents with and without tools?
Yes, you can create swarms with a mix of tool-enabled and regular agents. This allows for flexible swarm architectures.

### What's the recommended number of tools per agent?
While there's no strict limit, it's recommended to:

- Keep tools focused and specific

- Only include tools that the agent needs

- Consider the complexity of tool interactions

## Example Implementation

Here's a complete example of a financial analysis swarm:

```python
def run_financial_analysis_swarm():
    payload = {
        "name": "Financial Analysis Swarm",
        "description": "Market analysis swarm",
        "agents": [
            {
                "agent_name": "Market Analyst",
                "description": "Analyzes market trends",
                "system_prompt": "You are a financial analyst expert.",
                "model_name": "openai/gpt-4",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False,
                "tools_dictionary": [
                    {
                        "type": "function",
                        "function": {
                            "name": "search_topic",
                            "description": "Conduct market research",
                            "parameters": {
                                "type": "object",
                                "properties": {
                                    "depth": {
                                        "type": "integer",
                                        "description": "Search depth (1-3)"
                                    },
                                    "detailed_queries": {
                                        "type": "array",
                                        "items": {"type": "string"}
                                    }
                                },
                                "required": ["depth", "detailed_queries"]
                            }
                        }
                    }
                ]
            }
        ],
        "max_loops": 1,
        "swarm_type": "ConcurrentWorkflow",
        "task": "Analyze top performing tech ETFs",
        "output_type": "dict"
    }
    
    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload
    )
    return response.json()
```

## Health Check

Always verify the API status before running swarms:

```python
def check_api_health():
    response = requests.get(f"{BASE_URL}/health", headers=headers)
    return response.json()
```

## Best Practices

1. **Error Handling**: Always implement proper error handling:
```python
def safe_run_swarm(payload):
    try:
        response = requests.post(
            f"{BASE_URL}/v1/swarm/completions",
            headers=headers,
            json=payload
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error running swarm: {e}")
        return None
```

2. **Environment Variables**: Never hardcode API keys

3. **Tool Design**: Keep tools simple and focused

4. **Testing**: Validate swarm configurations before production use

## Troubleshooting

Common issues and solutions:

1. **API Key Issues**
   - Verify key is correctly set in `.env`

   - Check key permissions

2. **Tool Execution Errors**
   - Validate tool parameters

   - Check tool function signatures

3. **Response Timeout**
   - Consider reducing max_tokens

   - Simplify tool complexity



```python
import os
import requests
from dotenv import load_dotenv
import json

load_dotenv()

API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"

headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}


def run_health_check():
    response = requests.get(f"{BASE_URL}/health", headers=headers)
    return response.json()


def run_single_swarm():
    payload = {
        "name": "Financial Analysis Swarm",
        "description": "Market analysis swarm",
        "agents": [
            {
                "agent_name": "Market Analyst",
                "description": "Analyzes market trends",
                "system_prompt": "You are a financial analyst expert.",
                "model_name": "openai/gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False,
                "tools_dictionary": [
                    {
                        "type": "function",
                        "function": {
                            "name": "search_topic",
                            "description": "Conduct an in-depth search on a specified topic or subtopic, generating a comprehensive array of highly detailed search queries tailored to the input parameters.",
                            "parameters": {
                                "type": "object",
                                "properties": {
                                    "depth": {
                                        "type": "integer",
                                        "description": "Indicates the level of thoroughness for the search. Values range from 1 to 3, where 1 represents a superficial search and 3 signifies an exploration of the topic.",
                                    },
                                    "detailed_queries": {
                                        "type": "array",
                                        "description": "An array of highly specific search queries that are generated based on the input query and the specified depth. Each query should be designed to elicit detailed and relevant information from various sources.",
                                        "items": {
                                            "type": "string",
                                            "description": "Each item in this array should represent a unique search query that targets a specific aspect of the main topic, ensuring a comprehensive exploration of the subject matter.",
                                        },
                                    },
                                },
                                "required": ["depth", "detailed_queries"],
                            },
                        },
                    },
                ],
            },
            {
                "agent_name": "Economic Forecaster",
                "description": "Predicts economic trends",
                "system_prompt": "You are an expert in economic forecasting.",
                "model_name": "gpt-4o",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
                "auto_generate_prompt": False,
                "tools_dictionary": [
                    {
                        "type": "function",
                        "function": {
                            "name": "search_topic",
                            "description": "Conduct an in-depth search on a specified topic or subtopic, generating a comprehensive array of highly detailed search queries tailored to the input parameters.",
                            "parameters": {
                                "type": "object",
                                "properties": {
                                    "depth": {
                                        "type": "integer",
                                        "description": "Indicates the level of thoroughness for the search. Values range from 1 to 3, where 1 represents a superficial search and 3 signifies an exploration of the topic.",
                                    },
                                    "detailed_queries": {
                                        "type": "array",
                                        "description": "An array of highly specific search queries that are generated based on the input query and the specified depth. Each query should be designed to elicit detailed and relevant information from various sources.",
                                        "items": {
                                            "type": "string",
                                            "description": "Each item in this array should represent a unique search query that targets a specific aspect of the main topic, ensuring a comprehensive exploration of the subject matter.",
                                        },
                                    },
                                },
                                "required": ["depth", "detailed_queries"],
                            },
                        },
                    },
                ],
            },
        ],
        "max_loops": 1,
        "swarm_type": "ConcurrentWorkflow",
        "task": "What are the best etfs and index funds for ai and tech?",
        "output_type": "dict",
    }

    response = requests.post(
        f"{BASE_URL}/v1/swarm/completions",
        headers=headers,
        json=payload,
    )

    print(response)
    print(response.status_code)
    # return response.json()
    output = response.json()

    return json.dumps(output, indent=4)


if __name__ == "__main__":
    result = run_single_swarm()
    print("Swarm Result:")
    print(result)

```

--------------------------------------------------

# File: swarms_memory/chromadb.md

# ChromaDB Documentation

ChromaDB is a specialized module designed to facilitate the storage and retrieval of documents using the ChromaDB system. It offers functionalities for adding documents to a local ChromaDB collection and querying this collection based on provided query texts. This module integrates with the ChromaDB client to create and manage collections, leveraging various configurations for optimizing the storage and retrieval processes.


#### Parameters

| Parameter      | Type              | Default  | Description                                                 |
|----------------|-------------------|----------|-------------------------------------------------------------|
| `metric`       | `str`             | `"cosine"`| The similarity metric to use for the collection.             |
| `output_dir`   | `str`             | `"swarms"`| The name of the collection to store the results in.         |
| `limit_tokens` | `Optional[int]`   | `1000`   | The maximum number of tokens to use for the query.          |
| `n_results`    | `int`             | `1`      | The number of results to retrieve.                          |
| `docs_folder`  | `Optional[str]`   | `None`   | The folder containing documents to be added to the collection.|
| `verbose`      | `bool`            | `False`  | Flag to enable verbose logging for debugging.               |
| `*args`        | `tuple`           | `()`     | Additional positional arguments.                            |
| `**kwargs`     | `dict`            | `{}`     | Additional keyword arguments.                               |

#### Methods

| Method                | Description                                              |
|-----------------------|----------------------------------------------------------|
| `__init__`            | Initializes the ChromaDB instance with specified parameters. |
| `add`                 | Adds a document to the ChromaDB collection.              |
| `query`               | Queries documents from the ChromaDB collection based on the query text. |
| `traverse_directory`  | Traverses the specified directory to add documents to the collection. |


## Usage

```python
from swarms_memory import ChromaDB

chromadb = ChromaDB(
    metric="cosine",
    output_dir="results",
    limit_tokens=1000,
    n_results=2,
    docs_folder="path/to/docs",
    verbose=True,
)
```

### Adding Documents

The `add` method allows you to add a document to the ChromaDB collection. It generates a unique ID for each document and adds it to the collection.

#### Parameters

| Parameter     | Type   | Default | Description                                 |
|---------------|--------|---------|---------------------------------------------|
| `document`    | `str`  | -       | The document to be added to the collection. |
| `*args`       | `tuple`| `()`    | Additional positional arguments.            |
| `**kwargs`    | `dict` | `{}`    | Additional keyword arguments.               |

#### Returns

| Type  | Description                          |
|-------|--------------------------------------|
| `str` | The ID of the added document.        |

#### Example

```python
task = "example_task"
result = "example_result"
result_id = chromadb.add(document="This is a sample document.")
print(f"Document ID: {result_id}")
```

### Querying Documents

The `query` method allows you to retrieve documents from the ChromaDB collection based on the provided query text.

#### Parameters

| Parameter   | Type   | Default | Description                            |
|-------------|--------|---------|----------------------------------------|
| `query_text`| `str`  | -       | The query string to search for.        |
| `*args`     | `tuple`| `()`    | Additional positional arguments.       |
| `**kwargs`  | `dict` | `{}`    | Additional keyword arguments.          |

#### Returns

| Type  | Description                          |
|-------|--------------------------------------|
| `str` | The retrieved documents as a string. |

#### Example

```python
query_text = "search term"
results = chromadb.query(query_text=query_text)
print(f"Retrieved Documents: {results}")
```

### Traversing Directory

The `traverse_directory` method traverses through every file in the specified directory and its subdirectories, adding the contents of each file to the ChromaDB collection.

#### Example

```python
chromadb.traverse_directory()
```

## Additional Information and Tips

### Verbose Logging

Enable the `verbose` flag during initialization to get detailed logs of the operations, which is useful for debugging.

```python
chromadb = ChromaDB(verbose=True)
```

### Handling Large Documents

When dealing with large documents, consider using the `limit_tokens` parameter to restrict the number of tokens processed in a single query.

```python
chromadb = ChromaDB(limit_tokens=500)
```

### Optimizing Query Performance

Use the appropriate similarity metric (`metric` parameter) that suits your use case for optimal query performance.

```python
chromadb = ChromaDB(metric="euclidean")
```

## References and Resources

- [ChromaDB Documentation](https://chromadb.io/docs)
- [Python UUID Module](https://docs.python.org/3/library/uuid.html)
- [Python os Module](https://docs.python.org/3/library/os.html)
- [Python logging Module](https://docs.python.org/3/library/logging.html)
- [dotenv Package](https://pypi.org/project/python-dotenv/)

By following this documentation, users can effectively utilize the ChromaDB module for managing document storage and retrieval in their applications.

--------------------------------------------------

# File: swarms_memory/faiss.md

# FAISSDB: Documentation

The `FAISSDB` class is a highly customizable wrapper for the FAISS (Facebook AI Similarity Search) library, designed for efficient similarity search and clustering of dense vectors. This class facilitates the creation of a Retrieval-Augmented Generation (RAG) system by providing methods to add documents to a FAISS index and query the index for similar documents. It supports custom embedding models, preprocessing functions, and other customizations to fit various use cases.


### Parameters

| Parameter              | Type                                             | Default                       | Description                                                                 |
|------------------------|--------------------------------------------------|-------------------------------|-----------------------------------------------------------------------------|
| `dimension`            | `int`                                            | `768`                         | Dimension of the document embeddings.                                       |
| `index_type`           | `str`                                            | `'Flat'`                      | Type of FAISS index to use (`'Flat'` or `'IVF'`).                           |
| `embedding_model`      | `Optional[Any]`                                  | `None`                        | Custom embedding model.                                                     |
| `embedding_function`   | `Optional[Callable[[str], List[float]]]`         | `None`                        | Custom function to generate embeddings from text.                           |
| `preprocess_function`  | `Optional[Callable[[str], str]]`                 | `None`                        | Custom function to preprocess text before embedding.                        |
| `postprocess_function` | `Optional[Callable[[List[Dict[str, Any]]], List[Dict[str, Any]]]]` | `None` | Custom function to postprocess the results.                                  |
| `metric`               | `str`                                            | `'cosine'`                    | Distance metric for FAISS index (`'cosine'` or `'l2'`).                     |
| `logger_config`        | `Optional[Dict[str, Any]]`                       | `None`                        | Configuration for the logger.                                               |

## Methods

### `__init__`

Initializes the FAISSDB instance, setting up the logger, creating the FAISS index, and configuring custom functions if provided.

### `add`

Adds a document to the FAISS index.

#### Parameters

| Parameter | Type                    | Default | Description                                     |
|-----------|-------------------------|---------|-------------------------------------------------|
| `doc`     | `str`                   | None    | The document to be added.                       |
| `metadata`| `Optional[Dict[str, Any]]` | None    | Additional metadata for the document.            |

#### Example Usage

```python
db = FAISSDB(dimension=768)
db.add("This is a sample document.", {"category": "sample"})
```

### `query`

Queries the FAISS index for similar documents.

#### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query`   | `str` | None    | The query string. |
| `top_k`   | `int` | `5`     | The number of top results to return. |

#### Returns

| Type | Description |
|------|-------------|
| `List[Dict[str, Any]]` | A list of dictionaries containing the top_k most similar documents. |

#### Example Usage

```python
results = db.query("What is artificial intelligence?")
for result in results:
    print(f"Score: {result['score']}, Text: {result['metadata']['text']}")
```

## Internal Methods

### `_setup_logger`

Sets up the logger with the given configuration.

#### Parameters

| Parameter | Type                    | Default | Description                              |
|-----------|-------------------------|---------|------------------------------------------|
| `config`  | `Optional[Dict[str, Any]]` | None    | Configuration for the logger.             |

### `_create_index`

Creates and returns a FAISS index based on the specified type and metric.

#### Parameters

| Parameter | Type  | Default | Description                                  |
|-----------|-------|---------|----------------------------------------------|
| `index_type` | `str`  | 'Flat'   | Type of FAISS index to use.                  |
| `metric`    | `str`  | 'cosine' | Distance metric for FAISS index.             |

#### Returns

| Type | Description      |
|------|------------------|
| `faiss.Index` | FAISS index instance. |

### `_default_embedding_function`

Default embedding function using the SentenceTransformer model.

#### Parameters

| Parameter | Type | Default | Description          |
|-----------|------|---------|----------------------|
| `text`    | `str` | None    | The input text to embed. |

#### Returns

| Type | Description       |
|------|-------------------|
| `List[float]` | Embedding vector for the input text. |

### `_default_preprocess_function`

Default preprocessing function.

#### Parameters

| Parameter | Type | Default | Description        |
|-----------|------|---------|--------------------|
| `text`    | `str` | None    | The input text to preprocess. |

#### Returns

| Type | Description      |
|------|------------------|
| `str` | Preprocessed text. |

### `_default_postprocess_function`

Default postprocessing function.

#### Parameters

| Parameter | Type | Default | Description                    |
|-----------|------|---------|--------------------------------|
| `results` | `List[Dict[str, Any]]` | None    | The results to postprocess.   |

#### Returns

| Type | Description              |
|------|--------------------------|
| `List[Dict[str, Any]]` | Postprocessed results. |

## Usage Examples

### Example 1: Basic Usage

```python
# Initialize the FAISSDB instance
db = FAISSDB(dimension=768, index_type="Flat")

# Add documents to the FAISS index
db.add("This is a document about AI.", {"category": "AI"})
db.add("Python is great for data science.", {"category": "Programming"})

# Query the FAISS index
results = db.query("Tell me about AI")
for result in results:
    print(f"Score: {result['score']}, Text: {result['metadata']['text']}")
```

### Example 2: Custom Functions

```python
from transformers import AutoTokenizer, AutoModel
import torch

# Custom embedding function using a HuggingFace model
def custom_embedding_function(text: str) -> List[float]:
    tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
    model = AutoModel.from_pretrained("bert-base-uncased")
    inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True, max_length=512)
    with torch.no_grad():
        outputs = model(**inputs)
    embeddings = outputs.last_hidden_state.mean(dim=1).squeeze().tolist()
    return embeddings

# Custom preprocessing function
def custom_preprocess(text: str) -> str:
    return text.lower().strip()

# Custom postprocessing function
def custom_postprocess(results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    for result in results:
        result["custom_score"] = result["score"] * 2  # Example modification
    return results

# Initialize the FAISSDB instance with custom functions
db = FAISSDB(
    dimension=768,
    index_type="Flat",
    embedding_function=custom_embedding_function,
    preprocess_function=custom_preprocess,
    postprocess_function=custom_postprocess,
    metric="cosine",
    logger_config={
        "handlers": [
            {"sink": "custom_faiss_rag_wrapper.log", "rotation": "1 GB"},
            {"sink": lambda msg: print(f"Custom log: {msg}", end="")}
        ],
    },
)

# Add documents to the FAISS index
db.add("This is a document about machine learning.", {"category": "ML"})
db.add("Python is a versatile programming language.", {"category": "Programming"})

# Query the FAISS index
results = db.query("Explain machine learning")
for result in results:
    print(f"Score: {result['score']}, Custom Score: {result['custom_score']}, Text: {result['metadata']['text']}")
```

## Additional Information and Tips

- Ensure that the dimension of the document embeddings matches the dimension specified during the initialization of the FAISSDB instance.
- Use custom embedding functions to leverage domain-specific models for generating embeddings.
- Custom preprocessing and postprocessing functions can help tailor the text processing and

 result formatting to specific needs.
- FAISS supports various types of indices; choose the one that best fits the application requirements (e.g., `Flat` for brute-force search, `IVF` for faster search with some accuracy trade-off).
- Properly configure the logger to monitor and debug the operations of the FAISSDB instance.

## References and Resources

- [FAISS GitHub Repository](https://github.com/facebookresearch/faiss)
- [Sentence Transformers Documentation](https://www.sbert.net/)
- [Loguru Documentation](https://loguru.readthedocs.io/en/stable/)
- [HuggingFace Transformers](https://huggingface.co/transformers/)

By following this documentation, users can effectively utilize the `FAISSDB` class for various similarity search and document retrieval tasks, customizing it to their specific needs through the provided hooks and functions.

--------------------------------------------------

# File: swarms_memory/index.md

# Announcing the Release of Swarms-Memory Package: Your Gateway to Efficient RAG Systems


We are thrilled to announce the release of the Swarms-Memory package, a powerful and easy-to-use toolkit designed to facilitate the implementation of Retrieval-Augmented Generation (RAG) systems. Whether you're a seasoned AI practitioner or just starting out, Swarms-Memory provides the tools you need to integrate high-performance, reliable RAG systems into your applications seamlessly.

In this blog post, we'll walk you through getting started with the Swarms-Memory package, covering installation, usage examples, and a detailed overview of supported RAG systems like Pinecone and ChromaDB. Let's dive in!

## What is Swarms-Memory?

Swarms-Memory is a Python package that simplifies the integration of advanced RAG systems into your projects. It supports multiple databases optimized for AI tasks, providing you with the flexibility to choose the best system for your needs. With Swarms-Memory, you can effortlessly handle large-scale AI tasks, vector searches, and more.

### Key Features

- **Easy Integration**: Quickly set up and start using powerful RAG systems.
- **Customizable**: Define custom embedding, preprocessing, and postprocessing functions.
- **Flexible**: Supports multiple RAG systems like ChromaDB and Pinecone, with more coming soon.
- **Scalable**: Designed to handle large-scale AI tasks efficiently.

## Supported RAG Systems

Here's an overview of the RAG systems currently supported by Swarms-Memory:

| RAG System | Status       | Description                                                                              | Documentation             | Website         |
|------------|--------------|------------------------------------------------------------------------------------------|---------------------------|-----------------|
| ChromaDB   | Available    | A high-performance, distributed database optimized for handling large-scale AI tasks.    | [ChromaDB Documentation](https://chromadb.com/docs) | [ChromaDB](https://chromadb.com) |
| Pinecone   | Available    | A fully managed vector database for adding vector search to your applications.           | [Pinecone Documentation](https://pinecone.io/docs) | [Pinecone](https://pinecone.io) |
| Redis      | Coming Soon  | An open-source, in-memory data structure store, used as a database, cache, and broker.   | [Redis Documentation](https://redis.io/documentation) | [Redis](https://redis.io) |
| Faiss      | Coming Soon  | A library for efficient similarity search and clustering of dense vectors by Facebook AI. | [Faiss Documentation](https://faiss.ai) | [Faiss](https://faiss.ai) |
| HNSW       | Coming Soon  | A graph-based algorithm for approximate nearest neighbor search, known for speed.        | [HNSW Documentation](https://hnswlib.github.io/hnswlib) | [HNSW](https://hnswlib.github.io/hnswlib) |

## Getting Started

### Requirements

Before you begin, ensure you have the following:

- Python 3.10
- `.env` file with your respective API keys (e.g., `PINECONE_API_KEY`)

### Installation

You can install the Swarms-Memory package using pip:

```bash
$ pip install swarms-memory
```

### Usage Examples

#### Pinecone

Here's a step-by-step guide on how to use Pinecone with Swarms-Memory:

1. **Import Required Libraries**:

```python
from typing import List, Dict, Any
from swarms_memory import PineconeMemory
```

2. **Define Custom Functions**:

```python
from transformers import AutoTokenizer, AutoModel
import torch

# Custom embedding function using a HuggingFace model
def custom_embedding_function(text: str) -> List[float]:
    tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
    model = AutoModel.from_pretrained("bert-base-uncased")
    inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True, max_length=512)
    with torch.no_grad():
        outputs = model(**inputs)
    embeddings = outputs.last_hidden_state.mean(dim=1).squeeze().tolist()
    return embeddings

# Custom preprocessing function
def custom_preprocess(text: str) -> str:
    return text.lower().strip()

# Custom postprocessing function
def custom_postprocess(results: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
    for result in results:
        result["custom_score"] = result["score"] * 2  # Example modification
    return results
```

3. **Initialize the Wrapper with Custom Functions**:

```python
wrapper = PineconeMemory(
    api_key="your-api-key",
    environment="your-environment",
    index_name="your-index-name",
    embedding_function=custom_embedding_function,
    preprocess_function=custom_preprocess,
    postprocess_function=custom_postprocess,
    logger_config={
        "handlers": [
            {"sink": "custom_rag_wrapper.log", "rotation": "1 GB"},
            {"sink": lambda msg: print(f"Custom log: {msg}", end="")},
        ],
    },
)
```

4. **Add Documents and Query**:

```python
# Adding documents
wrapper.add("This is a sample document about artificial intelligence.", {"category": "AI"})
wrapper.add("Python is a popular programming language for data science.", {"category": "Programming"})

# Querying
results = wrapper.query("What is AI?", filter={"category": "AI"})
for result in results:
    print(f"Score: {result['score']}, Custom Score: {result['custom_score']}, Text: {result['metadata']['text']}")
```

#### ChromaDB

Using ChromaDB with Swarms-Memory is straightforward. Here’s how:

1. **Import ChromaDB**:

```python
from swarms_memory import ChromaDB
```

2. **Initialize ChromaDB**:

```python
chromadb = ChromaDB(
    metric="cosine",
    output_dir="results",
    limit_tokens=1000,
    n_results=2,
    docs_folder="path/to/docs",
    verbose=True,
)
```

3. **Add and Query Documents**:

```python
# Add a document
doc_id = chromadb.add("This is a test document.")

# Query the document
result = chromadb.query("This is a test query.")

# Traverse a directory
chromadb.traverse_directory()

# Display the result
print(result)
```

## Join the Community

We're excited to see how you leverage Swarms-Memory in your projects! Join our community on Discord to share your experiences, ask questions, and stay updated on the latest developments.

- **🐦 Twitter**: [Follow us on Twitter](https://twitter.com/swarms_platform)
- **📢 Discord**: [Join the Agora Discord](https://discord.gg/EamjgSaEQf)
- **Swarms Platform**: [Visit our website](https://swarms.ai)
- **📙 Documentation**: [Read the Docs](https://docs.swarms.ai)

## Conclusion

The Swarms-Memory package brings a new level of ease and efficiency to building and managing RAG systems. With support for leading databases like ChromaDB and Pinecone, it's never been easier to integrate powerful, scalable AI solutions into your projects. We can't wait to see what you'll create with Swarms-Memory!

For more detailed usage examples and documentation, visit our [GitHub repository](https://github.com/swarms-ai/swarms-memory) and start exploring today!


--------------------------------------------------

# File: swarms_memory/pinecone.md

# PineconeMemory Documentation

The `PineconeMemory` class provides a robust interface for integrating Pinecone-based Retrieval-Augmented Generation (RAG) systems. It allows for adding documents to a Pinecone index and querying the index for similar documents. The class supports custom embedding models, preprocessing functions, and other customizations to suit different use cases.



#### Parameters

| Parameter            | Type                                          | Default                           | Description                                                                                          |
|----------------------|-----------------------------------------------|-----------------------------------|------------------------------------------------------------------------------------------------------|
| `api_key`            | `str`                                         | -                                 | Pinecone API key.                                                                                    |
| `environment`        | `str`                                         | -                                 | Pinecone environment.                                                                                |
| `index_name`         | `str`                                         | -                                 | Name of the Pinecone index to use.                                                                   |
| `dimension`          | `int`                                         | `768`                             | Dimension of the document embeddings.                                                                |
| `embedding_model`    | `Optional[Any]`                               | `None`                            | Custom embedding model. Defaults to `SentenceTransformer('all-MiniLM-L6-v2')`.                       |
| `embedding_function` | `Optional[Callable[[str], List[float]]]`      | `None`                            | Custom embedding function. Defaults to `_default_embedding_function`.                                |
| `preprocess_function`| `Optional[Callable[[str], str]]`              | `None`                            | Custom preprocessing function. Defaults to `_default_preprocess_function`.                           |
| `postprocess_function`| `Optional[Callable[[List[Dict[str, Any]]], List[Dict[str, Any]]]]`| `None`              | Custom postprocessing function. Defaults to `_default_postprocess_function`.                         |
| `metric`             | `str`                                         | `'cosine'`                        | Distance metric for Pinecone index.                                                                  |
| `pod_type`           | `str`                                         | `'p1'`                            | Pinecone pod type.                                                                                   |
| `namespace`          | `str`                                         | `''`                              | Pinecone namespace.                                                                                  |
| `logger_config`      | `Optional[Dict[str, Any]]`                    | `None`                            | Configuration for the logger. Defaults to logging to `rag_wrapper.log` and console output.           |

### Methods

#### `_setup_logger`

```python
def _setup_logger(self, config: Optional[Dict[str, Any]] = None)
```

Sets up the logger with the given configuration.

#### `_default_embedding_function`

```python
def _default_embedding_function(self, text: str) -> List[float]
```

Generates embeddings using the default SentenceTransformer model.

#### `_default_preprocess_function`

```python
def _default_preprocess_function(self, text: str) -> str
```

Preprocesses the input text by stripping whitespace.

#### `_default_postprocess_function`

```python
def _default_postprocess_function(self, results: List[Dict[str, Any]]) -> List[Dict[str, Any]]
```

Postprocesses the query results.

#### `add`

Adds a document to the Pinecone index.

| Parameter | Type                  | Default | Description                                   |
|-----------|-----------------------|---------|-----------------------------------------------|
| `doc`     | `str`                 | -       | The document to be added.                     |
| `metadata`| `Optional[Dict[str, Any]]` | `None`  | Additional metadata for the document.         |

#### `query`

Queries the Pinecone index for similar documents.

| Parameter | Type                    | Default | Description                                   |
|-----------|-------------------------|---------|-----------------------------------------------|
| `query`   | `str`                   | -       | The query string.                             |
| `top_k`   | `int`                   | `5`     | The number of top results to return.          |
| `filter`  | `Optional[Dict[str, Any]]` | `None`  | Metadata filter for the query.                |

## Usage


The `PineconeMemory` class is initialized with the necessary parameters to configure Pinecone and the embedding model. It supports a variety of custom configurations to suit different needs.

#### Example

```python
from swarms_memory import PineconeMemory

# Initialize PineconeMemory
memory = PineconeMemory(
    api_key="your-api-key",
    environment="us-west1-gcp",
    index_name="example-index",
    dimension=768
)
```

### Adding Documents

Documents can be added to the Pinecone index using the `add` method. The method accepts a document string and optional metadata.

#### Example

```python
doc = "This is a sample document to be added to the Pinecone index."
metadata = {"author": "John Doe", "date": "2024-07-08"}

memory.add(doc, metadata)
```

### Querying Documents

The `query` method allows for querying the Pinecone index for similar documents based on a query string. It returns the top `k` most similar documents.

#### Example

```python
query = "Sample query to find similar documents."
results = memory.query(query, top_k=5)

for result in results:
    print(result)
```

## Additional Information and Tips

### Custom Embedding and Preprocessing Functions

Custom embedding and preprocessing functions can be provided during initialization to tailor the document processing to specific requirements.

#### Example

```python
def custom_embedding_function(text: str) -> List[float]:
    # Custom embedding logic
    return [0.1, 0.2, 0.3]

def custom_preprocess_function(text: str) -> str:
    # Custom preprocessing logic
    return text.lower()

memory = PineconeMemory(
    api_key="your-api-key",
    environment="us-west1-gcp",
    index_name="example-index",
    embedding_function=custom_embedding_function,
    preprocess_function=custom_preprocess_function
)
```

### Logger Configuration

The logger can be configured to suit different logging needs. The default configuration logs to a file and the console.

#### Example

```python
logger_config = {
    "handlers": [
        {"sink": "custom_log.log", "rotation": "1 MB"},
        {"sink": lambda msg: print(msg, end="")},
    ]
}

memory = PineconeMemory(
    api_key="your-api-key",
    environment="us-west1-gcp",
    index_name="example-index",
    logger_config=logger_config
)
```

## References and Resources

- [Pinecone Documentation](https://docs.pinecone.io/)
- [SentenceTransformers Documentation](https://www.sbert.net/)
- [Loguru Documentation](https://loguru.readthedocs.io/en/stable/)

For further exploration and examples, refer to the official documentation and resources provided by Pinecone, SentenceTransformers, and Loguru.

This concludes the detailed documentation for the `PineconeMemory` class. The class offers a flexible and powerful interface for leveraging Pinecone's capabilities in retrieval-augmented generation systems. By supporting custom embeddings, preprocessing, and postprocessing functions, it can be tailored to a wide range of applications.

--------------------------------------------------

# File: swarms_platform/account_management.md

# Swarms Platform Account Management Documentation

This guide provides comprehensive, production-grade documentation for managing your account on the Swarms Platform. It covers account settings, profile management, billing, payment methods, subscription details, and cryptocurrency wallet management. Use this documentation to navigate the account management interface, understand available options, and perform account-related operations efficiently and securely.

---

## Table of Contents

1. [Overview](#overview)
2. [Accessing the Account Management Page](#accessing-the-account-management-page)
3. [Account Settings](#account-settings)
   - [Theme Mode](#theme-mode)
4. [Profile Management](#profile-management)
   - [Profile Information](#profile-information)
   - [Password Management](#password-management)
5. [Billing and Payment Methods](#billing-and-payment-methods)
   - [Subscription Status](#subscription-status)
   - [Payment Methods](#payment-methods)
6. [Cryptocurrency Wallet](#cryptocurrency-wallet)
   - [Wallet Overview](#wallet-overview)
   - [Exchange and Transaction History](#exchange-and-transaction-history)
7. [Additional Resources](#additional-resources)

---

## Overview

The Swarms Platform account management page, available at [https://swarms.world/platform/account](https://swarms.world/platform/account), allows you to configure and update your account settings and preferences. From here, you can manage the appearance of the platform, view and update profile details, manage your billing information and subscriptions, and handle your cryptocurrency wallet operations.

---

## Accessing the Account Management Page

To access your account management dashboard:
1. Log in to your Swarms Platform account.
2. Navigate to [https://swarms.world/platform/account](https://swarms.world/platform/account).

Once on this page, you will see several sections dedicated to different aspects of your account:

- **Account Settings:** Customize the platform appearance and user interface.
- **Profile:** View and manage personal details.
- **Billing:** Review credits, invoices, and manage your payment methods.
- **Crypto:** Manage your cryptocurrency wallet and transactions.

---

## Account Settings

This section allows you to modify your personal account preferences, including the visual theme.

### Theme Mode

You can choose between different theme options to tailor your user experience:

- **Single Theme:**  
  A fixed theme, independent of system settings.
  - **Example:**  
    - **Logo:** Swarms logo
    - **Terminal Command:**  
      ```bash
      pip3 install -U swarms
      ```
    - **Theme Options:**  
      - **light**  
      - **dark (default)**
  
- **Sync with System Theme:**  
  Automatically adjusts the platform theme to match your system's theme settings.

Select the theme mode that best fits your workflow. Changes are applied immediately across the platform.

---

## Profile Management

### Profile Information

The Profile section allows you to view and update your personal details:

- **View Details:**  
  Your current profile information is displayed, including contact details, username, and any additional settings.
  
- **Manage Profile:**  
  Options to update your information, ensuring your account details remain current.

### Password Management

For security purposes, it is important to regularly update your password:

- **Change Password:**  
  Select the **"Change password"** option to update your login credentials.  
  Ensure you choose a strong password and keep it confidential.

---

## Billing and Payment Methods

The Billing section helps you manage financial aspects of your account, including credits, invoices, and subscriptions.

### Subscription Status

Your subscription details are clearly displayed:

- **Current Plan:**  
  Options include **Free**, **Premium**, or **Enterprise**.
  
- **Status:**  
  The active subscription status is indicated (e.g., "Active").
  
- **Customer Portal:**  
  An option to open the customer portal for additional billing and subscription management.

### Payment Methods

Manage your payment methods and review your billing details:

- **Manage Cards:**  
  View existing payment methods.  
  **Example Entry:**
  - **Card Type:** mastercard
  - **Last 4 Digits:** ending in 9491
  - **Expiry Date:** 2030/2
  
- **Add Card:**  
  Use the **"Add Card"** option to register a new payment method securely.

### Credit System

Details of the credits available for your account:

- **Credits Available:**  
  Displays the current credit balance (e.g., `$20.00`).
  
- **Charge:**  
  Option to apply charges against your available credits.
  
- **Invoice:**  
  Review or download your invoices.

---

## Cryptocurrency Wallet

The Crypto section provides management tools for your cryptocurrency wallet and associated transactions.

### Wallet Overview

- **Connected Wallet:**  
  Displays your linked wallet information.
  - **Example:**  
    - **Wallet Identifier:** A truncated wallet ID (e.g., `EmVa...79Vb`)
  
- **$swarms Balance and Price:**
  - **Balance:**  
    Displays your current $swarms balance (e.g., `0.00`).
  - **Price:**  
    Current market price for $swarms (e.g., `$0.0400`).

### Exchange and Transaction History

- **Exchange Functionality:**  
  Option to exchange $swarms tokens for credits directly through the platform.
  
- **Transaction History:**  
  View a detailed log of wallet transactions, ensuring full transparency over all exchanges and wallet activity.

---

## Additional Resources

For further assistance or to learn more about managing your account on the Swarms Platform, refer to the following resources:

- [Help Center](https://swarms.world/help)
- [Customer Support](https://cal.com/swarms)
- [API Documentation](https://swarms.world/platform/api-keys) (for developers)

---

## Best Practices

- **Regular Updates:**  
  Periodically review your account settings, profile, and payment methods to ensure they are up-to-date.
  
- **Security Measures:**  
  Always use strong, unique passwords and consider enabling two-factor authentication if available.
  
- **Monitor Transactions:**  
  Regularly check your billing and wallet transaction history to detect any unauthorized activities promptly.



--------------------------------------------------

# File: swarms_platform/agents/agents_api.md

# Agents API Documentation

The `https://swarms.world/api/add-agent` endpoint allows users to add a new agent to the Swarms platform. This API accepts a POST request with a JSON body containing details of the agent, such as its name, description, use cases, language, tags and requirements. The request must be authenticated using an API key.

## Endpoint: Add Agent

- **URL:** `https://swarms.world/api/add-agent`
- **Method:** POST
- **Content-Type:** `application/json`
- **Authorization:** Bearer token required in the header

## Request Parameters

The request body should be a JSON object with the following attributes:

| Attribute      | Type     | Description                                                                | Required |
| -------------- | -------- | -------------------------------------------------------------------------- | -------- |
| `name`         | `string` | The name of the agent.                                                     | Yes      |
| `agent`        | `string` | The agent text.                                                            | Yes      |
| `description`  | `string` | A brief description of the agent.                                          | Yes      |
| `language`     | `string` | The agent's syntax language with a default of python                       | No       |
| `useCases`     | `array`  | An array of use cases, each containing a title and description.            | Yes      |
| `requirements` | `array`  | An array of requirements, each containing a package name and installation. | Yes      |
| `tags`         | `string` | Comma-separated tags for the agent.                                        | Yes      |

### `useCases` Structure

Each use case in the `useCases` array should be an object with the following attributes:

| Attribute     | Type     | Description                          | Required |
| ------------- | -------- | ------------------------------------ | -------- |
| `title`       | `string` | The title of the use case.           | Yes      |
| `description` | `string` | A brief description of the use case. | Yes      |

### `requirements` Structure

Each requirement in the `requirements` array should be an object with the following attributes:

| Attribute      | Type     | Description                          | Required |
| -------------- | -------- | ------------------------------------ | -------- |
| `package`      | `string` | The name of the package.             | Yes      |
| `installation` | `string` | Installation command for the package | Yes      |

## Example Usage

### Python

```python
import requests
import json
import os


url = "https://swarms.world/api/add-agent"

headers = {
  "Content-Type": "application/json",
  "Authorization": f"Bearer {os.getenv("SWARMS_API_KEY")}"
}

data = {
  "name": "Example Agent",
  "agent": "This is an example agent from an API route.",
  "description": "Description of the agent.",
  "language": "python",
  "useCases": [
      {"title": "Use case 1", "description": "Description of use case 1"},
      {"title": "Use case 2", "description": "Description of use case 2"}
  ],
  "requirements": [
      {"package": "pip", "installation": "pip install"},
      {"package": "pip3", "installation": "pip3 install"}
  ],
    "tags": "example, agent"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

### Node.js

```javascript
const fetch = require("node-fetch");

async function addAgentHandler() {
  try {
    const response = await fetch("https://swarms.world/api/add-agent", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer {apiKey}",
      },
      body: JSON.stringify({
        name: "Example Agent",
        agent: "This is an example agent from an API route.",
        description: "Description of the agent.",
        language: "python",
        useCases: [
          { title: "Use case 1", description: "Description of use case 1" },
          { title: "Use case 2", description: "Description of use case 2" },
        ],
        requirements: [
          { package: "pip", installation: "pip install" },
          { package: "pip3", installation: "pip3 install" },
        ],
        tags: "example, agent",
      }),
    });

    const result = await response.json();
    console.log(result);
  } catch (error) {
    console.error("An error has occurred", error);
  }
}

addAgentHandler();
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://swarms.world/api/add-agent"
    payload := map[string]interface{}{
        "name":       "Example Agent",
        "agent":      "This is an example agent from an API route.",
        "description": "Description of the agent.",
        "useCases": []map[string]string{
            {"title": "Use case 1", "description": "Description of use case 1"},
            {"title": "Use case 2", "description": "Description of use case 2"},
        },
        "requirements": []map[string]string{
            {"package": "pip", "installation": "pip install"},
            {"package": "pip3", "installation": "pip3 install"}
        },
        "tags": "example, agent",
    }
    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer {apiKey}")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("An error has occurred", err)
        return
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
```

### cURL

```bash
curl -X POST https://swarms.world/api/add-agent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {apiKey}" \
-d '{
    "name": "Example Agent",
    "agent": "This is an example agent from an API route.",
    "description": "Description of the agent.",
    "language": "python",
    "useCases": [
        { title: "Use case 1", description: "Description of use case 1" },
        { title: "Use case 2", description: "Description of use case 2" },
    ],
    "requirements": [
        { package: "pip", installation: "pip install" },
        { package: "pip3", installation: "pip3 install" },
    ],
    "tags": "example, agent",
}'
```

## Response

The response will be a JSON object containing the result of the operation. Example response:

```json
{
  "success": true,
  "message": "Agent added successfully",
  "data": {
    "id": "agent_id",
    "name": "Example Agent",
    "agent": "This is an example agent from an API route.",
    "description": "Description of the agent.",
    "language": "python",
    "useCases": [
      { "title": "Use case 1", "description": "Description of use case 1" },
      { "title": "Use case 2", "description": "Description of use case 2" }
    ],
    "requirements": [
      { "package": "pip", "installation": "pip install" },
      { "package": "pip3", "installation": "pip3 install" }
    ],
    "tags": "example, agent"
  }
}
```

--------------------------------------------------

# File: swarms_platform/agents/edit_agent.md


# Endpoint: Edit Agent

The `https://swarms.world/api/edit-agent` endpoint allows users to edit an existing agent on the Swarms platform. This API accepts a POST request with a JSON body containing the agent details to be updated, such as its id, name, description, use cases, language, tags and requirements. The request must be authenticated using an API key.

## Endpoint

- **URL:** `https://swarms.world/api/edit-agent`
- **Method:** POST
- **Content-Type:** `application/json`
- **Authorization:** Bearer token required in the header

## Request Parameters

The request body should be a JSON object with the following attributes:

| Attribute      | Type     | Description                                                                | Required |
| -------------- | -------- | -------------------------------------------------------------------------- | -------- |
| `id`           | `string` | The ID of the agent to be edited.                                          | Yes      |
| `name`         | `string` | The name of the agent.                                                     | Yes      |
| `agent`        | `string` | The agent text.                                                            | Yes      |
| `description`  | `string` | A brief description of the agent.                                          | Yes      |
| `language`     | `string` | The agent's syntax language                                                | No       |
| `useCases`     | `array`  | An array of use cases, each containing a title and description.            | Yes      |
| `requirements` | `array`  | An array of requirements, each containing a package name and installation. | Yes      |
| `tags`         | `string` | Comma-separated tags for the agent.                                        | No       |

### `useCases` Structure

Each use case in the `useCases` array should be an object with the following attributes:

| Attribute     | Type     | Description                          | Required |
| ------------- | -------- | ------------------------------------ | -------- |
| `title`       | `string` | The title of the use case.           | Yes      |
| `description` | `string` | A brief description of the use case. | Yes      |

### `requirements` Structure

Each requirement in the `requirements` array should be an object with the following attributes:

| Attribute      | Type     | Description                          | Required |
| -------------- | -------- | ------------------------------------ | -------- |
| `package`      | `string` | The name of the package.             | Yes      |
| `installation` | `string` | Installation command for the package | Yes      |

## Example Usage

### Python

```python
import requests
import json

url = "https://swarms.world/api/edit-agent"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {apiKey}"
}
data = {
    "id": "agent_id",
    "name": "Updated agent",
    "agent": "This is an updated agent from an API route.",
    "description": "Updated description of the agent.",
    "language": "javascript",
    "useCases": [
        {"title": "Updated use case 1", "description": "Updated description of use case 1"},
        {"title": "Updated use case 2", "description": "Updated description of use case 2"}
    ],
    "requirements": [
        { "package": "express", "installation": "npm install express" },
        { "package": "lodash", "installation": "npm install lodash" },
    ],
    "tags": "updated, agent"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

### Node.js

```javascript
const fetch = require("node-fetch");

async function editAgentHandler() {
  try {
    const response = await fetch("https://swarms.world/api/edit-agent", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer {apiKey}",
      },
      body: JSON.stringify({
        id: "agent_id",
        name: "Updated agent",
        agent: "This is an updated agent from an API route.",
        description: "Updated description of the agent.",
        language: "javascript",
        useCases: [
          {
            title: "Updated use case 1",
            description: "Updated description of use case 1",
          },
          {
            title: "Updated use case 2",
            description: "Updated description of use case 2",
          },
        ],
        requirements: [
          { package: "express", installation: "npm install express" },
          { package: "lodash", installation: "npm install lodash" },
        ],
        tags: "updated, agent",
      }),
    });

    const result = await response.json();
    console.log(result);
  } catch (error) {
    console.error("An error has occurred", error);
  }
}

editAgentHandler();
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://swarms.world/api/edit-agent"
    payload := map[string]interface{}{
        "id":          "agent_id",
        "name":        "Updated Agent",
        "agent":      "This is an updated agent from an API route.",
        "description": "Updated description of the agent.",
        "language": "javascript",
        "useCases": []map[string]string{
            {"title": "Updated use case 1", "description": "Updated description of use case 1"},
            {"title": "Updated use case 2", "description": "Updated description of use case 2"},
        },
        "requirements": []map[string]string{
            {"package": "express", "installation": "npm install express"},
            {"package": "lodash", "installation": "npm install lodash"},
        },
        "tags": "updated, agent",
    }
    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer {apiKey}")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("An error has occurred", err)
        return
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
```

### cURL

```bash
curl -X POST https://swarms.world/api/edit-agent \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {apiKey}" \
-d '{
    "id": "agent_id",
    "name": "Updated agent",
    "agent": "This is an updated agent from an API route.",
    "description": "Updated description of the agent.",
    "language": "javascript",
    "useCases": [
        {"title": "Updated use case 1", "description": "Updated description of use case 1"},
        {"title": "Updated use case 2", "description": "Updated description of use case 2"}
    ],
    "requirements": [
        { "package": "express", "installation": "npm install express" },
        { "package": "lodash", "installation": "npm install lodash" },
    ],
    "tags": "updated, agent"
}'
```

## Response

The response will be a JSON object containing the result of the operation. Example response:

```json
{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "id": "agent_id",
    "name": "Updated agent",
    "agent": "This is an updated agent from an API route.",
    "description": "Updated description of the agent.",
    "language": "javascript",
    "useCases": [
      {
        "title": "Updated use case 1",
        "description": "Updated description of use case 1"
      },
      {
        "title": "Updated use case 2",
        "description": "Updated description of use case 2"
      }
    ],
    "requirements": [
      { "package": "express", "installation": "npm install express" },
      { "package": "lodash", "installation": "npm install lodash" }
    ],
    "tags": "updated, agent"
  }
}
```

In case of an error, the response will contain an error message detailing the issue.

## Common Issues and Tips

- **Authentication Error:** Ensure that the `Authorization` header is correctly set with a valid API key.
- **Invalid JSON:** Make sure the request body is a valid JSON object.
- **Missing Required Fields:** Ensure that all required fields (`name`, `agent`, `description`, `useCases`, `requirements`) are included in the request body.
- **Network Issues:** Verify network connectivity and endpoint URL.

## References and Resources

- [API Authentication Guide](https://swarms.world/docs/authentication)
- [JSON Structure Standards](https://json.org/)
- [Fetch API Documentation (Node.js)](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
- [Requests Library (Python)](https://requests.readthedocs.io/)
- [Net/HTTP Package (Go)](https://pkg.go.dev/net/http)

This comprehensive documentation provides all the necessary information to effectively use the `https://swarms.world/api/add-agent` and `https://swarms.world/api/edit-agent` endpoints, including details on request parameters, example code snippets in multiple programming languages, and troubleshooting tips.


--------------------------------------------------

# File: swarms_platform/agents/fetch_agents.md

# Documentation for `getAllAgents` API Endpoint

The `getAllAgents` API endpoint is a part of the `swarms.world` application, designed to fetch all agent records from the database. This endpoint is crucial for retrieving various agents stored in the `swarms_cloud_agents` table, including their metadata such as name, description, use cases, language, requirements and tags. It provides an authenticated way to access this data, ensuring that only authorized users can retrieve the information.

## Purpose

The primary purpose of this API endpoint is to provide a method for clients to fetch a list of agents stored in the `swarms_cloud_agents` table, with the ability to filter by name, tags, language, requirement package and use cases. It ensures data integrity and security by using an authentication guard and handles various HTTP methods and errors gracefully.

## API Endpoint Definition

### Fetch All Agents

#### Endpoint URL

```
https://swarms.world/get-agents
```

#### HTTP Method

```
GET
```

### Request Headers

| Header        | Type   | Required | Description                 |
| ------------- | ------ | -------- | --------------------------- |
| Authorization | String | Yes      | Bearer token for API access |

### Query Parameters

- **name** (optional): A substring to match against the agent name. The query is case-insensitive.
- **tag** (optional): A comma-separated list of tags to filter agents by. The query matches any of the provided tags, and is case-insensitive.
- **language** (optional): A substring to match against the language the agent is written in. The query is case-insensitive.
- **use_case** (optional): A substring to match against the use case titles within the `use_cases` array. The query is case-insensitive.
- **req_package** (optional): A substring to match against the requirement packaages within the `requirements` array. The query is case-insensitive.

#### Response

##### Success Response (200)

Returns an array of agents.

```json
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "language": "string",
    "agent": "string",
    "use_cases": [
      {
        "title": "string",
        "description": "string"
      }
    ],
    "requirements": [
      {
        "package": "string",
        "installation": "string"
      }
    ],
    "tags": "string"
  },
  ...
]
```

##### Error Responses

- **405 Method Not Allowed**

  ```json
  {
    "error": "Method <method> Not Allowed"
  }
  ```

- **500 Internal Server Error**

  ```json
  {
    "error": "Could not fetch agents"
  }
  ```

### Fetch Agent by ID

#### Endpoint URL

```
https://swarms.world/get-agents/[id]
```

#### HTTP Method

```
GET
```

### Request Headers

| Header        | Type   | Required | Description                 |
| ------------- | ------ | -------- | --------------------------- |
| Authorization | String | Yes      | Bearer token for API access |

#### Response

##### Success Response (200)

Returns a single agent by ID.

```json
{
  "id": "string",
  "name": "string",
  "description": "string",
  "language": "string",
  "agent": "string",
  "use_cases": [
    {
      "title": "string",
      "description": "string"
    }
  ],
  "requirements": [
    {
      "package": "string",
      "installation": "string"
    }
  ],
  "tags": "string"
}
```

##### Error Responses

- **404 Not Found**

  ```json
  {
    "error": "Agent not found"
  }
  ```

- **500 Internal Server Error**

  ```json
  {
    "error": "Could not fetch agent"
  }
  ```

### Request Handling

1. **Method Validation**: The endpoint only supports the `GET` method. If a different HTTP method is used, it responds with a `405 Method Not Allowed` status.

2. **Database Query**:

   - **Fetching All Agents**: The endpoint uses the `supabaseAdmin` client to query the `swarms_cloud_agents` table. Filters are applied based on the query parameters (`name`, `tag`, `language`, `req_package` and `use_case`).
   - **Fetching an Agent by ID**: The endpoint retrieves a single agent from the `swarms_cloud_agents` table by its unique ID.

3. **Response**: On success, it returns the agent data in JSON format. In case of an error during the database query, a `500 Internal Server Error` status is returned. For fetching by ID, if the agent is not found, it returns a `404 Not Found` status.

### Code Example

#### JavaScript (Node.js)

```javascript
import fetch from "node-fetch";

// Fetch all agents with optional filters
const getAgents = async (filters) => {
  const queryString = new URLSearchParams(filters).toString();
  const response = await fetch(
    `https://swarms.world/get-agents?${queryString}`,
    {
      method: "GET",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer {apiKey}",
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
};

// Fetch agent by ID
const getAgentById = async (id) => {
  const response = await fetch(`https://swarms.world/get-agents/${id}`, {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Bearer {apiKey}",
    },
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
};

// Example usage
getAgents({
  name: "example",
  tag: "tag1,tag2",
  use_case: "example",
  language: "langauge",
  req_package: "package_name",
}).catch(console.error);
getAgentById("123").catch(console.error);
```

#### Python

```python
import requests

API_KEY = "{apiKey}"

# Fetch all agents with optional filters
def get_agents(filters):
    query_string = "&".join([f"{key}={value}" for key, value in filters.items()])
    url = f"https://swarms.world/get-agents?{query_string}"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    }
    response = requests.get(url, headers=headers)

    if not response.ok:
        raise Exception(f"Error: {response.reason}")

    data = response.json()
    print(data)
    return data

# Fetch agent by ID
def get_agent_by_id(agent_id):
    url = f"https://swarms.world/get-agents/{agent_id}"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {API_KEY}",
    }
    response = requests.get(url, headers=headers)

    if not response.ok:
        raise Exception(f"Error: {response.reason}")

    data = response.json()
    print(data)
    return data

# Example usage
try:
    get_agents({
        "name": "example",
        "tag": "tag1,tag2",
        "use_case": "example",
        "language": "language",
        "req_package": "package_name",
    })
except Exception as e:
    print(e)

try:
    get_agent_by_id("123")
except Exception as e:
    print(e)
```

#### cURL

```sh
# Fetch all agents with optional filters
curl -X GET "https://swarms.world/get-agents?name=example&tag=tag1,tag2&use_case=example&language=language&req_package=package_name" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {apiKey}"

# Fetch agent by ID
curl -X GET "https://swarms.world/get-agents/123" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {apiKey}"
```

#### Go

```go
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
	"os"
)

func getAgents(filters map[string]string) error {
	query := url.Values{}
	for key, value := range filters {
		query.Set(key, value)
	}

	url := fmt.Sprintf("https://swarms.world/get-agents?%s", query.Encode())
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return err
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer {apiKey}")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("error: %s", resp.Status)
	}

	var data interface{}
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		return err
	}

	fmt.Println(data)
	return nil
}

func getAgentById(id string) error {
	url := fmt.Sprintf("https://swarms.world/get-agents/%s", id)
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return err
	}

	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer {apiKey}")

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return fmt.Errorf("error: %s", resp.Status)
	}

	var data interface{}
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		return err
	}

	fmt.Println(data)
	return nil
}
func main() {
	filters := map[string]string{
		"name":        "example",
		"tag":         "tag1,tag2",
		"use_case":    "example",
		"language":    "language",
		"req_package": "package_name",
	}

    getAgents(filters)
    getAgentById("123")
}
```

#### Attributes Table

| Attribute    | Type   | Description                     |
| ------------ | ------ | ------------------------------- |
| id           | String | Unique identifier for the agent |
| name         | String | Name of the agent               |
| description  | String | Description of the agent        |
| agent        | String | The actual agent                |
| lanuage      | String | The code language of the agent  |
| use_cases    | Array  | Use cases for the agent         |
| requirements | Array  | Requirements for the agent      |
| tags         | String | Tags associated with the agent  |

## Additional Information and Tips

- Handle different error statuses appropriately to provide clear feedback to users.
- Consider implementing rate limiting and logging for better security and monitoring.

## References and Resources

- [Next.js API Routes](https://nextjs.org/docs/api-routes/introduction)
- [Supabase Documentation](https://supabase.com/docs)
- [Node Fetch](https://www.npmjs.com/package/node-fetch)
- [Requests Library (Python)](https://docs.python-requests.org/en/latest/)
- [Go net/http Package](https://pkg.go.dev/net/http)

This documentation provides a comprehensive guide to the `getAllAgents` API endpoint, including usage examples in multiple programming languages and detailed attribute descriptions.


--------------------------------------------------

# File: swarms_platform/apikeys.md

# Swarms Platform API Keys Documentation

This document provides detailed information on managing API keys within the Swarms Platform. API keys grant programmatic access to your account and should be handled securely. Follow the guidelines below to manage your API keys safely and effectively.

---

## Table of Contents

1. [Overview](#overview)
2. [Viewing Your API Keys](#viewing-your-api-keys)
3. [Creating a New API Key](#creating-a-new-api-key)
4. [Security Guidelines](#security-guidelines)
5. [Frequently Asked Questions](#frequently-asked-questions)

---

## Overview

API keys are unique credentials that allow you to interact with the Swarms Platform programmatically. These keys enable you to make authenticated API requests to access or modify your data. **Important:** Once a secret API key is generated, it will not be displayed again. Ensure you store it securely, as it cannot be retrieved from the platform later.

---

## Viewing Your API Keys

When you navigate to the API Keys page ([https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)), you will see a list of your API keys along with the following information:

### Key Details:

- **Name:** A label you assign to your API key to help you identify it.
- **Key:** The secret API key is only partially visible here for security reasons.
- **Created Date:** The date when the API key was generated.
- **Actions:** Options available for managing the key (e.g., deleting an API key).

---

## Creating a New API Key

To generate a new API key, follow these steps:

1. **Attach a Credit Card:**  
   Before creating a new API key, ensure that your account has a credit card attached. This is required for authentication and billing purposes.

2. **Access the API Keys Page:**  
   Navigate to [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys).

3. **Generate a New Key:**  
   Click on the **"Create new API key"** button. The system will generate a new secret API key for your account.

4. **Store Your API Key Securely:**  
   Once generated, the full API key will be displayed only once. Copy and store it in a secure location, as it will not be displayed again.  
   **Note:** Do not share your API key with anyone or expose it in any client-side code (e.g., browser JavaScript).

---

## Security Guidelines

- **Confidentiality:**  
  Your API keys are sensitive credentials. Do not share them with anyone or include them in public repositories or client-side code.

- **Storage:**  
  Store your API keys in secure, encrypted storage. Avoid saving them in plain text files or unsecured locations.

- **Rotation:**  
  If you suspect that your API key has been compromised, immediately delete it and create a new one.

- **Access Control:**  
  Limit access to your API keys to only those systems and personnel who absolutely require it.

---

## Frequently Asked Questions

### Q1: **Why do I need a credit card attached to my account to create an API key?**  
**A:** The requirement to attach a credit card helps verify your identity and manage billing, ensuring responsible usage of the API services provided by the Swarms Platform.

### Q2: **What happens if I lose my API key?**  
**A:** If you lose your API key, you will need to generate a new one. The platform does not store the full key after its initial generation, so recovery is not possible.

### Q3: **How can I delete an API key?**  
**A:** On the API Keys page, locate the key you wish to delete and click the **"Delete"** action next to it. This will revoke the key's access immediately.

### Q4: **Can I have multiple API keys?**  
**A:** Yes, you can generate and manage multiple API keys. Use naming conventions to keep track of their usage and purpose.

---

For any further questions or issues regarding API key management, please refer to our [Help Center](https://swarms.world/help) or contact our support team.

--------------------------------------------------

# File: swarms_platform/apps_page.md

# Swarms Marketplace Apps Documentation


The Swarms Apps page (`https://swarms.world/apps`) is your central hub for managing and customizing your workspace experience. Here you can control which applications appear in your sidebar, organize them using templates, and quickly access the tools you need for different workflows.

## Apps Gallery

### Customizing Your Sidebar

The Apps Gallery allows you to curate your workspace by selecting which applications you want to see in your sidebar. This personalized approach ensures you have quick access to the tools most relevant to your work.

**Key Features:**

- **Selective App Display**: Choose exactly which apps appear in your sidebar

- **Favorites System**: Star your most-used apps to pin them for instant access

- **Quick Access**: Starred apps remain easily accessible regardless of your current template


### How to Use the Apps Gallery

1. **Browse Available Apps**: Scroll through the complete list of available applications
2. **Toggle App Visibility**: Click on apps to add or remove them from your sidebar
3. **Star Favorites**: Click the star icon on frequently used apps to pin them
4. **Instant Updates**: Changes to your sidebar configuration take effect immediately

## Quick Sidebar Templates

Templates provide pre-configured app collections optimized for specific workflows. Instead of manually selecting apps one by one, you can choose a template that matches your current needs.

### Available Templates

#### 🏪 Marketplace Template

*Perfect for discovering and managing marketplace content*

**Included Apps:**

- **Marketplace**: Browse and discover new tools, agents, and prompts

- **App Store**: Access autonomous AI applications  

- **Leaderboard**: View top creators and contributors

- **Dashboard**: Your main control center

- **Settings**: Account and organization configuration


**Best For:** Content discovery, community engagement, platform exploration

#### 🎨 No-Code Solutions Template  

*Ideal for users who prefer visual, drag-and-drop interfaces*

**Included Apps:**
- **Dashboard**: Central control and overview

- **Chat**: Direct communication with agents and team members

- **Spreadsheet**: Collaborative AI-powered spreadsheets

- **Drag n Drop**: Visual workflow builder for creating processes

- **Settings**: Platform configuration options


**Best For:** Visual workflow creation, collaborative work, rapid prototyping

#### 👨‍💻 Developer Template

*Designed for technical users and developers*

**Included Apps:**
- **Dashboard**: System overview and monitoring

- **API Key**: Manage authentication credentials  

- **Telemetry**: Monitor platform usage and analytics

- **Settings**: Advanced configuration options

- **Playground**: Testing and experimentation environment


**Best For:** API integration, performance monitoring, technical development

#### 📱 All Apps Template

*Comprehensive access to every available application*

**Features:**
- **Complete Access**: Activates all available apps in your sidebar

- **Maximum Flexibility**: Switch between any tool without reconfiguration

- **Full Feature Set**: Access to every platform capability


**Best For:** Power users, comprehensive workflows, exploration of all features

## App Categories

### Marketplace Applications

These apps focus on content discovery, community interaction, and marketplace functionality.

#### Dashboard

Your primary control center providing system overview, key metrics, and quick access to important functions.

#### Marketplace  

Discover and utilize new tools, agents, and prompts created by the community. Browse categories, read reviews, and integrate new capabilities into your workflows.

#### App Store

Access a curated collection of autonomous AI applications. These are complete solutions that can operate independently to accomplish specific tasks.

#### Leaderboard

View rankings of top creators, contributors, and most popular content. Discover trending tools and identify influential community members.

#### Marketplace Bookmarks
Organize and manage your saved marketplace items. Keep track of tools you want to try later or frequently reference.

### No Code Agent Platforms

Visual, user-friendly tools that don't require programming knowledge.

| Application | Description |
|-------------|-------------|
| Apps | Meta-application for managing your sidebar configuration. Add, remove, and organize your available applications. |
| Chat | Real-time communication interface for conversing with AI agents and team members. Supports both individual and group conversations. |
| Spreadsheet Swarm | AI-enhanced collaborative spreadsheets that combine familiar spreadsheet functionality with intelligent automation and team collaboration features. |
| Drag & Drop | Visual workflow builder allowing you to create complex processes using intuitive drag-and-drop interfaces. Connect different tools and actions without coding. |

### Account Settings

Configuration and management tools for your account and organization.

| Application | Description |
|-------------|-------------|
| API Keys | Secure management of your authentication credentials. Generate, rotate, and manage API keys for integrating external services. |
| Telemetry | Comprehensive analytics dashboard showing platform usage, performance metrics, and usage patterns. Monitor your organization's AI agent activity. |
| Settings | Central configuration hub for account preferences, organization settings, notification preferences, and platform customization options. |
| Playground | Safe testing environment for experimenting with new configurations, testing API calls, and prototyping workflows before implementing them in production. |

## Best Practices

### Template Selection Strategy

**Start with Templates**: Begin with a template that matches your primary use case, then customize as needed.

**Regular Review**: Periodically reassess your app selection as your needs evolve.

**Workflow-Specific**: Consider switching templates based on current projects or tasks.

### App Management Tips

**Star Strategically**: Only star apps you use daily to avoid sidebar clutter.

**Template Switching**: Don't hesitate to switch templates when your focus changes.

**Exploration**: Periodically activate the "All" template to discover new capabilities.

### Organization Recommendations

**Role-Based Setup**: Configure templates based on team roles (developers, content creators, analysts).

**Project Phases**: Adjust app selection based on project phases (research, development, deployment).

**Performance Monitoring**: Use telemetry data to optimize your app selection over time.

## Getting Started

1. **Visit the Apps Page**: Navigate to `https://swarms.world/apps`
2. **Choose a Template**: Select the template that best matches your immediate needs
3. **Customize**: Add or remove specific apps based on your preferences  
4. **Star Favorites**: Mark your most-used apps as favorites
5. **Start Working**: Your customized sidebar is immediately available across the platform

The Apps page puts you in complete control of your Swarms experience, ensuring you have the right tools at your fingertips for any task or workflow.

--------------------------------------------------

# File: swarms_platform/index.md

# Swarms Platform Documentation

Welcome to the Swarms Platform, a dynamic ecosystem where users can share, discover, and host agents and agent swarms. This documentation will guide you through the various features of the platform, providing you with the information you need to get started and make the most out of your experience.

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Account Management](#account-management)
4. [Usage Monitoring](#usage-monitoring)
5. [API Key Generation](#api-key-generation)
6. [Explorer](#explorer)
7. [Dashboard](#dashboard)
8. [Creating an Organization](#creating-an-organization)
9. [Additional Resources](#additional-resources)

## Introduction

The Swarms Platform is designed to facilitate the sharing, discovery, and hosting of intelligent agents and swarms of agents. Whether you are a developer looking to deploy your own agents, or an organization seeking to leverage collective intelligence, the Swarms Platform provides the tools and community support you need.

## Getting Started

To begin using the Swarms Platform, follow these steps:

1. **Create an Account**: Sign up on the platform to access its features.
2. **Explore the Dashboard**: Familiarize yourself with the user interface and available functionalities.
3. **Generate API Keys**: Securely interact with the platform's API.
4. **Create and Join Organizations**: Collaborate with others to deploy and manage agents and swarms.
5. **Share and Discover**: Use the Explorer to find and share agents and swarms.

## Account Management

### Account Page

Access and manage your account settings through the account page.

- **URL**: [Account Page](https://swarms.world/platform/account)

Here, you can update your profile information, manage security settings, and configure notifications.

## Usage Monitoring

### Check Your Usage

Monitor your usage statistics to keep track of your activities and resource consumption on the platform.

- **URL**: [Usage Monitoring](https://swarms.world/platform/usage)

This page provides detailed insights into your usage patterns, helping you optimize your resource allocation and stay within your limits.

## API Key Generation

### Generate Your API Keys

Generate API keys to securely interact with the Swarms Platform API.

- **URL**: [API Key Generation](https://swarms.world/platform/api-keys)

Follow the steps on this page to create, manage, and revoke API keys as needed. Ensure that your keys are kept secure and only share them with trusted applications.

## Explorer

### Explorer: Share, Discover, and Deploy

The Explorer is a central hub for sharing, discovering, and deploying prompts, agents, and swarms.

- **URL**: [Explorer](https://swarms.world/)

Use the Explorer to:

- **Share**: Upload and share your own prompts, agents, and swarms with the community.
- **Discover**: Browse and discover new and innovative agents and swarms created by others.
- **Deploy**: Quickly deploy agents and swarms for your own use or organizational needs.

## Dashboard

### Dashboard

The Dashboard is your control center for managing all aspects of your Swarms Platform experience.

- **URL**: [Dashboard](https://swarms.world/platform/dashboard)

From the Dashboard, you can:

- Monitor real-time metrics and analytics.
- Manage your agents and swarms.
- Access your account settings and usage information.
- Navigate to other sections of the platform.

## Creating an Organization

### Create an Organization

Collaborate with others by creating and joining organizations on the Swarms Platform.

- **URL**: [Create an Organization](https://swarms.world/platform/organization)

Creating an organization allows you to:

- Pool resources with team members.
- Manage shared agents and swarms.
- Set permissions and roles for organization members.

## Additional Resources

To further enhance your understanding and usage of the Swarms Platform, explore the following resources:

- **API Documentation**: Comprehensive documentation on the platform's API.
- **Community Forums**: Engage with other users, share insights, and get support.
- **Tutorials and Guides**: Step-by-step tutorials to help you get started with specific features and use cases.
- **Support**: Contact the support team for any issues or inquiries.

### Links

- [API Documentation](https://docs.swarms.world)
- [Community Forums](https://discord.gg/EamjgSaEQf)
- [Tutorials and Guides](https://docs.swarms.world))
- [Support](https://discord.gg/EamjgSaEQf)

## Conclusion

The Swarms Platform is a versatile and powerful ecosystem for managing intelligent agents and swarms. By following this documentation, you can effectively navigate the platform, leverage its features, and collaborate with others to create innovative solutions. Happy swarming!

--------------------------------------------------

# File: swarms_platform/monetize.md

# Swarms.World Monetization Guide

## Quick Overview

Swarms Marketplace has activated its payment infrastructure, enabling creators to monetize AI agents, prompts, and tools directly through the platform. Sellers receive payments minus a 5-15% platform fee, scaled based on subscription tiers. Revenue accrues in real-time to integrated crypto wallets, with optional fiat conversions.

---

## Eligibility Requirements

### Current Requirements for Paid Content

- **2+ published items** (Prompts, Agents, and Tools)

- **2 Items with 4+ star ratings** (you need community ratings)

- **Marketplace Agent Rating** An agent will automatically rate your prompt, agent, or tool.

**Bottom Line**: You must build reputation with free, high-quality content first.

---

## Step-by-Step Process

### Phase 1: Build Reputation (Required First)

#### 1. Improve Your Existing Content

- Add better descriptions and examples to your published items

- Use the Rating System: Evaluate and rate prompts, agents, and tools based on their effectiveness. Commenting System: Share feedback and insights with the Swarms community

- Ask users for honest reviews and ratings

#### 2. Create More Quality Content

Focus on these categories:

- **Agents**: Marketing, finance, or programming automation

- **Prompts**: Templates for specific business tasks  

- **Tools**: Utilities that solve real problems

Target: 3-5 additional items, all aiming for 4+ star ratings

#### 3. Get Community Ratings

- Share your content in relevant communities

- Engage with users who try your content

- Respond to feedback and improve based on comments

- Be patient - ratings take time to accumulate

### Phase 2: Start Monetizing

#### 4. Choose Your Pricing Model

Three primary monetization avenues exist: AI agents (autonomous task-execution models), prompts (pre-optimized input templates), and tools (development utilities like data preprocessors)

**Pricing Options:**

- **One-time**: $0.01 - $999,999 USD

- **Subscription**: Monthly/annual recurring fees  (Coming Soon)

- **Usage-based**: Pay per API call or computation (Coming Soon)


#### 6. Optimize & Scale

- Monitor your revenue and user feedback

- Developers can bundle assets—such as pairing prompt libraries with compatible agents—creating value-added 
packages

- Create bundles of related content for higher value

- Adjust pricing based on demand

---

## Revenue Models

### What Sells Best

1. **Business Automation Agents** - Marketing, sales, finance

2. **Industry-Specific Prompts** - Legal, medical, technical writing

3. **Integration Tools** - APIs, data processors, connectors

### Pricing Examples

- Simple prompts: $1-50

- Complex agents: $20-500+

- Enterprise tools: $100-1000+

---

## Quick Tips for Success

1. **Quality over quantity** - Better to have 3 excellent items than 10 mediocre ones
2. **Solve real problems** - Focus on actual business needs
3. **Document everything** - Clear instructions increase ratings
4. **Engage actively** - Respond to all user feedback
5. **Be patient** - Building reputation takes time but pays off

---

## Common Mistakes to Avoid

- Publishing low-quality content to meet quantity requirements

- Not responding to user feedback

- Setting prices too high before building reputation

- Copying existing solutions without adding value

- Ignoring community guidelines



--------------------------------------------------

# File: swarms_platform/playground_page.md

# Swarms API Playground Documentation

## Overview

The Swarms Playground (`https://swarms.world/platform/playground`) is an interactive testing environment that allows you to experiment with the Swarms API in real-time. This powerful tool enables you to configure AI agents, test different parameters, and generate code examples in multiple programming languages without writing any code manually.

## Key Features

- **Real-time API Testing**: Execute Swarms API calls directly in the browser

- **Multi-language Code Generation**: Generate code examples in Python, Rust, Go, and TypeScript

- **Interactive Configuration**: Visual interface for setting up agent parameters

- **Live Output**: See API responses immediately in the output terminal

- **Code Export**: Copy generated code for use in your applications


## Interface Overview

### Language Selection

The playground supports code generation in four programming languages:

- **Python**: Default language with `requests` library implementation

- **Rust**: Native Rust HTTP client implementation

- **Go**: Standard Go HTTP package implementation  

- **TypeScript**: Node.js/browser-compatible implementation


Switch between languages using the dropdown menu in the top-right corner to see language-specific code examples.

### Agent Modes

The playground offers two distinct modes for testing different types of AI implementations:

#### Single Agent Mode
Test individual AI agents with specific configurations and tasks. Ideal for:
- Prototype testing

- Parameter optimization

- Simple task automation

- API familiarization


#### Multi-Agent Mode  
Experiment with coordinated AI agent systems. Perfect for:
- Complex workflow automation

- Collaborative AI systems

- Distributed task processing

- Advanced orchestration scenarios


## Configuration Parameters

### Basic Agent Settings

#### Agent Name
**Purpose**: Unique identifier for your agent
**Usage**: Helps distinguish between different agent configurations
**Example**: `"customer_service_bot"`, `"data_analyst"`, `"content_writer"`

#### Model Name
**Purpose**: Specifies which AI model to use for the agent
**Default**: `gpt-4o-mini`
**Options**: Various OpenAI and other supported models
**Impact**: Affects response quality, speed, and cost

#### Description
**Purpose**: Human-readable description of the agent's purpose
**Usage**: Documentation and identification
**Best Practice**: Be specific about the agent's intended function

#### System Prompt
**Purpose**: Core instructions that define the agent's behavior and personality
**Impact**: Critical for agent performance and response style
**Tips**: 
- Be clear and specific

- Include role definition

- Specify output format if needed

- Add relevant constraints


### Advanced Parameters

#### Temperature
**Range**: 0.0 - 2.0

**Default**: 0.5
**Purpose**: Controls randomness in responses
- **Low (0.0-0.3)**: More deterministic, consistent responses

- **Medium (0.4-0.7)**: Balanced creativity and consistency  

- **High (0.8-2.0)**: More creative and varied responses


#### Max Tokens
**Default**: 8192
**Purpose**: Maximum length of the agent's response
**Considerations**:
- Higher values allow longer responses

- Impacts API costs

- Model-dependent limits apply


#### Role
**Default**: `worker`
**Purpose**: Defines the agent's role in multi-agent scenarios
**Common Roles**: `worker`, `manager`, `coordinator`, `specialist`

#### Max Loops
**Default**: 1
**Purpose**: Number of iterations the agent can perform
**Usage**:
- `1`: Single response

- `>1`: Allows iterative problem solving


#### MCP URL (Optional)
**Purpose**: Model Context Protocol URL for external integrations
**Usage**: Connect to external services or data sources
**Format**: Valid URL pointing to MCP-compatible service

### Task Definition

#### Task
**Purpose**: Specific instruction or query for the agent to process
**Best Practices**:
- Be specific and clear

- Include all necessary context

- Specify desired output format

- Provide examples when helpful


## Using the Playground

### Step-by-Step Guide

1. **Select Mode**: Choose between Single Agent or Multi-Agent
2. **Choose Language**: Select your preferred programming language
3. **Configure Agent**: Fill in the required parameters
4. **Define Task**: Enter your specific task or query
5. **Run Agent**: Click the "Run Agent" button
6. **Review Output**: Check the Output Terminal for results
7. **Copy Code**: Use the generated code in your applications

### Testing Strategies

#### Parameter Experimentation

- **Temperature Testing**: Try different temperature values to find optimal creativity levels

- **Prompt Engineering**: Iterate on system prompts to improve responses

- **Token Optimization**: Adjust max_tokens based on expected response length


#### Workflow Development

- **Start Simple**: Begin with basic tasks and gradually increase complexity

- **Iterative Refinement**: Use playground results to refine your approach

- **Documentation**: Keep notes on successful configurations


## Output Interpretation

### Output Terminal

The Output Terminal displays:

- **Agent Responses**: Direct output from the AI agent

- **Error Messages**: API errors or configuration issues

- **Execution Status**: Success/failure indicators

- **Response Metadata**: Token usage, timing information


### Code Preview

The Code Preview section shows:

- **Complete Implementation**: Ready-to-use code in your selected language

- **API Configuration**: Proper headers and authentication setup

- **Request Structure**: Correctly formatted payload

- **Response Handling**: Basic error handling and output processing


## Code Examples by Language

### Python Implementation
```python
import requests

url = "https://swarms-api-285321057562.us-east1.run.app/v1/agent/completions"
headers = {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key-here"
}

payload = {
    "agent_config": {
        "agent_name": "example_agent",
        "description": "Example agent for demonstration",
        "system_prompt": "You are a helpful assistant.",
        "model_name": "gpt-4o-mini",
        "auto_generate_prompt": false,
        "max_tokens": 8192,
        "temperature": 0.5,
        "role": "worker",
        "max_loops": 1,
        "tools_list_dictionary": null,
        "mcp_url": null
    },
    "task": "Explain quantum computing in simple terms"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Key Code Components

#### API Endpoint

- **URL**: `https://swarms-api-285321057562.us-east1.run.app/v1/agent/completions`

- **Method**: POST

- **Authentication**: API key in `x-api-key` header


#### Request Structure

- **Headers**: Content-Type and API key

- **Payload**: Agent configuration and task

- **Response**: JSON with agent output and metadata


## Best Practices

### Security

- **API Key Management**: Never expose API keys in client-side code

- **Environment Variables**: Store sensitive credentials securely

- **Rate Limiting**: Respect API rate limits in production


### Performance Optimization

- **Parameter Tuning**: Optimize temperature and max_tokens for your use case

- **Prompt Engineering**: Craft efficient system prompts

- **Caching**: Implement response caching for repeated queries


### Development Workflow

- **Prototype in Playground**: Test configurations before implementation

- **Document Successful Configs**: Save working parameter combinations

- **Iterate and Improve**: Use playground for continuous optimization


## Troubleshooting

### Common Issues

#### No Output in Terminal

- **Check API Key**: Ensure valid API key is configured

- **Verify Parameters**: All required fields must be filled

- **Network Issues**: Check internet connection


#### Unexpected Responses

- **Review System Prompt**: Ensure clear instructions

- **Adjust Temperature**: Try different creativity levels

- **Check Task Definition**: Verify task clarity and specificity


#### Code Generation Issues

- **Language Selection**: Ensure correct language is selected

- **Copy Functionality**: Use the "Copy Code" button for accurate copying

- **Syntax Validation**: Test generated code in your development environment


## Integration Guide

### From Playground to Production

1. **Copy Generated Code**: Use the Code Preview section
2. **Add Error Handling**: Implement robust error handling
3. **Configure Environment**: Set up proper API key management
4. **Test Thoroughly**: Validate in your target environment
5. **Monitor Performance**: Track API usage and response quality

The Swarms Playground is your gateway to understanding and implementing the Swarms API effectively. Use it to experiment, learn, and build confidence before deploying AI agents in production environments.

--------------------------------------------------

# File: swarms_platform/prompts/add_prompt.md

# Prompts API Documentation

The `https://swarms.world/api/add-prompt` endpoint allows users to add a new prompt to the Swarms platform. This API accepts a POST request with a JSON body containing details of the prompt, such as its name, description, use cases, and tags. The request must be authenticated using an API key.

## Endpoint: Add Prompt

- **URL:** `https://swarms.world/api/add-prompt`
- **Method:** POST
- **Content-Type:** `application/json`
- **Authorization:** Bearer token required in the header

## Request Parameters

The request body should be a JSON object with the following attributes:

| Attribute     | Type     | Description                                                     | Required |
| ------------- | -------- | --------------------------------------------------------------- | -------- |
| `name`        | `string` | The name of the prompt.                                         | Yes      |
| `prompt`      | `string` | The prompt text.                                                | Yes      |
| `description` | `string` | A brief description of the prompt.                              | Yes      |
| `useCases`    | `array`  | An array of use cases, each containing a title and description. | Yes      |
| `tags`        | `string` | Comma-separated tags for the prompt.                            | No       |

### `useCases` Structure

Each use case in the `useCases` array should be an object with the following attributes:

| Attribute     | Type     | Description                          | Required |
| ------------- | -------- | ------------------------------------ | -------- |
| `title`       | `string` | The title of the use case.           | Yes      |
| `description` | `string` | A brief description of the use case. | Yes      |

## Example Usage

### Python

```python
import requests
import json

url = "https://swarms.world/api/add-prompt"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {apiKey}"
}
data = {
    "name": "Example Prompt",
    "prompt": "This is an example prompt from an API route.",
    "description": "Description of the prompt.",
    "useCases": [
        {"title": "Use case 1", "description": "Description of use case 1"},
        {"title": "Use case 2", "description": "Description of use case 2"}
    ],
    "tags": "example, prompt"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

### Node.js

```javascript
const fetch = require("node-fetch");

async function addPromptsHandler() {
  try {
    const response = await fetch("https://swarms.world/api/add-prompt", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer {apiKey}",
      },
      body: JSON.stringify({
        name: "Example Prompt",
        prompt: "This is an example prompt from an API route.",
        description: "Description of the prompt.",
        useCases: [
          { title: "Use case 1", description: "Description of use case 1" },
          { title: "Use case 2", description: "Description of use case 2" },
        ],
        tags: "example, prompt",
      }),
    });

    const result = await response.json();
    console.log(result);
  } catch (error) {
    console.error("An error has occurred", error);
  }
}

addPromptsHandler();
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://swarms.world/api/add-prompt"
    payload := map[string]interface{}{
        "name":        "Example Prompt",
        "prompt":      "This is an example prompt from an API route.",
        "description": "Description of the prompt.",
        "useCases": []map[string]string{
            {"title": "Use case 1", "description": "Description of use case 1"},
            {"title": "Use case 2", "description": "Description of use case 2"},
        },
        "tags": "example, prompt",
    }
    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer {apiKey}")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("An error has occurred", err)
        return
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
```

### cURL

```bash
curl -X POST https://swarms.world/api/add-prompt \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {apiKey}" \
-d '{
  "name": "Example Prompt",
  "prompt": "This is an example prompt from an API route.",
  "description": "Description of the prompt.",
  "useCases": [
    { "title": "Use case 1", "description": "Description of use case 1" },
    { "title": "Use case 2", "description": "Description of use case 2" }
  ],
  "tags": "example, prompt"
}'
```

## Response

The response will be a JSON object containing the result of the operation. Example response:

```json
{
  "success": true,
  "message": "Prompt added successfully",
  "data": {
    "id": "prompt_id",
    "name": "Example Prompt",
    "prompt": "This is an example prompt from an API route.",
    "description": "Description of the prompt.",
    "useCases": [
      { "title": "Use case 1", "description": "Description of use case 1" },
      { "title": "Use case 2", "description": "Description of use case 2" }
    ],
    "tags": "example, prompt"
  }
}
```

--------------------------------------------------

# File: swarms_platform/prompts/edit_prompt.md

# Endpoint: Edit Prompt

The `https://swarms.world/api/edit-prompt` endpoint allows users to edit an existing prompt on the Swarms platform. This API accepts a POST request with a JSON body containing the prompt details to be updated, such as its name, description, use cases, and tags. The request must be authenticated using an API key.

## Endpoint

- **URL:** `https://swarms.world/api/edit-prompt`
- **Method:** POST
- **Content-Type:** `application/json`
- **Authorization:** Bearer token required in the header

## Request Parameters

The request body should be a JSON object with the following attributes:

| Attribute     | Type     | Description                                                     | Required |
| ------------- | -------- | --------------------------------------------------------------- | -------- |
| `id`          | `string` | The ID of the prompt to be edited.                              | Yes      |
| `name`        | `string` | The name of the prompt.                                         | Yes      |
| `prompt`      | `string` | The prompt text.                                                | Yes      |
| `description` | `string` | A brief description of the prompt.                              | No       |
| `useCases`    | `array`  | An array of use cases, each containing a title and description. | Yes      |
| `tags`        | `string` | Comma-separated tags for the prompt.                            | No       |

### `useCases` Structure

Each use case in the `useCases` array should be an object with the following attributes:

| Attribute     | Type     | Description                          | Required |
| ------------- | -------- | ------------------------------------ | -------- |
| `title`       | `string` | The title of the use case.           | Yes      |
| `description` | `string` | A brief description of the use case. | Yes      |

## Example Usage

### Python

```python
import requests
import json

url = "https://swarms.world/api/edit-prompt"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {apiKey}"
}
data = {
    "id": "prompt_id",
    "name": "Updated Prompt",
    "prompt": "This is an updated prompt from an API route.",
    "description": "Updated description of the prompt.",
    "useCases": [
        {"title": "Updated use case 1", "description": "Updated description of use case 1"},
        {"title": "Updated use case 2", "description": "Updated description of use case 2"}
    ],
    "tags": "updated, prompt"
}

response = requests.post(url, headers=headers, data=json.dumps(data))
print(response.json())
```

### Node.js

```javascript
const fetch = require("node-fetch");

async function editPromptsHandler() {
  try {
    const response = await fetch("https://swarms.world/api/edit-prompt", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: "Bearer {apiKey}",
      },
      body: JSON.stringify({
        id: "prompt_id",
        name: "Updated Prompt",
        prompt: "This is an updated prompt from an API route.",
        description: "Updated description of the prompt.",
        useCases: [
          {
            title: "Updated use case 1",
            description: "Updated description of use case 1",
          },
          {
            title: "Updated use case 2",
            description: "Updated description of use case 2",
          },
        ],
        tags: "updated, prompt",
      }),
    });

    const result = await response.json();
    console.log(result);
  } catch (error) {
    console.error("An error has occurred", error);
  }
}

editPromptsHandler();
```

### Go

```go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://swarms.world/api/edit-prompt"
    payload := map[string]interface{}{
        "id":          "prompt_id",
        "name":        "Updated Prompt",
        "prompt":      "This is an updated prompt from an API route.",
        "description": "Updated description of the prompt.",
        "useCases": []map[string]string{
            {"title": "Updated use case 1", "description": "Updated description of use case 1"},
            {"title": "Updated use case 2", "description": "Updated description of use case 2"},
        },
        "tags": "updated, prompt",
    }
    jsonPayload, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonPayload))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer {apiKey}")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("An error has occurred", err)
        return
    }
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
```

### cURL

```bash
curl -X POST https://swarms.world/api/edit-prompt \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {apiKey}" \
-d '{
  "id": "prompt_id",
  "name": "Updated Prompt",
  "prompt": "This is an updated prompt from an API route.",
  "description": "Updated description of the prompt.",
  "useCases": [
    { "title": "Updated use case 1", "description": "Updated description of use case 1" },
    { "title": "Updated use case 2", "description": "Updated description of use case 2" }
  ],
  "tags": "updated, prompt"
}'
```

## Response

The response will be a JSON object containing the result of the operation. Example response:

```json
{
  "success": true,
  "message": "Prompt updated successfully",
  "data": {
    "id": "prompt_id",
    "name": "Updated Prompt",
    "prompt": "This is an updated prompt from an API route.",
    "description": "Updated description of the prompt.",
    "useCases": [
      {
        "title": "Updated use case 1",
        "description": "Updated description of use case 1"
      },
      {
        "title": "Updated use case 2",
        "description": "Updated description of use case 2"
      }
    ],
    "tags": "updated, prompt"
  }
}
```

In case of an error, the response will contain an error message detailing the issue.

## Common Issues and Tips

- **Authentication Error:** Ensure that the `Authorization` header is correctly set with a valid API key.
- **Invalid JSON:** Make sure the request body is a valid JSON object.
- **Missing Required Fields:** Ensure that all required fields (`name`, `prompt`, `description`, `useCases`) are included in the request body.
- **Network Issues:** Verify network connectivity and endpoint URL.

## References and Resources

- [API Authentication Guide](https://swarms.world/docs/authentication)
- [JSON Structure Standards](https://json.org/)
- [Fetch API Documentation (Node.js)](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
- [Requests Library (Python)](https://requests.readthedocs.io/)
- [Net/HTTP Package (Go)](https://pkg.go.dev/net/http)

This comprehensive documentation provides all the necessary information to effectively use the `https://swarms.world/api/add-prompt` and `https://swarms.world/api/edit-prompt` endpoints, including details on request parameters, example code snippets in multiple programming languages, and troubleshooting tips.


--------------------------------------------------

# File: swarms_platform/prompts/fetch_prompts.md

# Documentation for `getAllPrompts` API Endpoint

The `getAllPrompts` API endpoint is a part of the `swarms.world` application, designed to fetch all prompt records from the database. This endpoint is crucial for retrieving various prompts stored in the `swarms_cloud_prompts` table, including their metadata such as name, description, use cases, and tags.

## Purpose

The primary purpose of this API endpoint is to provide a method for clients to fetch a list of prompts stored in the `swarms_cloud_prompts` table, with the ability to filter by name, tags, and use cases.

## API Endpoint Definition

### Fetch All Prompts

#### Endpoint URL

```
https://swarms.world/get-prompts
```

#### HTTP Method

```
GET
```

### Query Parameters

- **name** (optional): A substring to match against the prompt name. The query is case-insensitive.
- **tag** (optional): A comma-separated list of tags to filter prompts by. The query matches any of the provided tags, and is case-insensitive.
- **use_case** (optional): A substring to match against the use case titles within the `use_cases` array. The query is case-insensitive.
- **use_case_description** (optional): A substring to match against the use case descriptions within the `use_cases` array. The query is case-insensitive.

#### Response

##### Success Response (200)

Returns an array of prompts.

```json
[
  {
    "id": "string",
    "name": "string",
    "description": "string",
    "prompt": "string",
    "use_cases": [
      {
        "title": "string",
        "description": "string"
      }
    ],
    "tags": "string"
  },
  ...
]
```

##### Error Responses

- **405 Method Not Allowed**

  ```json
  {
    "error": "Method <method> Not Allowed"
  }
  ```

- **500 Internal Server Error**

  ```json
  {
    "error": "Could not fetch prompts"
  }
  ```

### Fetch Prompt by ID

#### Endpoint URL

```
https://swarms.world/get-prompts/[id]
```

#### HTTP Method

```
GET
```

#### Response

##### Success Response (200)

Returns a single prompt by ID.

```json
{
  "id": "string",
  "name": "string",
  "description": "string",
  "prompt": "string",
  "use_cases": [
    {
      "title": "string",
      "description": "string"
    }
  ],
  "tags": "string"
}
```

##### Error Responses

- **404 Not Found**

  ```json
  {
    "error": "Prompt not found"
  }
  ```

- **500 Internal Server Error**

  ```json
  {
    "error": "Could not fetch prompt"
  }
  ```

### Request Handling

1. **Method Validation**: The endpoint only supports the `GET` method. If a different HTTP method is used, it responds with a `405 Method Not Allowed` status.

2. **Database Query**:

   - **Fetching All Prompts**: The endpoint uses the `supabaseAdmin` client to query the `swarms_cloud_prompts` table. Filters are applied based on the query parameters (`name`, `tag`, and `use_cases`).
   - **Fetching a Prompt by ID**: The endpoint retrieves a single prompt from the `swarms_cloud_prompts` table by its unique ID.

3. **Response**: On success, it returns the prompt data in JSON format. In case of an error during the database query, a `500 Internal Server Error` status is returned. For fetching by ID, if the prompt is not found, it returns a `404 Not Found` status.

### Code Example

#### JavaScript (Node.js)

```javascript
import fetch from "node-fetch";

// Fetch all prompts with optional filters
const getPrompts = async (filters) => {
  const queryString = new URLSearchParams(filters).toString();
  const response = await fetch(
    `https://swarms.world/get-prompts?${queryString}`,
    {
      method: "GET",
    }
  );

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
};

// Fetch prompt by ID
const getPromptById = async (id) => {
  const response = await fetch(`https://swarms.world/get-prompts/${id}`, {
    method: "GET",
  });

  if (!response.ok) {
    throw new Error(`Error: ${response.statusText}`);
  }

  const data = await response.json();
  console.log(data);
};

// Example usage
getPrompts({
  name: "example",
  tag: "tag1,tag2",
  use_case: "example",
  use_case_description: "description",
}).catch(console.error);
getPromptById("123").catch(console.error);
```

#### Python

```python
import requests

# Fetch all prompts with optional filters
def get_prompts(filters):
    response = requests.get('https://swarms.world/get-prompts', params=filters)

    if response.status_code != 200:
        raise Exception(f'Error: {response.status_code}, {response.text}')

    data = response.json()
    print(data)

# Fetch prompt by ID
def get_prompt_by_id(id):
    response = requests.get(f'https://swarms.world/get-prompts/{id}')

    if response.status_code != 200:
        raise Exception(f'Error: {response.status_code}, {response.text}')

    data = response.json()
    print(data)

# Example usage
get_prompts({'name': 'example', 'tag': 'tag1,tag2', 'use_case': 'example', 'use_case_description': 'description'})
get_prompt_by_id('123')
```

#### cURL

```sh
# Fetch all prompts with optional filters
curl -X GET "https://swarms.world/get-prompts?name=example&tag=tag1,tag2&use_case=example&use_case_description=description"

# Fetch prompt by ID
curl -X GET https://swarms.world/get-prompts/123
```

#### Go

```go
package main

import (
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

func getPrompts(filters map[string]string) {
    baseURL := "https://swarms.world/get-prompts"
    query := url.Values{}
    for key, value := range filters {
        query.Set(key, value)
    }
    fullURL := fmt.Sprintf("%s?%s", baseURL, query.Encode())

    resp, err := http.Get(fullURL)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        body, _ := ioutil.ReadAll(resp.Body)
        panic(fmt.Sprintf("Error: %d, %s", resp.StatusCode, string(body)))
    }

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

func getPromptById(id string) {
    url := fmt.Sprintf("https://swarms.world/get-prompts/%s", id)
    resp, err := http.Get(url)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        body, _ := ioutil.ReadAll(resp.Body)
        panic(fmt.Sprintf("Error: %d, %s", resp.StatusCode, string(body)))
    }

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        panic(err)
    }

    fmt.Println(string(body))
}

func main() {
    filters := map[string]string{
        "name":                  "example",
        "tag":                   "tag1,tag2",
        "use_case":        "example",
        "use_case_description":  "description",
    }
    getPrompts(filters)
    getPromptById("123")
}
```

#### Attributes Table

| Attribute   | Type   | Description                      |
| ----------- | ------ | -------------------------------- |
| id          | String | Unique identifier for the prompt |
| name        | String | Name of the prompt               |
| description | String | Description of the prompt        |
| prompt      | String | The actual prompt text           |
| use_cases   | Array  | Use cases for the prompt         |
| tags        | String | Tags associated with the prompt  |

## Additional Information and Tips

- Handle different error statuses appropriately to provide clear feedback to users.
- Consider implementing rate limiting and logging for better security and monitoring.

## References and Resources

- [Next.js API Routes](https://nextjs.org/docs/api-routes/introduction)
- [Supabase Documentation](https://supabase.com/docs)
- [Node Fetch](https://www.npmjs.com/package/node-fetch)
- [Requests Library (Python)](https://docs.python-requests.org/en/latest/)
- [Go net/http Package](https://pkg.go.dev/net/http)

This documentation provides a comprehensive guide to the `getAllPrompts` API endpoint, including usage examples in multiple programming languages and detailed attribute descriptions.


--------------------------------------------------

# File: swarms_platform/share_and_discover.md

# Swarms Marketplace Documentation

The Swarms Marketplace (`https://swarms.world`) is a vibrant community hub where developers, researchers, and agent enthusiasts share and discover cutting-edge agent tools, agents, and prompts. This collaborative platform empowers you to leverage the collective intelligence of the Swarms community while contributing your own innovations.

## What You Can Discover

### 🤖 Agents

Ready-to-use agent agents for specific tasks and industries:

- **Specialized Agents**: From healthcare diagnostics to financial analysis

- **Multi-Agent Systems**: Collaborative agent swarms for complex workflows

- **Industry Solutions**: Pre-built agents for healthcare, finance, education, and more

- **Custom Implementations**: Unique agent architectures and approaches


### 💡 Prompts

System prompts and instructions that define agent behavior:

- **Role-Specific Prompts**: Behavioral psychologist, documentation specialist, financial advisor

- **System Templates**: Production-grade prompts for various use cases

- **Collaborative Frameworks**: Multi-agent coordination prompts

- **Task-Specific Instructions**: Optimized prompts for specific workflows


### 🛠️ Tools

APIs, integrations, and utilities that extend agent capabilities:

- **API Integrations**: Connect to external services and data sources

- **Data Fetchers**: Tools for retrieving information from various platforms

- **Workflow Utilities**: Helper functions and automation tools

- **Communication Tools**: Integrations with messaging platforms and services


## Browsing and Discovery

### Category-Based Navigation

**Industry Categories:**

- **Healthcare**: Medical diagnosis, patient care, research tools

- **Education**: Learning assistants, curriculum development, assessment tools

- **Finance**: Trading bots, market analysis, financial planning

- **Research**: Academic paper fetchers, data analysis, literature review

- **Public Safety**: Risk assessment, emergency response, safety monitoring

- **Marketing**: Content creation, campagentgn optimization, audience analysis

- **Sales**: Lead generation, customer engagement, sales automation

- **Customer Support**: Chatbots, issue resolution, knowledge management


### Trending Section

Discover the most popular and highly-rated content in the community:

- **Top-Rated Items**: Content with 5-star ratings from users

- **Community Favorites**: Most shared and downloaded items

- **Recent Additions**: Latest contributions to the marketplace

- **Featured Content**: Curated selections highlighting exceptional work


### Search and Filtering

- **Keyword Search**: Find specific tools, agents, or prompts by name or description

- **Category Filters**: Browse within specific industry verticals

- **Rating Filters**: Filter by community ratings and reviews

- **Tag-Based Discovery**: Explore content by relevant tags and keywords


## Contributing to the Marketplace

### Why Share Your Work?

**🌟 Community Impact**

- Help fellow developers solve similar challenges

- Contribute to the collective advancement of agent technology

- Build your reputation in the agent community


**📈 Professional Growth**

- Showcase your expertise and innovative solutions

- Receive feedback and suggestions from the community

- Network with like-minded professionals and researchers


**🔄 Knowledge Exchange**

- Learn from others who use and modify your contributions

- Discover new approaches and improvements to your work

- Foster collaborative innovation and problem-solving


**🏆 Recognition**

- Get credited for your contributions with author attribution

- Build a portfolio of public agent implementations

- Gagentn visibility in the growing Swarms ecosystem


## How to Submit Content

### Adding a Prompt

Prompts are the foundation of agent behavior - share your carefully crafted instructions with the community.


**Step-by-Step Process:**

1. **Click "Add Prompt"** from the marketplace interface
2. **Fill Required Fields:**

   - **Name**: Descriptive title that clearly indicates the prompt's purpose

   - **Description**: Detagentled explanation of what the prompt does and when to use it

   - **Prompt**: The complete system prompt or instruction text

3. **Enhance Your Submission:**
   - **Add Image**: Upload a visual representation (up to 60MB)

   - **Select Categories**: Choose relevant industry categories

   - **Add Tags**: Include searchable keywords and descriptors

4. **Submit**: Review and submit your prompt to the community

**Best Practices for Prompts:**

- **Be Specific**: Clearly define the agent's role and expected behavior

- **Include Context**: Provide background information and use case scenarios

- **Test Thoroughly**: Ensure your prompt produces consistent, high-quality results

- **Document Parameters**: Explagentn any variables or customization options


### Submitting an Agent

Agents are complete agent implementations - share your working solutions with the community.


**Step-by-Step Process:**

1. **Click "Add Agent"** from the marketplace interface
2. **Complete Required Information:**
   - **Name**: Clear, descriptive agent name

   - **Description**: Comprehensive explanation of functionality and use cases

   - **Agent Code**: Complete, working implementation

   - **Language**: Select the programming language (Python, etc.)

3. **Optimize Discoverability:**
   - **Categories**: Choose appropriate industry verticals

   - **Image**: Add a representative image or diagram

   - **Tags**: Include relevant keywords for searchability

4. **Submit**: Finalize and share your agent with the community

**Agent Submission Guidelines:**

- **Complete Implementation**: Provide fully functional, tested code

- **Clear Documentation**: Include usage instructions and configuration detagentls

- **Error Handling**: Implement robust error handling and validation

- **Dependencies**: List all required libraries and dependencies

- **Examples**: Provide usage examples and expected outputs


### Adding Tools

Tools extend the capabilities of the Swarms ecosystem - share your integrations and utilities.


**What Makes a Great Tool:**

- **Solves Real Problems**: Addresses common pagentn points or workflow gaps

- **Easy Integration**: Simple to implement and configure

- **Well Documented**: Clear instructions and examples

- **Reliable Performance**: Tested and optimized for production use


## Content Quality Guidelines

### Writing Effective Descriptions

**For All Submissions:**

- **Start with Purpose**: Lead with what your contribution does

- **Explagentn Benefits**: Highlight the value and use cases

- **Include Technical Detagentls**: Mention key features and capabilities

- **Provide Context**: Explagentn when and why to use your contribution


**Example Description Structure:**

```
[Brief summary of what it does]

Key Features:
- [Feature 1 with benefit]

- [Feature 2 with benefit]

- [Feature 3 with benefit]


Use Cases:
- [Scenario 1]

- [Scenario 2]

- [Scenario 3]


Technical Detagentls:
- [Implementation notes]

- [Requirements or dependencies]

- [Configuration options]

```

### Choosing Categories and Tags

**Categories:**

- Select all relevant industry verticals

- Consider cross-industry applications

- Choose the primary category first


**Tags:**

- Include technical keywords (API names, frameworks, models)

- Add functional descriptors (automation, analysis, generation)

- Include use case keywords (customer service, data processing, content creation)

- Use common terminology that others would search for


### Visual Assets

**Image Guidelines:**

- **File Size**: Maximum 60MB supported

- **Recommended Types**: Screenshots, diagrams, logos, workflow illustrations

- **Quality**: High-resolution images that clearly represent your contribution

- **Content**: Visual representations of functionality, architecture, or results


## Community Engagement

### Rating and Reviews

**As a User:**

- Rate content honestly based on quality and usefulness

- Leave constructive feedback to help creators improve

- Share your experiences and modifications


**As a Creator:**

- Respond to feedback and questions

- Update your submissions based on community input

- Engage with users who implement your solutions


### Building Your Reputation

**Consistency**: Regularly contribute high-quality content
**Responsiveness**: Engage with community feedback and questions
**Innovation**: Share unique approaches and creative solutions
**Collaboration**: Build upon and improve existing community contributions


### What Makes Content Successful

**Clear Value Proposition**: Immediately obvious benefits and use cases
**Production Ready**: Fully functional, tested implementations
**Good Documentation**: Clear instructions and examples
**Active Magentntenance**: Regular updates and community engagement
**Unique Approach**: Novel solutions or creative implementations

## Getting Started

### For New Contributors

1. **Explore First**: Browse existing content to understand community standards
2. **Start Small**: Begin with a simple but useful contribution
3. **Focus on Quality**: Prioritize completeness and documentation over quantity
4. **Engage**: Participate in discussions and provide feedback to others

### For Experienced Developers

1. **Share Expertise**: Contribute advanced implementations and frameworks
2. **Mentor Others**: Provide feedback and suggestions to new contributors
3. **Lead Innovation**: Introduce cutting-edge approaches and techniques
4. **Build Ecosystems**: Create complementary tools and integrations

## Best Practices Summary

### Before Submitting

- ✅ Test your contribution thoroughly

- ✅ Write clear, comprehensive documentation

- ✅ Choose appropriate categories and tags

- ✅ Create or find a representative image

- ✅ Review similar existing content


### After Submitting

- ✅ Monitor for community feedback

- ✅ Respond to questions and comments

- ✅ Update based on user suggestions

- ✅ Share your contribution on social platforms

- ✅ Continue improving and iterating


## Join the Community

The Swarms Marketplace thrives on community participation. Whether you're sharing a simple prompt or a complex multi-agent system, your contribution makes the entire ecosystem stronger. Start exploring, contributing, and collaborating today!

**Ready to contribute?** Visit `https://swarms.world` and click "Add Prompt," "Add Agent," or "Add Tool" to share your innovation with the world.

Together, we're building the future of agent collaboration, one contribution at a time.

--------------------------------------------------

# File: swarms_rs/agents.md

# swarms-rs

!!! note "Modern AI Agent Framework"
    swarms-rs is a powerful Rust framework for building autonomous AI agents powered by LLMs, equipped with robust tools and memory capabilities. Designed for various applications from trading analysis to healthcare diagnostics.

## Getting Started

### Installation

```bash
cargo add swarms-rs
```

!!! tip "Compatible with Rust 1.70+"
    This library requires Rust 1.70 or later. Make sure your Rust toolchain is up to date.

### Required Environment Variables

```bash
# Required API keys
OPENAI_API_KEY="your_openai_api_key_here"
DEEPSEEK_API_KEY="your_deepseek_api_key_here"
```

### Quick Start

Here's a simple example to get you started with swarms-rs:

```rust
use std::env;
use anyhow::Result;
use swarms_rs::{llm::provider::openai::OpenAI, structs::agent::Agent};

#[tokio::main]
async fn main() -> Result<()> {
    // Load environment variables from .env file
    dotenv::dotenv().ok();
    
    // Initialize tracing for better debugging
    tracing_subscriber::registry()
        .with(tracing_subscriber::EnvFilter::from_default_env())
        .with(
            tracing_subscriber::fmt::layer()
                .with_line_number(true)
                .with_file(true),
        )
        .init();

    // Set up your LLM client
    let api_key = env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY must be set");
    let client = OpenAI::new(api_key).set_model("gpt-4-turbo");
    
    // Create a basic agent
    let agent = client
        .agent_builder()
        .system_prompt("You are a helpful assistant.")
        .agent_name("BasicAgent")
        .user_name("User")
        .build();
    
    // Run the agent with a user query
    let response = agent
        .run("Tell me about Rust programming.".to_owned())
        .await?;
    
    println!("{}", response);
    Ok(())
}
```

## Core Concepts

### Agents

Agents in swarms-rs are autonomous entities that can:

- Perform complex reasoning based on LLM capabilities
- Use tools to interact with external systems
- Maintain persistent memory
- Execute multi-step plans

## Agent Configuration

### Core Parameters

| Parameter | Description | Default | Required |
|-----------|-------------|---------|----------|
| `system_prompt` | Initial instructions/role for the agent | - | Yes |
| `agent_name` | Name identifier for the agent | - | Yes |
| `user_name` | Name for the user interacting with agent | - | Yes |
| `max_loops` | Maximum number of reasoning loops | 1 | No |
| `retry_attempts` | Number of retry attempts on failure | 1 | No |
| `enable_autosave` | Enable state persistence | false | No |
| `save_state_dir` | Directory for saving agent state | None | No |

### Advanced Configuration

You can enhance your agent's capabilities with:

- **Planning**: Enable structured planning for complex tasks
- **Memory**: Persistent storage for agent state
- **Tools**: External capabilities through MCP protocol

!!! warning "Resource Usage"
    Setting high values for `max_loops` can increase API usage and costs. Start with lower values and adjust as needed.

## Examples

### Specialized Agent for Cryptocurrency Analysis

```rust
use std::env;
use anyhow::Result;
use swarms_rs::{llm::provider::openai::OpenAI, structs::agent::Agent};

#[tokio::main]
async fn main() -> Result<()> {
    dotenv::dotenv().ok();
    tracing_subscriber::registry()
        .with(tracing_subscriber::EnvFilter::from_default_env())
        .with(
            tracing_subscriber::fmt::layer()
                .with_line_number(true)
                .with_file(true),
        )
        .init();

    let api_key = env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY must be set");
    let client = OpenAI::new(api_key).set_model("gpt-4-turbo");
    
    let agent = client
        .agent_builder()
        .system_prompt(
            "You are a sophisticated cryptocurrency analysis assistant specialized in:
            1. Technical analysis of crypto markets
            2. Fundamental analysis of blockchain projects
            3. Market sentiment analysis
            4. Risk assessment
            5. Trading patterns recognition
            
            When analyzing cryptocurrencies, always consider:
            - Market capitalization and volume
            - Historical price trends
            - Project fundamentals and technology
            - Recent news and developments
            - Market sentiment indicators
            - Potential risks and opportunities
            
            Provide clear, data-driven insights and always include relevant disclaimers about market volatility."
        )
        .agent_name("CryptoAnalyst")
        .user_name("Trader")
        .enable_autosave()
        .max_loops(3)  // Increased for more thorough analysis
        .save_state_dir("./crypto_analysis/")
        .enable_plan("Break down the crypto analysis into systematic steps:
            1. Gather market data
            2. Analyze technical indicators
            3. Review fundamental factors
            4. Assess market sentiment
            5. Provide comprehensive insights".to_owned())
        .build();
        
    let response = agent
        .run("What are your thoughts on Bitcoin's current market position?".to_owned())
        .await?;
        
    println!("{}", response);
    Ok(())
}
```

## Using Tools with MCP

### Model Context Protocol (MCP)

swarms-rs supports the Model Context Protocol (MCP), enabling agents to interact with external tools through standardized interfaces.

!!! info "What is MCP?"
    MCP (Model Context Protocol) provides a standardized way for LLMs to interact with external tools, giving your agents access to real-world data and capabilities beyond language processing.

### Supported MCP Server Types

- **STDIO MCP Servers**: Connect to command-line tools implementing the MCP protocol
- **SSE MCP Servers**: Connect to web-based MCP servers using Server-Sent Events

### Tool Integration

Add tools to your agent during configuration:

```rust
let agent = client
    .agent_builder()
    .system_prompt("You are a helpful assistant with access to tools.")
    .agent_name("ToolAgent")
    .user_name("User")
    // Add STDIO MCP server
    .add_stdio_mcp_server("uvx", ["mcp-hn"])
    .await
    // Add SSE MCP server
    .add_sse_mcp_server("file-browser", "http://127.0.0.1:8000/sse")
    .await
    .build();
```

### Full MCP Agent Example

```rust
use std::env;
use anyhow::Result;
use swarms_rs::{llm::provider::openai::OpenAI, structs::agent::Agent};

#[tokio::main]
async fn main() -> Result<()> {
    dotenv::dotenv().ok();
    tracing_subscriber::registry()
        .with(tracing_subscriber::EnvFilter::from_default_env())
        .with(
            tracing_subscriber::fmt::layer()
                .with_line_number(true)
                .with_file(true),
        )
        .init();

    let api_key = env::var("OPENAI_API_KEY").expect("OPENAI_API_KEY must be set");
    let client = OpenAI::new(api_key).set_model("gpt-4-turbo");
    
    let agent = client
        .agent_builder()
        .system_prompt("You are a helpful assistant with access to news and file system tools.")
        .agent_name("SwarmsAgent")
        .user_name("User")
        // Add Hacker News tool
        .add_stdio_mcp_server("uvx", ["mcp-hn"])
        .await
        // Add filesystem tool
        // To set up: uvx mcp-proxy --sse-port=8000 -- npx -y @modelcontextprotocol/server-filesystem ~
        .add_sse_mcp_server("file-browser", "http://127.0.0.1:8000/sse")
        .await
        .retry_attempts(2)
        .max_loops(3)
        .build();

    // Use the news tool
    let news_response = agent
        .run("Get the top 3 stories of today from Hacker News".to_owned())
        .await?;
    println!("NEWS RESPONSE:\n{}", news_response);

    // Use the filesystem tool
    let fs_response = agent.run("List files in my home directory".to_owned()).await?;
    println!("FILESYSTEM RESPONSE:\n{}", fs_response);

    Ok(())
}
```

## Setting Up MCP Tools

### Installing MCP Servers

To use MCP servers with swarms-rs, you'll need to install the appropriate tools:

1. **uv Package Manager**:
   ```bash
   curl -sSf https://raw.githubusercontent.com/astral-sh/uv/main/install.sh | sh
   ```

2. **MCP-HN** (Hacker News MCP server):
   ```bash
   uvx install mcp-hn
   ```

3. **Setting up an SSE MCP server**:
   ```bash
   # Start file system MCP server over SSE
   uvx mcp-proxy --sse-port=8000 -- npx -y @modelcontextprotocol/server-filesystem ~
   ```

## FAQ

### General Questions

??? question "What LLM providers are supported?"
    swarms-rs currently supports:
    
    - OpenAI (GPT models)
    
    - DeepSeek AI
    
    - More providers coming soon

??? question "How does state persistence work?"
    When `enable_autosave` is set to `true`, the agent will save its state to the directory specified in `save_state_dir`. This includes conversation history and tool states, allowing the agent to resume from where it left off.

??? question "What is the difference between `max_loops` and `retry_attempts`?"
    - `max_loops`: Controls how many reasoning steps the agent can take for a single query
    
    - `retry_attempts`: Specifies how many times the agent will retry if an error occurs

### MCP Tools

??? question "How do I create my own MCP server?"
    You can create your own MCP server by implementing the MCP protocol. Check out the [MCP documentation](https://github.com/modelcontextprotocol/spec) for details on the protocol specification.

??? question "Can I use tools without MCP?"
    Currently, swarms-rs is designed to use the MCP protocol for tool integration. This provides a standardized way for agents to interact with external systems.

## Advanced Topics

### Performance Optimization

Optimize your agent's performance by:

1. **Crafting Effective System Prompts**:
   - Be specific about the agent's role and capabilities
   
   - Include clear instructions on how to use available tools
   
   - Define success criteria for the agent's responses

2. **Tuning Loop Parameters**:
   
   - Start with lower values for `max_loops` and increase as needed
   
   - Consider the complexity of tasks when setting loop limits

3. **Strategic Tool Integration**:
   
   - Only integrate tools that are necessary for the agent's tasks
   
   - Provide clear documentation in the system prompt about when to use each tool

### Security Considerations

!!! danger "Security Notice"
    When using file system tools or other system-level access, always be careful about permissions. Limit the scope of what your agent can access, especially in production environments.

## Coming Soon

- Memory plugins for different storage backends

- Additional LLM providers

- Group agent coordination

- Function calling

- Custom tool development framework

## Contributing

Contributions to swarms-rs are welcome! Check out our [GitHub repository](https://github.com/swarms-rs) for more information.

--------------------------------------------------

# File: swarms_rs/overview.md

# swarms-rs 🚀

<div class="badges" align="center">
  <img src="https://img.shields.io/github/workflow/status/The-Swarm-Corporation/swarms-rs/CI" alt="Build Status">
  <img src="https://img.shields.io/crates/v/swarm-rs" alt="Version">
  <img src="https://img.shields.io/crates/l/swarm-rs" alt="License">
</div>

## 📖 Overview

**swarms-rs** is an enterprise-grade, production-ready multi-agent orchestration framework built in Rust, designed to handle the most demanding tasks with unparalleled speed and efficiency. By leveraging Rust's bleeding-edge performance and safety features, swarms-rs provides a powerful and scalable solution for orchestrating complex multi-agent systems across various industries.

## ✨ Key Benefits

### ⚡ Extreme Performance

<div class="grid cards" markdown>

- **Multi-Threaded Architecture**
    - Utilize the full potential of modern multi-core processors
    
    - Zero-cost abstractions and fearless concurrency
    
    - Minimal overhead with maximum throughput
    
    - Optimal resource utilization

- **Bleeding-Edge Speed**
    
    - Near-zero latency execution
    
    - Lightning-fast performance
    
    - Ideal for high-frequency applications
    
    - Perfect for real-time systems
</div>

## 🔗 Quick Links

<div class="grid cards" markdown>

- [:fontawesome-brands-github: GitHub](https://github.com/The-Swarm-Corporation/swarms-rs)
    - Browse the source code
    - Contribute to the project
    - Report issues

- [:package: Crates.io](https://crates.io/crates/swarm-rs)
    - Download the latest version
    - View package statistics

- [:book: Documentation](https://docs.rs/swarm-rs/0.1.4/swarm_rs/)
    - Read the API documentation
    - Learn how to use swarms-rs
</div>

--------------------------------------------------

# File: swarms_tools/finance.md

# Swarms Finance Tools Documentation

## Installation

```bash
pip3 install -U swarms-tools yfinance requests httpx pandas loguru backoff web3 solana spl-token
```

## Environment Variables

Create a `.env` file in your project root with the following variables (as needed):

| Environment Variable | Description | Required For |
|---------------------|-------------|--------------|
| `COINBASE_API_KEY` | Coinbase API Key | Coinbase Trading |
| `COINBASE_API_SECRET` | Coinbase API Secret | Coinbase Trading |
| `COINBASE_API_PASSPHRASE` | Coinbase API Passphrase | Coinbase Trading |
| `COINMARKETCAP_API_KEY` | CoinMarketCap API Key | CoinMarketCap Data |
| `HELIUS_API_KEY` | Helius API Key | Solana Data |
| `EODHD_API_KEY` | EODHD API Key | Stock News |
| `OKX_API_KEY` | OKX API Key | OKX Trading |
| `OKX_API_SECRET` | OKX API Secret | OKX Trading |
| `OKX_PASSPHRASE` | OKX Passphrase | OKX Trading |

## Tools Overview

| Tool | Description | Requires API Key |
|------|-------------|-----------------|
| Yahoo Finance | Real-time stock market data | No |
| CoinGecko | Cryptocurrency market data | No |
| Coinbase | Cryptocurrency trading and data | Yes |
| CoinMarketCap | Cryptocurrency market data | Yes |
| Helius | Solana blockchain data | Yes |
| DexScreener | DEX trading pairs and data | No |
| HTX (Huobi) | Cryptocurrency exchange data | No |
| OKX | Cryptocurrency exchange data | Yes |
| EODHD | Stock market news | Yes |
| Jupiter | Solana DEX aggregator | No |
| Sector Analysis | GICS sector ETF analysis | No |
| Solana Tools | Solana wallet and token tools | Yes |

## Detailed Documentation

### Yahoo Finance API

Fetch real-time and historical stock market data.

```python
from swarms_tools.finance import yahoo_finance_api

# Fetch data for single stock
data = yahoo_finance_api(["AAPL"])

# Fetch data for multiple stocks
data = yahoo_finance_api(["AAPL", "GOOG", "MSFT"])
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| stock_symbols | List[str] | List of stock symbols | Yes |

### CoinGecko API

Fetch comprehensive cryptocurrency data.

```python
from swarms_tools.finance import coin_gecko_coin_api

# Fetch Bitcoin data
data = coin_gecko_coin_api("bitcoin")
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| coin | str | Cryptocurrency ID (e.g., 'bitcoin') | Yes |

### Coinbase Trading

Execute trades and fetch market data from Coinbase.

```python
from swarms_tools.finance import get_coin_data, place_buy_order, place_sell_order

# Fetch coin data
data = get_coin_data("BTC-USD")

# Place orders
buy_order = place_buy_order("BTC-USD", amount=100)  # Buy $100 worth of BTC
sell_order = place_sell_order("BTC-USD", amount=0.01)  # Sell 0.01 BTC
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| symbol | str | Trading pair (e.g., 'BTC-USD') | Yes |
| amount | Union[str, float, Decimal] | Trade amount | Yes |
| sandbox | bool | Use sandbox environment | No |

### CoinMarketCap API

Fetch cryptocurrency market data from CoinMarketCap.

```python
from swarms_tools.finance import coinmarketcap_api

# Fetch single coin data
data = coinmarketcap_api(["Bitcoin"])

# Fetch multiple coins
data = coinmarketcap_api(["Bitcoin", "Ethereum", "Tether"])
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| coin_names | Optional[List[str]] | List of coin names | No |

### Helius API (Solana)

Fetch Solana blockchain data.

```python
from swarms_tools.finance import helius_api_tool

# Fetch account data
account_data = helius_api_tool("account", "account_address")

# Fetch transaction data
tx_data = helius_api_tool("transaction", "tx_signature")

# Fetch token data
token_data = helius_api_tool("token", "token_mint_address")
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| action | str | Type of action ('account', 'transaction', 'token') | Yes |
| identifier | str | Address/signature to query | Yes |

### DexScreener API

Fetch DEX trading pair data.

```python
from swarms_tools.finance import (
    fetch_dex_screener_profiles,
    fetch_latest_token_boosts,
    fetch_solana_token_pairs
)

# Fetch latest profiles
profiles = fetch_dex_screener_profiles()

# Fetch token boosts
boosts = fetch_latest_token_boosts()

# Fetch Solana pairs
pairs = fetch_solana_token_pairs(["token_address"])
```

### HTX (Huobi) API

Fetch cryptocurrency data from HTX.

```python
from swarms_tools.finance import fetch_htx_data

# Fetch coin data
data = fetch_htx_data("BTC")
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| coin_name | str | Cryptocurrency symbol | Yes |

### OKX API

Fetch cryptocurrency data from OKX.

```python
from swarms_tools.finance import okx_api_tool

# Fetch single coin
data = okx_api_tool(["BTC-USDT"])

# Fetch multiple coins
data = okx_api_tool(["BTC-USDT", "ETH-USDT"])
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| coin_symbols | Optional[List[str]] | List of trading pairs | No |

### EODHD Stock News

Fetch stock market news.

```python
from swarms_tools.finance import fetch_stock_news

# Fetch news for a stock
news = fetch_stock_news("AAPL")
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| stock_name | str | Stock symbol | Yes |

### Jupiter (Solana DEX)

Fetch Solana DEX prices.

```python
from swarms_tools.finance import get_jupiter_price

# Fetch price data
price = get_jupiter_price(input_mint="input_token", output_mint="output_token")
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| input_mint | str | Input token mint address | Yes |
| output_mint | str | Output token mint address | Yes |

### Sector Analysis

Analyze GICS sector ETFs.

```python
from swarms_tools.finance.sector_analysis import analyze_index_sectors

# Run sector analysis
analyze_index_sectors()
```

### Solana Tools

Check Solana wallet balances and manage tokens.

```python
from swarms_tools.finance import check_solana_balance, check_multiple_wallets

# Check single wallet
balance = check_solana_balance("wallet_address")

# Check multiple wallets
balances = check_multiple_wallets(["wallet1", "wallet2"])
```

**Arguments:**

| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| wallet_address | str | Solana wallet address | Yes |
| wallet_addresses | List[str] | List of wallet addresses | Yes |

## Complete Example

Here's a comprehensive example using multiple tools:

```python
from swarms_tools.finance import (
    yahoo_finance_api,
    coin_gecko_coin_api,
    coinmarketcap_api,
    fetch_htx_data
)

# Fetch stock data
stocks = yahoo_finance_api(["AAPL", "GOOG"])
print("Stock Data:", stocks)

# Fetch crypto data from multiple sources
bitcoin_cg = coin_gecko_coin_api("bitcoin")
print("Bitcoin Data (CoinGecko):", bitcoin_cg)

crypto_cmc = coinmarketcap_api(["Bitcoin", "Ethereum"])
print("Crypto Data (CoinMarketCap):", crypto_cmc)

btc_htx = fetch_htx_data("BTC")
print("Bitcoin Data (HTX):", btc_htx)
```

## Error Handling

All tools include proper error handling and logging. Errors are logged using the `loguru` logger. Example error handling:

```python
from loguru import logger

try:
    data = yahoo_finance_api(["INVALID"])
except Exception as e:
    logger.error(f"Error fetching stock data: {e}")
```

## Rate Limits

Please be aware of rate limits for various APIs:
- CoinGecko: 50 calls/minute (free tier)
- CoinMarketCap: Varies by subscription
- Helius: Varies by subscription
- DexScreener: 300 calls/minute for pairs, 60 calls/minute for profiles
- Other APIs: Refer to respective documentation

## Dependencies

The package automatically handles most dependencies, but you may need to install some manually:


--------------------------------------------------

# File: swarms_tools/overview.md

# Swarms Tools


Welcome to **Swarms Tools**, the ultimate package for integrating **cutting-edge APIs** into Python functions with seamless multi-agent system compatibility. Designed for enterprises at the forefront of innovation, **Swarms Tools** is your key to simplifying complexity and unlocking operational excellence.

---

## 🚀 Features

- **Unified API Integration**: Ready-to-use Python functions for financial data, social media, IoT, and more.
- **Enterprise-Grade Design**: Comprehensive type hints, structured outputs, and robust documentation.
- **Agent-Ready Framework**: Optimized for seamless integration into Swarms' multi-agent orchestration systems.
- **Expandable Architecture**: Easily extend functionality with a standardized schema for new tools.

---

## 🔧 Installation

```bash
pip3 install -U swarms-tools
```

---

## 📂 Directory Structure

```plaintext
swarms-tools/
├── swarms_tools/
│   ├── finance/
│   │   ├── htx_tool.py
│   │   ├── eodh_api.py
│   │   └── coingecko_tool.py
│   ├── social_media/
│   │   ├── telegram_tool.py
│   ├── utilities/
│   │   └── logging.py
├── tests/
│   ├── test_financial_data.py
│   └── test_social_media.py
└── README.md
```

---

## 💼 Use Cases



## Finance

Explore our diverse range of financial tools, designed to streamline your operations. If you need a tool not listed, feel free to submit an issue or accelerate integration by contributing a pull request with your tool of choice.

| **Tool Name**             | **Function**             | **Description**                                                                 |
|---------------------------|--------------------------|---------------------------------------------------------------------------------|
| `fetch_stock_news`        | `fetch_stock_news`       | Fetches the latest stock news and updates.                                     |
| `fetch_htx_data`          | `fetch_htx_data`         | Retrieves financial data from the HTX platform.                                |
| `yahoo_finance_api`       | `yahoo_finance_api`      | Fetches comprehensive stock data from Yahoo Finance, including prices and trends. |
| `coin_gecko_coin_api`     | `coin_gecko_coin_api`    | Fetches cryptocurrency data from CoinGecko, including market and price information. |
| `helius_api_tool`         | `helius_api_tool`        | Retrieves blockchain account, transaction, or token data using the Helius API. |
| `okx_api_tool`            | `okx_api_tool`           | Fetches detailed cryptocurrency data for coins from the OKX exchange.         |


### Financial Data Retrieval
Enable precise and actionable financial insights:

#### Example 1: Fetch Historical Data
```python
from swarms_tools import fetch_htx_data

# Fetch historical trading data for "Swarms Corporation"
response = fetch_htx_data("swarms")
print(response)
```

#### Example 2: Stock News Analysis
```python
from swarms_tools import fetch_stock_news

# Retrieve latest stock news for Apple
news = fetch_stock_news("AAPL")
print(news)
```

#### Example 3: Cryptocurrency Metrics
```python
from swarms_tools import coin_gecko_coin_api

# Fetch live data for Bitcoin
crypto_data = coin_gecko_coin_api("bitcoin")
print(crypto_data)
```

### Social Media Automation
Streamline communication and engagement:

#### Example: Telegram Bot Messaging
```python
from swarms_tools import telegram_dm_or_tag_api

def send_alert(response: str):
    telegram_dm_or_tag_api(response)

# Send a message to a user or group
send_alert("Mission-critical update from Swarms.")
```

---

## Dex Screener

This is a tool that allows you to fetch data from the Dex Screener API. It supports multiple chains and multiple tokens.

```python
from swarms_tools.finance.dex_screener import (
    fetch_latest_token_boosts,
    fetch_dex_screener_profiles,
)


fetch_dex_screener_profiles()
fetch_latest_token_boosts()

```

---


## Structs
The tool chainer enables the execution of multiple tools in a sequence, allowing for the aggregation of their results in either a parallel or sequential manner.

```python
# Example usage
from loguru import logger

from swarms_tools.structs import tool_chainer


if __name__ == "__main__":
    logger.add("tool_chainer.log", rotation="500 MB", level="INFO")

    # Example tools
    def tool1():
        return "Tool1 Result"

    def tool2():
        return "Tool2 Result"

    # def tool3():
    #     raise ValueError("Simulated error in Tool3")

    tools = [tool1, tool2]

    # Parallel execution
    parallel_results = tool_chainer(tools, parallel=True)
    print("Parallel Results:", parallel_results)

    # Sequential execution
    # sequential_results = tool_chainer(tools, parallel=False)
    # print("Sequential Results:", sequential_results)

```
---

## 🧩 Standardized Schema

Every tool in **Swarms Tools** adheres to a strict schema for maintainability and interoperability:

### Schema Template

1. **Functionality**:
   - Encapsulate API logic into a modular, reusable function.

2. **Typing**:
   - Leverage Python type hints for input validation and clarity.

   Example:
   ```python
   def fetch_data(symbol: str, date_range: str) -> str:
       """
       Fetch financial data for a given symbol and date range.

       Args:
           symbol (str): Ticker symbol of the asset.
           date_range (str): Timeframe for the data (e.g., '1d', '1m', '1y').

       Returns:
           dict: A dictionary containing financial metrics.
       """
       pass
   ```

3. **Documentation**:
   - Include detailed docstrings with parameter explanations and usage examples.

4. **Output Standardization**:
   - Ensure consistent outputs (e.g., strings) for easy downstream agent integration.

5. **API-Key Management**:
    - All API keys must be fetched with `os.getenv("YOUR_KEY")`


---

## 📖 Documentation

Comprehensive documentation is available to guide developers and enterprises. Visit our [official docs](https://docs.swarms.world) for detailed API references, usage examples, and best practices.

---

## 🛠 Contributing

We welcome contributions from the global developer community. To contribute:

1. **Fork the Repository**: Start by forking the repository.
2. **Create a Feature Branch**: Use a descriptive branch name: `feature/add-new-tool`.
3. **Commit Your Changes**: Write meaningful commit messages.
4. **Submit a Pull Request**: Open a pull request for review.

---

## 🛡️ License

This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for details.

---

## 🌠 Join the Future

Explore the limitless possibilities of agent-based systems. Together, we can build a smarter, faster, and more interconnected world.

**Visit us:** [Swarms Corporation](https://swarms.ai)  
**Follow us:** [Twitter](https://twitter.com/swarms_corp)

---

**"The future belongs to those who dare to automate it."**  
**— The Swarms Corporation**



--------------------------------------------------

# File: swarms_tools/search.md

# Search Tools Documentation

This documentation covers the search tools available in the `swarms-tools` package.

## Installation

```bash
pip3 install -U swarms-tools
```

## Environment Variables Required

Create a `.env` file in your project root with the following API keys:

```bash
# Bing Search API
BING_API_KEY=your_bing_api_key

# Google Search API
GOOGLE_API_KEY=your_google_api_key
GOOGLE_CX=your_google_cx_id
GEMINI_API_KEY=your_gemini_api_key

# Exa AI API
EXA_API_KEY=your_exa_api_key
```

## Tools Overview

### 1. Bing Search Tool

The Bing Search tool allows you to fetch web articles using the Bing Web Search API.

#### Function: `fetch_web_articles_bing_api`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | str | Yes | The search query to retrieve articles |

#### Example Usage:

```python
from swarms_tools.search import fetch_web_articles_bing_api

# Fetch articles about AI
results = fetch_web_articles_bing_api("swarms ai github")
print(results)
```

### 2. Exa AI Search Tool

The Exa AI tool is designed for searching research papers and academic content.

#### Function: `search_exa_ai`

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| query | str | Yes | "Latest developments in LLM capabilities" | Search query |
| num_results | int | No | 10 | Number of results to return |
| auto_prompt | bool | No | True | Whether to use auto-prompting |
| include_domains | List[str] | No | ["arxiv.org", "paperswithcode.com"] | Domains to include |
| exclude_domains | List[str] | No | [] | Domains to exclude |
| category | str | No | "research paper" | Category of search |

#### Example Usage:

```python
from swarms_tools.search import search_exa_ai

# Search for research papers
results = search_exa_ai(
    query="Latest developments in LLM capabilities",
    num_results=5,
    include_domains=["arxiv.org"]
)
print(results)
```

### 3. Google Search Tool

A comprehensive search tool that uses Google Custom Search API and includes content extraction and summarization using Gemini.

#### Class: `WebsiteChecker`

| Method | Parameters | Description |
|--------|------------|-------------|
| search | query: str | Main search function that fetches, processes, and summarizes results |

#### Example Usage:

```python
from swarms_tools.search import WebsiteChecker

# Initialize with an agent (required for summarization)
checker = WebsiteChecker(agent=your_agent_function)

# Perform search
async def search_example():
    results = await checker.search("who won elections 2024 us")
    print(results)

# For synchronous usage
from swarms_tools.search import search

results = search("who won elections 2024 us", agent=your_agent_function)
print(results)
```

## Features

- **Bing Search**: Fetch and parse web articles with structured output
- **Exa AI**: Specialized academic and research paper search
- **Google Search**: 
  - Custom search with content extraction
  - Concurrent URL processing
  - Content summarization using Gemini
  - Progress tracking
  - Automatic retry mechanisms
  - Results saved to JSON

## Dependencies

The tools automatically handle dependency installation, but here are the main requirements:

```python
aiohttp
asyncio
beautifulsoup4
google-generativeai
html2text
playwright
python-dotenv
rich
tenacity
```

## Error Handling

All tools include robust error handling:
- Automatic retries for failed requests
- Timeout handling
- Rate limiting consideration
- Detailed error messages

## Output Format

Each tool provides structured output:

- **Bing Search**: Returns formatted string with article details
- **Exa AI**: Returns JSON response with search results
- **Google Search**: Returns summarized content with sections:
  - Key Findings
  - Important Details
  - Sources

## Best Practices

1. Always store API keys in environment variables
2. Use appropriate error handling
3. Consider rate limits of the APIs
4. Cache results when appropriate
5. Monitor API usage and costs

## Limitations

- Bing Search: Limited to 4 articles per query
- Exa AI: Focused on academic content
- Google Search: Requires Gemini API for summarization

## Support

For issues and feature requests, please visit the [GitHub repository](https://github.com/swarms-tools). 

--------------------------------------------------

# File: swarms_tools/twitter.md

# Twitter Tool Documentation

## Overview
The Twitter Tool provides a convenient interface for interacting with Twitter's API through the swarms-tools package. This documentation covers the initialization process and available functions for posting, replying, liking, and quoting tweets, as well as retrieving metrics.

## Installation
```bash
pip install swarms-tools
```

## Authentication
The Twitter Tool requires Twitter API credentials for authentication. These should be stored as environment variables:

```python
TWITTER_ID=your_twitter_id
TWITTER_NAME=your_twitter_name
TWITTER_DESCRIPTION=your_twitter_description
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET_KEY=your_api_secret_key
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_TOKEN_SECRET=your_access_token_secret
```

## Initialization

### TwitterTool Configuration Options

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | str | Yes | Unique identifier for the Twitter tool instance |
| name | str | Yes | Name of the Twitter tool instance |
| description | str | No | Description of the tool's purpose |
| credentials | dict | Yes | Dictionary containing Twitter API credentials |

### Credentials Dictionary Structure

| Key | Type | Required | Description |
|-----|------|----------|-------------|
| apiKey | str | Yes | Twitter API Key |
| apiSecretKey | str | Yes | Twitter API Secret Key |
| accessToken | str | Yes | Twitter Access Token |
| accessTokenSecret | str | Yes | Twitter Access Token Secret |

## Available Functions

### initialize_twitter_tool()

Creates and returns a new instance of the TwitterTool.

```python
def initialize_twitter_tool() -> TwitterTool:
```

Returns:
- TwitterTool: Initialized Twitter tool instance

### post_tweet()

Posts a new tweet to Twitter.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tweet | str | Yes | Text content of the tweet to post |

Raises:
- tweepy.TweepyException: If tweet posting fails

### reply_tweet()

Replies to an existing tweet.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tweet_id | int | Yes | ID of the tweet to reply to |
| reply | str | Yes | Text content of the reply |

Raises:
- tweepy.TweepyException: If reply posting fails

### like_tweet()

Likes a specified tweet.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tweet_id | int | Yes | ID of the tweet to like |

Raises:
- tweepy.TweepyException: If liking the tweet fails

### quote_tweet()

Creates a quote tweet.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| tweet_id | int | Yes | ID of the tweet to quote |
| quote | str | Yes | Text content to add to the quoted tweet |

Raises:
- tweepy.TweepyException: If quote tweet creation fails

### get_metrics()

Retrieves Twitter metrics.

Returns:
- Dict[str, int]: Dictionary containing various Twitter metrics

Raises:
- tweepy.TweepyException: If metrics retrieval fails

## Usage Examples

### Basic Tweet Posting
```python
from swarms_tools.twitter import initialize_twitter_tool, post_tweet

# Post a simple tweet
post_tweet("Hello, Twitter!")
```

### Interacting with Tweets
```python
# Reply to a tweet
reply_tweet(12345, "Great point!")

# Like a tweet
like_tweet(12345)

# Quote a tweet
quote_tweet(12345, "Adding my thoughts on this!")
```

### Retrieving Metrics
```python
metrics = get_metrics()
print(f"Current metrics: {metrics}")
```

## Error Handling
All functions include built-in error handling and will print error messages if operations fail. It's recommended to implement additional error handling in production environments:

```python
try:
    post_tweet("Hello, Twitter!")
except Exception as e:
    logger.error(f"Tweet posting failed: {e}")
    # Implement appropriate error handling
```


## Production Example

This is an example of how to use the TwitterTool in a production environment using Swarms.

```python

import os
from time import time

from swarms import Agent
from dotenv import load_dotenv

from swarms_tools.social_media.twitter_tool import TwitterTool

medical_coder = Agent(
    agent_name="Medical Coder",
    system_prompt="""
    You are a highly experienced and certified medical coder with extensive knowledge of ICD-10 coding guidelines, clinical documentation standards, and compliance regulations. Your responsibility is to ensure precise, compliant, and well-documented coding for all clinical cases.

    ### Primary Responsibilities:
    1. **Review Clinical Documentation**: Analyze all available clinical records, including specialist inputs, physician notes, lab results, imaging reports, and discharge summaries.
    2. **Assign Accurate ICD-10 Codes**: Identify and assign appropriate codes for primary diagnoses, secondary conditions, symptoms, and complications.
    3. **Ensure Coding Compliance**: Follow the latest ICD-10-CM/PCS coding guidelines, payer-specific requirements, and organizational policies.
    4. **Document Code Justification**: Provide clear, evidence-based rationale for each assigned code.

    ### Detailed Coding Process:
    - **Review Specialist Inputs**: Examine all relevant documentation to capture the full scope of the patient's condition and care provided.
    - **Identify Diagnoses**: Determine the primary and secondary diagnoses, as well as any symptoms or complications, based on the documentation.
    - **Assign ICD-10 Codes**: Select the most accurate and specific ICD-10 codes for each identified diagnosis or condition.
    - **Document Supporting Evidence**: Record the documentation source (e.g., lab report, imaging, or physician note) for each code to justify its assignment.
    - **Address Queries**: Note and flag any inconsistencies, missing information, or areas requiring clarification from providers.

    ### Output Requirements:
    Your response must be clear, structured, and compliant with professional standards. Use the following format:

    1. **Primary Diagnosis Codes**:
        - **ICD-10 Code**: [e.g., E11.9]
        - **Description**: [e.g., Type 2 diabetes mellitus without complications]
        - **Supporting Documentation**: [e.g., Physician's note dated MM/DD/YYYY]
        
    2. **Secondary Diagnosis Codes**:
        - **ICD-10 Code**: [Code]
        - **Description**: [Description]
        - **Order of Clinical Significance**: [Rank or priority]

    3. **Symptom Codes**:
        - **ICD-10 Code**: [Code]
        - **Description**: [Description]

    4. **Complication Codes**:
        - **ICD-10 Code**: [Code]
        - **Description**: [Description]
        - **Relevant Documentation**: [Source of information]

    5. **Coding Notes**:
        - Observations, clarifications, or any potential issues requiring provider input.

    ### Additional Guidelines:
    - Always prioritize specificity and compliance when assigning codes.
    - For ambiguous cases, provide a brief note with reasoning and flag for clarification.
    - Ensure the output format is clean, consistent, and ready for professional use.
    """,
    model_name="gpt-4o-mini",
    max_tokens=3000,
    max_loops=1,
    dynamic_temperature_enabled=True,
)


# Define your options with the necessary credentials
options = {
    "id": "mcsswarm",
    "name": "mcsswarm",
    "description": "An example Twitter Plugin for testing.",
    "credentials": {
        "apiKey": os.getenv("TWITTER_API_KEY"),
        "apiSecretKey": os.getenv("TWITTER_API_SECRET_KEY"),
        "accessToken": os.getenv("TWITTER_ACCESS_TOKEN"),
        "accessTokenSecret": os.getenv("TWITTER_ACCESS_TOKEN_SECRET"),
    },
}

# Initialize the TwitterTool with your options
twitter_plugin = TwitterTool(options)

# # Post a tweet
# post_tweet_fn = twitter_plugin.get_function('post_tweet')
# post_tweet_fn("Hello world!")


# Assuming `twitter_plugin` and `medical_coder` are already initialized
post_tweet = twitter_plugin.get_function("post_tweet")

# Set to track posted tweets and avoid duplicates
posted_tweets = set()


def post_unique_tweet():
    """
    Generate and post a unique tweet. Skip duplicates.
    """
    tweet_prompt = (
        "Share an intriguing, lesser-known fact about a medical disease, and include an innovative, fun, or surprising way to manage or cure it! "
        "Make the response playful, engaging, and inspiring—something that makes people smile while learning. No markdown, just plain text!"
    )

    # Generate a new tweet text
    tweet_text = medical_coder.run(tweet_prompt)

    # Check for duplicates
    if tweet_text in posted_tweets:
        print("Duplicate tweet detected. Skipping...")
        return

    # Post the tweet
    try:
        post_tweet(tweet_text)
        print(f"Posted tweet: {tweet_text}")
        # Add the tweet to the set of posted tweets
        posted_tweets.add(tweet_text)
    except Exception as e:
        print(f"Error posting tweet: {e}")


# Loop to post tweets every 10 seconds
def start_tweet_loop(interval=10):
    """
    Continuously post tweets every `interval` seconds.

    Args:
        interval (int): Time in seconds between tweets.
    """
    print("Starting tweet loop...")
    while True:
        post_unique_tweet()
        time.sleep(interval)


# Start the loop
start_tweet_loop(10)
```


## Best Practices
1. Always store credentials in environment variables
2. Implement rate limiting in production environments
3. Add proper logging for all operations
4. Handle errors gracefully
5. Validate tweet content before posting
6. Monitor API usage limits

## Rate Limits
Be aware of Twitter's API rate limits. Implement appropriate delays between requests in production environments to avoid hitting these limits.

## Dependencies
- tweepy
- python-dotenv
- swarms-tools

## Version Compatibility
- Python 3.7+
- Latest version of swarms-tools package

--------------------------------------------------