README.md

---
title: ResearchAI
emoji: 🏛️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "4.44.0"
app_file: app.py
pinned: false
---

# 🏛️ Multi-Model Hierarchical Research System

A sophisticated **hierarchical multi-agent research system** with real-time progress tracking and live dashboard. Powered by multiple AI models (Qwen, Llama, Mistral) for comprehensive market research, competitive analysis, and strategic insights.

## ✨ Features

### 🎯 Hierarchical Multi-Agent Architecture
```
Supervisor (Strategy)
    ↓
    ├─→ Researcher Agent 🏆 (Industry Leaders)
    ├─→ Analyzer Agent ⭐ (Best Practices)
    └─→ Critic Agent 🔍 (Quality Review)
    ↓
Synthesizer Agent 💡 (Recommendations)
```

### 📊 Real-Time Progress Tracking
- **Live Dashboard** - Watch research progress in real-time
- **Phase-by-phase updates** - See each agent's status
- **Execution metrics** - Track timing and performance
- **Error handling** - Graceful degradation with retry logic

### 🤖 Multi-Model Support
- **Qwen 2.5 7B** - Fast & efficient analysis
- **Qwen 2.5 72B** - Most capable Qwen model
- **Meta Llama 3.1 70B** - Strong reasoning capabilities
- **Mistral Large** - Excellent analysis and synthesis

### 🔍 Comprehensive Research
- **Industry Leaders** - Top 5 companies setting standards
- **Best Practices** - Proven methods and innovations
- **Quality Review** - Independent assessment and validation
- **Strategic Recommendations** - Actionable roadmap

### 📈 Rich Output
- Executive summaries with infographics
- Execution timelines and performance metrics
- Model assignment verification
- Search history and metadata

## 🚀 Quick Start

### 1. **Get HuggingFace API Token**

Visit [HuggingFace Settings](https://huggingface.co/settings/tokens):
1. Click "New token"
2. Select "Read" permission
3. Copy the token (starts with `hf_...`)

### 2. **Set Environment Variable**

```bash
# On Linux/Mac
export HF_TOKEN=hf_your_token_here

# On Windows (PowerShell)
$env:HF_TOKEN="hf_your_token_here"

# Or create .env file
echo "HF_TOKEN=hf_your_token_here" > .env
```

### 3. **Install Dependencies**

```bash
pip install -r requirements.txt
```

### 4. **Run the Application**

```bash
python app.py
```

The application will start on `http://localhost:7860`

## 📋 Usage Guide

### Basic Research

1. **Enter Research Topic**
   - Example: "AI project management tools"
   - Example: "Sustainable fashion brands"
   - Example: "Electric vehicle charging infrastructure"

2. **Click "Start Research"**
   - Watch the Live Dashboard tab for real-time progress
   - Each agent will execute in sequence

3. **Review Results**
   - **Summary**: Executive overview and metadata
   - **Industry Leaders**: Top 5 companies/products
   - **Best Practices**: Proven strategies and innovations
   - **Quality Review**: Independent assessment
   - **Recommendations**: Strategic action plan

### Advanced: Configure Models

1. Open "Configure AI Models" accordion
2. Select different models for each phase:
   - Query Understanding
   - Industry Leaders Research
   - Best Practices Analysis
   - Quality Review
   - Recommendations Generation

3. Click "Start Research" with custom configuration

## 📊 Understanding the Output

### Live Dashboard
Shows real-time progress as research happens:
```
🚀 Research started!
📌 Topic: AI project management tools
🤖 Models configured: 4 unique models

🏆 PHASE 1: RESEARCHER AGENT - Industry Leaders
   Model: Qwen/Qwen2.5-72B-Instruct
   Status: ⏳ Running...
   Status: ✅ Complete (24.5s)

⭐ PHASE 2: ANALYZER AGENT - Best Practices
   Model: Qwen/Qwen2.5-72B-Instruct
   Status: ⏳ Running...
   Status: ✅ Complete (25.2s)

[... more phases ...]

📊 RESEARCH COMPLETE!
📈 EXECUTION SUMMARY:
   🏆 Researcher:  24.5s [████████████████████░░░░░░░░]
   ⭐ Analyzer:    25.2s [████████████████████░░░░░░░░]
   🔍 Critic:      14.8s [████████████░░░░░░░░░░░░░░░░]
   💡 Synthesizer: 19.5s [██████████████████░░░░░░░░░░]
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   📈 TOTAL TIME:  84.0s [██████████████████████████░░]
```

### Summary Tab
- Research overview with hierarchy diagram
- Agent execution status and timing
- Performance metrics
- Model assignment verification
- Research metadata

### Industry Leaders Tab
- Top 5 companies/products
- Market positioning
- Key strengths
- Notable features
- Market metrics

### Best Practices Tab
- Industry standards and frameworks
- Success stories and case studies
- Innovation patterns
- Implementation guidelines
- Key takeaways

### Quality Review Tab
- Research completeness assessment
- Source quality evaluation
- Recency and relevance check
- Clarity and usefulness rating
- Improvement recommendations
- Overall quality scores

### Recommendations Tab
- Executive summary
- Immediate actions (0-30 days)
- Short-term strategy (1-3 months)
- Long-term vision (3-12 months)
- Success metrics
- Risk mitigation strategies
- Resource requirements
- Next steps

## 🏗️ Architecture

### Research Engine
- **MultiModelResearchEngine**: Orchestrates agent execution
- **Model Caching**: Efficient model instance management
- **Retry Logic**: Automatic fallback for API errors
- **Web Search Integration**: Real-time information gathering

### Agent System
1. **Researcher Agent** 🏆
   - Identifies top industry leaders
   - Analyzes market positioning
   - Gathers competitive intelligence

2. **Analyzer Agent** ⭐
   - Researches best practices
   - Identifies success patterns
   - Documents innovations

3. **Critic Agent** 🔍
   - Quality assurance review
   - Source validation
   - Gap identification

4. **Synthesizer Agent** 💡
   - Synthesizes all inputs
   - Generates recommendations
   - Creates action roadmap

### State Management
- **ResearchState**: Tracks search history, model usage, dashboard updates
- **Live Updates**: Real-time progress tracking
- **Caching**: Results and model instances

## 🔧 Configuration

### Environment Variables

```bash
# Required
HF_TOKEN=hf_your_token_here

# Optional (for future extensions)
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
```

### Model Selection

Edit `DEFAULT_PHASE_MODELS` in `app.py`:

```python
DEFAULT_PHASE_MODELS = {
    "query_understanding": "qwen-2.5-7b",
    "industry_leaders": "qwen-2.5-72b",
    "best_practices": "qwen-2.5-72b",
    "quality_review": "qwen-2.5-72b",
    "recommendations": "qwen-2.5-72b"
}
```

### Available Models

| Model | Provider | Speed | Quality | Cost |
|-------|----------|-------|---------|------|
| Qwen 2.5 7B | HuggingFace | ⚡⚡⚡ | ⭐⭐⭐ | 💰 |
| Qwen 2.5 72B | HuggingFace | ⚡⚡ | ⭐⭐⭐⭐ | 💰💰 |
| Llama 3.1 70B | HuggingFace | ⚡⚡ | ⭐⭐⭐⭐ | 💰💰 |
| Mistral Large | HuggingFace | ⚡⚡ | ⭐⭐⭐⭐ | 💰💰 |

## 📈 Expected Performance

### Typical Execution Times

| Phase | Duration | Notes |
|-------|----------|-------|
| Researcher Agent | 20-30s | Includes web search |
| Analyzer Agent | 20-30s | Includes web search |
| Critic Agent | 10-20s | No web search |
| Synthesizer Agent | 15-25s | No web search |
| **Total** | **80-120s** | ~2 minutes |

### Factors Affecting Speed
- Model size (larger = slower)
- Topic complexity
- Internet speed (affects web search)
- API response time
- System load

## 🐛 Troubleshooting

### "HF_TOKEN not found"
**Solution**: Set the environment variable:
```bash
export HF_TOKEN=hf_your_token_here
```

### "API compatibility issue"
**Solution**: The system automatically falls back to compatible configurations. If issues persist:
1. Try using Qwen models instead
2. Simplify your research topic
3. Check your internet connection

### "Research stuck on Running"
**Solution**:
1. Check internet connection
2. Verify HF_TOKEN is valid
3. Try a simpler topic
4. Check HuggingFace API status

### "Empty results"
**Solution**:
1. Check the Live Dashboard for errors
2. Verify all models are available
3. Try with default model configuration
4. Simplify the research topic

## 📦 Deployment

### Local Deployment
```bash
python app.py
```

### HuggingFace Spaces
1. Create new Space on HuggingFace
2. Upload files:
   - `app.py`
   - `requirements.txt`
   - `.env` (with HF_TOKEN)
3. HuggingFace automatically detects Gradio app
4. Space launches automatically

### Docker Deployment
```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY app.py .

ENV HF_TOKEN=your_token_here

CMD ["python", "app.py"]
```

## 📚 File Structure

```
.
├── app.py                 # Main application
├── requirements.txt       # Python dependencies
├── agents_config.yaml     # Agent configuration (optional)
├── .env                   # Environment variables (local only)
└── README.md             # This file
```

## 🔐 Security

### API Key Management
- Never commit `.env` file to version control
- Use HuggingFace Spaces secrets for deployment
- Rotate tokens regularly
- Use read-only tokens when possible

### Data Privacy
- Research results are not stored
- Web searches are performed by the models
- No data is sent to external services except HuggingFace API
- Each session is independent

## 📖 API Reference

### Main Function: `run_research()`

```python
run_research(
    topic: str,
    model_query: str,
    model_leaders: str,
    model_practices: str,
    model_quality: str,
    model_recommendations: str,
    progress: gr.Progress
) -> Tuple[str, str, str, str, str, str]
```

**Parameters:**
- `topic`: Research topic
- `model_*`: Model selection for each phase
- `progress`: Gradio progress callback

**Returns:**
- Summary, Leaders, Practices, Review, Recommendations, Dashboard

### Research Engine

```python
engine = MultiModelResearchEngine(phase_models)
engine.research_industry_leaders(topic)
engine.research_best_practices(topic)
engine.quality_review(research_text)
engine.generate_recommendations(topic, research_text)
```

## 🤝 Contributing

Contributions are welcome! Areas for enhancement:
- Additional model support
- Custom agent configurations
- Export formats (PDF, DOCX, etc.)
- Caching and persistence
- Advanced filtering options

## 📄 License

MIT License - See LICENSE file for details

## 🙋 Support

### Getting Help
1. Check the Troubleshooting section
2. Review the Live Dashboard for error messages
3. Verify environment setup
4. Check HuggingFace API status

### Common Issues

**Q: How long does research take?**
A: Typically 80-120 seconds (about 2 minutes) depending on topic complexity and model selection.

**Q: Can I use different models for each phase?**
A: Yes! Use the "Configure AI Models" accordion to select different models.

**Q: What if a model fails?**
A: The system has automatic retry logic and will gracefully degrade to compatible configurations.

**Q: How many searches are performed?**
A: Typically 8-12 searches across the Researcher and Analyzer agents.

**Q: Can I export the results?**
A: Results are displayed in markdown format and can be copied. Future versions will support PDF/DOCX export.

## 🎓 Learning Resources

- [HuggingFace Hub Documentation](https://huggingface.co/docs/hub)
- [Gradio Documentation](https://www.gradio.app/docs)
- [SmolaGents Documentation](https://huggingface.co/docs/smolagents)
- [Multi-Agent Systems](https://en.wikipedia.org/wiki/Multi-agent_system)

## 🚀 Roadmap

### Upcoming Features
- [ ] PDF/DOCX export
- [ ] Custom agent configuration via YAML
- [ ] Result caching and history
- [ ] Advanced filtering options
- [ ] Custom prompt templates
- [ ] Multi-language support
- [ ] API endpoint for programmatic access
- [ ] Result persistence and database storage

## 📊 Metrics & Analytics

The system tracks:
- Execution time per agent
- Model usage statistics
- Search queries performed
- Success/failure rates
- Research coverage metrics

All metrics are displayed in the Summary and Dashboard tabs.

---

**Made with ❤️ for intelligent research and decision-making**

For questions or suggestions, please open an issue or contact the development team.