Upload 🏛️ Multi-Model Hierarchical Research System.md

🏛️ Multi-Model Hierarchical Research System.md

@@ -0,0 +1,460 @@
+# 🏛️ 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.