--- 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.