[![codecov](https://codecov.io/gh/zbloss/agent-expert-panel/graph/badge.svg?token=ZLecmiZ5dp)](https://codecov.io/gh/zbloss/agent-expert-panel)



# 🧠 Agent Expert Panel

A sophisticated multi-agent discussion framework that orchestrates AI experts to solve complex problems through collaborative reasoning.

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

## 🌟 Overview

**Agent Expert Panel** is a powerful Python framework for multi-agent AI collaboration, inspired by groundbreaking research from Microsoft's MAI-DxO (Medical AI Diagnostic Orchestrator) and Hugging Face's Consilium platform.

This system is specifically designed for **isolated decision-makers** in unique roles like CEOs, CTOs, Head of Product, and Startup Founders who need expert-level guidance but lack access to diverse expert opinions.

Recent research has demonstrated that multi-agent systems can achieve remarkable results:
- Microsoft's MAI-DxO achieved **85.5% diagnostic accuracy** vs **20% for human physicians** on complex medical cases
- Multi-agent collaboration reduces cognitive biases and improves decision quality
- Diverse expert perspectives lead to more robust and comprehensive solutions

## 🎯 Perfect For

- **CEOs & Founders**: Strategic decisions with high stakes and limited expert access
- **CTOs & Technical Leaders**: Complex architecture choices requiring current best practices
- **Head of Product**: Feature prioritization backed by market research and user insights
- **Other Executives**: Anyone in a 1-of-1 role making decisions without peer consultation

## ✨ Key Features

### 🧠 **GraphRAG-Enhanced Knowledge System**
- **Persistent memory**: Knowledge persists across sessions and grows smarter over time
- **Intelligent indexing**: GraphRAG creates searchable knowledge graphs from research and user context
- **Domain-specific workspaces**: Separate knowledge bases for different problem areas
- **Cross-session learning**: Later consultations benefit from previous research and decisions

### 🤖 **5 Specialized AI Experts**
- **Advocate**: Champions ideas with conviction and evidence
- **Critic**: Rigorous quality assurance and risk analysis  
- **Pragmatist**: Practical implementation focus
- **Research Specialist**: Fact-finding and evidence gathering
- **Innovator**: Creative disruption and breakthrough solutions

### 🌐 **Real-Time Web Research**
- **Tavily-powered search**: Real-time internet research with AI-optimized results
- **Automatic research synthesis**: Converts raw web data into actionable insights
- **Source credibility tracking**: Maintains confidence levels and source reliability
- **Knowledge gap detection**: Identifies what information is missing and researches it

### 🔄 **Intelligent Decision Framework**  
- **ASK_QUESTION**: Request user-specific context that can't be researched online
- **REQUEST_TEST**: Perform comprehensive web research to fill knowledge gaps
- **PROVIDE_SOLUTION**: Deliver research-backed, context-aware recommendations

### 🎯 **Built for Decision-Makers**
- **Interactive consultations**: Guided conversations that gather your specific context
- **Research-backed recommendations**: Every decision supported by current data and best practices
- **Comprehensive analysis**: Multiple expert perspectives reduce blind spots and bias
- **Actionable outputs**: Specific next steps, implementation guidance, and success metrics

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/zbloss/agent-expert-panel.git
cd agent-expert-panel

# Install core dependencies (using uv - recommended)
uv sync --group dev --group test

# Or using pip
pip install -e ".[dev]"
```

### Environment Setup

```bash
# Required: OpenAI API key
export OPENAI_API_KEY="your-openai-api-key"

# Optional: Tavily API key for real-time web search (1,000 free searches/month)
export TAVILY_API_KEY="your-tavily-api-key"
```

Get your Tavily API key from [tavily.com](https://tavily.com) - free tier includes 1,000 searches per month.

### Basic Usage

#### Interactive Mode
```bash
# Run interactive CLI
agent-panel
```

#### Batch Mode
```bash
# Run a specific discussion
agent-panel discuss "Should we adopt microservices architecture?" --pattern round-robin --rounds 3

# List available agents
agent-panel list-agents

# Show specific agent details
agent-panel show-agent advocate

# Get quick consensus
agent-panel quick-consensus "What are our top 3 priorities?"
```

#### Virtual Expert Panel Mode (Microsoft MAI-DxO Inspired)
```bash
# Solve complex problems with AI-powered research
agent-panel virtual-solve "How can we improve customer retention?" --domain business

# Interactive problem-solving with web research
agent-panel virtual-solve "What are the best practices for cloud migration?" \
  --domain technology \
  --max-iterations 5 \
  --interactive \
  --memory
```

#### Programmatic Usage
```python
import asyncio
from agent_expert_panel.panel import ExpertPanel, DiscussionPattern

async def main():
    # Initialize the expert panel
    panel = ExpertPanel()

    # Run a discussion
    result = await panel.discuss(
        topic="How can we improve team productivity?",
        pattern=DiscussionPattern.ROUND_ROBIN,
        max_rounds=3
    )

    print(f"Recommendation: {result.final_recommendation}")

asyncio.run(main())
```

## 👥 Meet the Expert Panel

### 🥊 The Advocate
*Champions ideas with conviction and evidence*

The Advocate is a passionate expert who builds strong cases for promising positions. Armed with extensive factual evidence and compelling arguments, they excel at identifying opportunities, highlighting benefits, and motivating action. When the panel needs someone to push forward with confidence, The Advocate steps up with enthusiasm and conviction.

### 🔍 The Critic
*Rigorous quality assurance and risk analysis*

The Critic serves as the panel's quality assurance specialist, approaching every proposal with healthy skepticism. They excel at identifying potential flaws, hidden risks, and unintended consequences. The Critic asks the tough questions and ensures decisions are made with full awareness of potential downsides.

### ⚡ The Pragmatist
*Practical implementation focus*

The Pragmatist cuts through theoretical complexities to deliver actionable solutions that work in practice. They prioritize feasibility, cost-effectiveness, and simplicity, always asking "What can we actually accomplish?" The Pragmatist provides clear, practical roadmaps for moving from ideas to action.

### 📚 The Research Specialist
*Fact-finding and evidence gathering*

The Research Specialist brings deep domain knowledge, current data, and evidence-based insights to every discussion. They ensure all panel discussions are grounded in accurate, up-to-date information and can quickly dive deep into specific topics to uncover relevant details others might miss.

### 💡 The Innovator
*Creative disruption and breakthrough solutions*

The Innovator challenges conventional thinking and generates novel ideas others haven't considered. With a natural ability to connect disparate concepts and see opportunities where others see obstacles, they provide the creative spark needed for transformative solutions.

## 🔧 Usage Examples

### Example 1: Quick Decision Support
```python
panel = ExpertPanel()
consensus = await panel.quick_consensus(
    "What are the top 3 priorities for a startup's first year?"
)
print(consensus)
```

### Example 2: Technical Architecture Discussion
```python
result = await panel.discuss(
    topic="Should we migrate to microservices?",
    participants=["advocate", "critic", "pragmatist"],  # Focus on implementation
    max_rounds=2
)
```

### Example 3: Innovation Brainstorming
```python
result = await panel.discuss(
    topic="How can AI improve customer experience?",
    participants=["innovator", "research_specialist", "advocate"],
    pattern=DiscussionPattern.STRUCTURED_DEBATE
)
```

## 👥 Human Participation

**NEW!** The Expert Panel now supports human participation through AutoGen's `UserProxyAgent`. Join AI experts as an active participant in discussions!

### Interactive CLI with Human Participation
```bash
# Interactive mode will ask if you want to participate
agent-panel

# Batch mode with human participation
agent-panel discuss "Product roadmap planning" --pattern structured-debate --with-human
```

### Programmatic Human Participation
```python
import asyncio
from agent_expert_panel.panel import ExpertPanel, DiscussionPattern

async def main():
    panel = ExpertPanel()

    # Include human expert in the discussion
    result = await panel.discuss_with_human(
        topic="What are the key considerations for implementing AI in healthcare?",
        pattern=DiscussionPattern.ROUND_ROBIN,
        max_rounds=2,
        human_name="Healthcare Expert"
    )

    print(f"Final recommendation: {result.final_recommendation}")

asyncio.run(main())
```

### Custom Input Functions
```python
def custom_input_func(prompt: str) -> str:
    """Custom input function for specialized interfaces."""
    print(f"\n🤔 Your turn to contribute:")
    print(f"Context: {prompt}")
    user_input = input("Your expert input: ").strip()
    return user_input or "I'll pass on this round."

# Use with custom input handling
result = await panel.discuss_with_human(
    topic="How can we improve team productivity?",
    human_name="Team Lead",
    human_input_func=custom_input_func
)
```

### Features
- **Seamless Integration**: Humans participate alongside AI agents in any discussion pattern
- **Custom Input Functions**: Support for web interfaces, chatbots, and specialized input methods
- **Flexible Participation**: Choose which AI agents to include with human participants
- **Timeout Handling**: Built-in support for async input with cancellation tokens

For detailed documentation, see [Human Participation Guide](docs/HUMAN_PARTICIPATION.md).

## 🖥️ Modern CLI with Typer

The Agent Expert Panel features a modern, user-friendly CLI built with [Typer](https://typer.tiangolo.com/):

### Rich Command Interface
```bash
# Beautiful help with emojis and colors
agent-panel --help

# Multiple specialized commands
agent-panel discuss "Your topic"           # Run discussions
agent-panel list-agents                    # Show available experts
agent-panel show-agent advocate            # Agent details
agent-panel quick-consensus "Question?"    # Rapid decisions
```

### Advanced Features
- 🎨 **Rich Output**: Colorful, formatted output with progress indicators
- ✅ **Type Validation**: Automatic validation of arguments and options
- 🔧 **Tab Completion**: Auto-completion support for commands and options
- 📋 **Multiple Commands**: Organized subcommands for different operations
- 🚀 **CI/CD Ready**: Perfect for automation and scripting

For complete CLI documentation, see [Typer CLI Guide](docs/TYPER_CLI.md).

## ⚙️ Configuration

Agents are configured via YAML files in the `configs/` directory:

```yaml
# configs/advocate.yaml
name: "advocate"
model_name: "qwen3:4b"
openai_base_url: "http://localhost:11434/v1"
openai_api_key: ""
timeout: 30.0
description: "A passionate expert who champions ideas with conviction"
system_message: |
  You are The Advocate, a passionate and confident expert...
model_info:
  vision: false
  function_calling: true
  json_output: true
```

### Custom Model Support

The framework supports any OpenAI-compatible API:
- **Local models**: Ollama, LocalAI, LM Studio
- **Cloud providers**: OpenAI, Anthropic, Google, etc.
- **Custom endpoints**: Any OpenAI-compatible service

## 🎨 CLI Reference

```bash
agent-panel --help

Usage: agent-panel [OPTIONS]

Options:
  -t, --topic TEXT        Topic for discussion
  -p, --pattern TEXT      Discussion pattern (round_robin, structured_debate)
  -r, --rounds INTEGER    Maximum discussion rounds (default: 3)
  -c, --config-dir PATH   Custom config directory
  -v, --verbose           Enable verbose logging
  --help                  Show this message and exit
```

## 📚 Advanced Usage

### Custom Discussion Patterns

```python
class ExpertPanel:
    async def discuss(
        self,
        topic: str,
        pattern: DiscussionPattern = DiscussionPattern.ROUND_ROBIN,
        max_rounds: int = 3,
        participants: Optional[List[str]] = None,
        with_human: bool = False  # Include human in discussion
    ) -> PanelResult:
```

### Available Patterns
- **Round Robin**: Each agent contributes in sequence
- **Structured Debate**: Formal debate with phases
- **Open Floor**: (Coming soon) Agents speak when they have input

### Export Results

Discussion results can be accessed programmatically:

```python
result = await panel.discuss(topic="...")

# Access detailed results
print(f"Topic: {result.topic}")
print(f"Consensus: {result.consensus_reached}")
print(f"Participants: {result.agents_participated}")
print(f"History: {result.discussion_history}")
```

## 🧪 Development

### Running Examples

```bash
# Simple discussion example
python examples/simple_discussion.py

# Custom agent configuration example
python examples/custom_agents.py
```

### Testing

```bash
# Run tests
pytest tests

```

### Adding Custom Agents

1. Create a new YAML config in `configs/`
2. Update `ExpertPanel._load_agents()` to include your agent
3. Customize the system message and model parameters

## 🔬 Research Foundation

This framework is inspired by cutting-edge research in multi-agent AI:

- **Microsoft's MAI-DxO**: [The Path to Medical Superintelligence](https://microsoft.ai/new/the-path-to-medical-superintelligence/)
- **Hugging Face Consilium**: [Multi-LLM Collaboration](https://huggingface.co/blog/consilium-multi-llm)
- **Multi-Agent Debate Research**: Encouraging diverse reasoning through structured agent interaction

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Areas for Contribution
- Additional discussion patterns
- New agent personalities
- Integration with more LLM providers
- Enhanced result export formats
- Performance optimizations

## 🙏 Acknowledgments

- Microsoft Research for MAI-DxO inspiration
- Hugging Face for Consilium multi-LLM concepts
- AutoGen team for the excellent agent framework
- The open-source AI community for continued innovation

---

**Ready to harness the power of collaborative AI?** Start your first expert panel discussion today! 🚀

