# Multi-Swarm Framework

A powerful framework for creating collaborative AI agent swarms, supporting multiple LLM providers and advanced agent management capabilities.

## Latest Version: 1.0.5

### What's New
- Plugin system for extensible agent capabilities
- Centralized YAML configuration for model management
- Enhanced experimental model support
- Improved version compatibility handling
- Enhanced knowledge coordination across agents
- Improved temporal awareness in document retrieval
- Better knowledge gap detection and analysis
- Advanced knowledge synthesis capabilities
- Optimized collaborative search functionality
- Improved communication flows between agents
- Enhanced state management and persistence
- Better error handling and recovery mechanisms

## Features

### Plugin System
- Extensible plugin architecture for custom tools
- Built-in plugin registry and management
- Example tools including Git integration
- Easy-to-implement plugin interface
- Automatic plugin discovery and loading
- Plugin health monitoring and lifecycle management

### Multi-LLM Support
- Claude (Anthropic) integration with latest models:
  - claude-3-5-sonnet-latest (balanced)
  - claude-3-5-opus-latest (research)
- Gemini (Google) integration with latest models:
  - gemini-2.0-flash-exp (high performance)
- Automatic model selection based on agent roles and tasks

### Advanced Agency Management
- Flexible agent creation and configuration
- Sophisticated communication flows between agents
- State persistence and thread management
- Automated task distribution and coordination
- Knowledge synthesis and gap analysis

### Built-in Tools
- Plugin-based tool architecture
- Git integration for version control
- Code Interpreter for executing Python code
- RAG system with temporal awareness
- File Search with semantic capabilities
- Docker integration for isolated environments
- Customizable tool creation framework

## Installation

```bash
pip install multi-swarm
```

For development:
```bash
pip install multi-swarm[dev]
```

For GPU support:
```bash
pip install multi-swarm[gpu]
```

## Quick Start

```python
from multi_swarm import Agency, Agent
from multi_swarm.plugins.tools.development import GitTool

# Create agents with specific roles
ceo = Agent(
    name="CEO",
    description="Manages overall strategy and coordination",
    llm_provider="claude",  # Will use claude-3-5-sonnet-latest
    provider_config={
        "model": "claude-3-5-sonnet-latest",
        "api_version": "2024-03"
    }
)

developer = Agent(
    name="Developer",
    description="Handles technical implementation",
    llm_provider="gemini",  # Will use gemini-2.0-flash-exp
    provider_config={
        "model": "gemini-2.0-flash-exp",
        "api_version": "2024-01"
    }
)

# Register tools with agents
git_tool = GitTool()
developer.register_tool(git_tool)

# Create agency with communication flows
agency = Agency([
    ceo,  # Entry point for user communication
    [ceo, developer],  # CEO can communicate with Developer
])

# Run the agency
agency.run()
```

## Plugin Development

Create custom plugins by extending the base plugin class:

```python
from multi_swarm.plugins.base import PluginBase, PluginMetadata

class CustomTool(PluginBase):
    """Custom tool implementation."""
    def __init__(self):
        metadata = PluginMetadata(
            name="custom_tool",
            version="1.0.0",
            description="Custom tool description",
            author="Your Name",
            requirements=["required-package"],
            tags=["custom", "tool"]
        )
        super().__init__(metadata=metadata)
    
    def get_capabilities(self):
        return ["custom_capability"]
```

## Task-Specific Model Selection

The framework automatically selects the best model based on the agent's role:

### Claude Models
- Code Generation & Development: claude-3-5-sonnet-latest
- Research & Analysis: claude-3-5-opus-latest
- Technical Writing: claude-3-5-sonnet-latest

### Gemini Models
- Data Processing: gemini-2.0-flash-exp
- Real-time Operations: gemini-2.0-flash-exp
- Machine Learning Tasks: gemini-2.0-flash-exp

## Documentation

For detailed documentation, visit:
- [Getting Started Guide](docs/getting-started/index.md)
- [API Reference](docs/api/index.md)
- [Examples](docs/examples/index.md)
- [LLM Providers](docs/providers/index.md)

## Requirements

- Python 3.8+
- Dependencies:
  - anthropic>=0.18.1
  - google-generativeai>=0.3.2
  - pydantic>=2.0.0
  - python-dotenv>=1.0.0
  - docker>=6.1.0
  - sentence-transformers>=2.2.0
  - faiss-cpu>=1.7.4 (or faiss-gpu for GPU support)
  - transformers>=4.38.0
  - torch>=2.0.0
  - numpy>=1.24.0
  - click>=8.0.0

## Optional Dependencies

### Development Tools
- pytest>=8.0.0
- pytest-asyncio>=0.25.0
- pytest-cov>=6.0.0
- black>=24.0.0
- isort>=5.0.0
- mypy>=1.8.0

### GPU Support
- faiss-gpu>=1.7.4
- torch>=2.0.0 (with CUDA support)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md).

## Support

- Report issues on [GitHub Issues](https://github.com/bartvanspitaels99/multi-swarm/issues)
- Join discussions in [GitHub Discussions](https://github.com/bartvanspitaels99/multi-swarm/discussions)

## Authors

- Bart Van Spitaels (bart.vanspitaels@gmail.com) 