README.md

metadata

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:

1. Click "New token"
2. Select "Read" permission
3. Copy the token (starts with hf_...)

2. Set Environment Variable

# 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

pip install -r requirements.txt

4. Run the Application

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

# 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:

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:

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

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

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()

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

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
• Gradio Documentation
• SmolaGents Documentation
• Multi-Agent Systems

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