README.md

---
title: Heavy Multi-Model 2.0
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "4.44.1"
app_file: app.py
pinned: false
---

# 🤖 Heavy Multi-Model 2.0 - AI Analysis System

**Version 2.0** - Now with Web Search Integration!

A powerful multi-agent AI analysis system that leverages multiple AI models working in parallel to provide comprehensive, well-researched responses to complex queries.

## 🆕 What's New in v2.0

### Web Search Integration with Tavily
- **Real-time Information**: Agents can now search the web for current data and facts
- **Enhanced Analysis**: Each agent performs web searches for their specialized questions
- **Source Citation**: Responses include references to web sources when using search
- **Optional Feature**: Enable/disable web search with a simple checkbox
- **User-provided API Key**: Bring your own Tavily API key for complete control

### Features from v1.0
- **Multi-Model Support**: GPT-5, **GPT-5.1**, Gemini 3 Pro Preview, Gemini 2.5 Pro, Claude 4.5 Sonnet, **Claude 4.5 Opus**, GPT-4.1 Mini, Gemini 2.0 Flash, Llama 3.1 70B
- **Flexible Configuration**:
  - Single Model Mode: Use one model for all roles
  - Multi-Model Mode: Assign different models to each role
  - make-it-heavy Mode: Use the original implementation
- **Parallel Execution**: Multiple agents analyze different aspects simultaneously
- **Web Interface**: Beautiful Gradio-based UI with real-time updates

## 🏗️ Architecture

### Multi-Agent Workflow

1. **Orchestrator**: Breaks down your query into specialized research questions
2. **Agents** (2-8): Each agent:
   - Receives a specialized question
   - **(NEW)** Optionally searches the web for relevant information
   - Analyzes their question from a unique perspective
   - Runs in parallel with other agents
3. **Synthesizer**: Combines all agent insights into a comprehensive response

### Role-Based Model Assignment

Different AI models excel at different tasks:
- **Orchestrator**: Requires strong reasoning to generate meaningful questions
- **Agents**: Need analytical depth and diverse perspectives
- **Synthesizer**: Must excel at combining and organizing information

You can assign the best model to each role, or keep it simple with a single model for everything.

## 🚀 Getting Started

### Prerequisites

- Python 3.8 or higher
- OpenRouter API key (get it from [openrouter.ai/keys](https://openrouter.ai/keys))
- **(Optional)** Tavily API key for web search (get it from [tavily.com](https://tavily.com))

### Installation

1. Navigate to this directory:
```bash
cd "Heavy 2.0"
```

2. Install dependencies:
```bash
pip install -r requirements.txt
```

3. Run the application:
```bash
python app.py
```

4. Open your browser to `http://localhost:7860`

## 📖 Usage

### Basic Workflow

1. **Enter API Keys**:
   - OpenRouter API key (required)
   - Tavily API key (optional, for web search)

2. **Enable Web Search** (Optional):
   - Check the "Enable Web Search" box
   - Enter your Tavily API key
   - Agents will now search the web for each specialized question

3. **Choose Configuration Mode**:
   - **Single Model**: Use one model for all roles (simplest)
   - **Multi-Model**: Assign different models to each role (most flexible)
   - **make-it-heavy**: Use the original implementation (cost-effective)

4. **Configure Analysis**:
   - Number of agents (2-8): More agents = more perspectives
   - Show agent thoughts: Display individual agent analyses

5. **Submit Your Query** and watch the magic happen!

### Example Queries

Perfect for web search:
- "What are the latest developments in quantum computing?"
- "What are the current best practices for React 18?"
- "What happened in the tech industry this week?"

Great for analysis:
- "What are the trade-offs between microservices and monolithic architecture?"
- "How should I design a scalable authentication system?"
- "What factors should I consider when choosing a database?"

## 🔧 Configuration

### Model Options

All models are accessed through OpenRouter:

| Model | Best For | Speed | Cost |
|-------|----------|-------|------|
| GPT-5.1 | Frontier reasoning + creativity | Medium | $$$$ |
| GPT-5 | Creative solutions | Fast | $$$ |
| Gemini 3 Pro Preview | Multimodal depth & planning | Medium | $$$ |
| Gemini 2.5 Pro | Synthesis & organization | Medium | $$ |
| Claude 4.5 Opus | Frontier reasoning & software engineering | Medium | $$$$ |
| Claude 4.5 Sonnet | Deep reasoning | Medium | $$$ |
| GPT-4.1 Mini | Cost-effective analysis | Fast | $ |
| Gemini 2.0 Flash | Quick responses | Very Fast | $ |
| Llama 3.1 70B | Open source option | Medium | $ |

### Web Search (Tavily)

When enabled, each agent:
1. Receives their specialized question
2. Searches the web using Tavily's advanced search
3. Gets an AI-generated summary + top 5 search results
4. Uses this context to enhance their analysis
5. Cites sources in their response

**Search Depth**: Advanced (configurable in `tavily_search.py`)
**Results per query**: 5 (configurable)

## 📁 Project Structure

```
Heavy 2.0/
├── app.py                  # Entry point for Gradio app
├── config.yaml             # Configuration file
├── requirements.txt        # Python dependencies
├── src/
│   ├── __init__.py
│   ├── multi_web.py        # Gradio web interface
│   ├── multi_client.py     # Multi-model API client
│   ├── multi_orchestrator.py  # Workflow orchestrator
│   ├── multi_agent.py      # Individual agent logic
│   └── tavily_search.py    # NEW: Tavily web search integration
└── README.md
```

## 🔐 Security & Privacy

- **API Keys**: Never stored, only used during your session
- **Web Search**: Tavily searches are performed on-demand and not cached
- **No Data Collection**: Your queries and responses are not logged or saved

## 🛠️ Development

### Extending the System

**Add a new model**:
```python
# In src/multi_client.py
MODELS = {
    "your-model": {
        "provider": "openrouter",
        "model_id": "provider/model-name",
        "display_name": "Your Model Name"
    }
}
```

**Customize web search**:
```python
# In src/tavily_search.py
def search(self, query: str, max_results: int = 5):
    # Adjust max_results, search_depth, etc.
    pass
```

**Modify agent behavior**:
```python
# In src/multi_agent.py
def _build_system_prompt(self):
    # Customize agent instructions
    pass
```

## 📊 Performance Tips

1. **Use web search selectively**: Great for current events, not needed for general analysis
2. **Adjust agent count**: More agents = more perspectives but slower/costlier
3. **Choose models wisely**:
   - Quick answers: Gemini 2.0 Flash + GPT-4.1 Mini
   - Deep analysis: Claude 4.5 Sonnet + GPT-5
   - Cost-effective: GPT-4.1 Mini for all roles

## 🤝 Contributing

This is based on the original Heavy/make-it-heavy project. v2.0 adds:
- Tavily web search integration
- Enhanced UI with search controls
- Dynamic context enrichment for agents
- Source citation capabilities

## 📄 License

[Same as original project]

## 🙏 Acknowledgments

- Original Heavy project from Justin-Choo
- Tavily for web search API
- OpenRouter for multi-model access
- Gradio for the amazing UI framework

---

**Built with ❤️ using Python, Gradio, and multiple AI models**

For questions or issues, please refer to the original project or check the Tavily/OpenRouter documentation.