ComputerAssignments/CA14_multi_agent_reasoning/README.md

CA14: Multi-Agent Reasoning Systems

📚 Overview

This project implements advanced multi-agent reasoning systems that combine multiple AI agents to solve complex problems through collaboration, coordination, and hierarchical planning. The system integrates state-of-the-art techniques including ReAct agents, collaborative reasoning with Analysis of Competing Hypotheses (ACH), meta-thinking, and multi-agent orchestration.

🎯 Key Concepts

1. ReAct Agents (Reasoning + Acting)

• Combines reasoning (thinking) with acting (tool use)
• Iterative thought-action-observation loop
• Self-correcting behavior through reflection
• Tool-augmented problem solving

2. Collaborative Reasoning with ACH

• Analysis of Competing Hypotheses framework
• Evidence-based decision making
• Multi-perspective analysis
• Systematic bias mitigation

3. Meta-Thinking Agents

• Hierarchical reasoning (Strategic → Tactical → Operational)
• Adaptive planning and execution
• Meta-level monitoring and control
• Self-reflective problem solving

4. Multi-Agent Orchestration (Nexus)

• Supervisor-worker architecture
• Task decomposition and assignment
• Coordinated execution
• Result integration

📁 Project Structure

CA14_multi_agent_reasoning/
├── src/
│   ├── agents/
│   │   ├── react_agent.py                    # ReAct pattern implementation
│   │   ├── nexus_orchestrator.py             # Multi-agent orchestration
│   │   ├── collaborative_reasoning_agent.py  # ACH-based reasoning
│   │   ├── meta_thinking_agent.py            # Hierarchical meta-thinking
│   │   ├── planning_agent.py                 # Planning and scheduling
│   │   ├── reflexion_agent.py                # Self-reflective agents
│   │   ├── hipporag_agent.py                 # Memory-augmented reasoning
│   │   └── meta_learning_agent.py            # Meta-learning capabilities
│   ├── core/
│   │   ├── communication.py                  # Message broker and protocols
│   │   ├── memory.py                         # Working memory system
│   │   └── state_management.py               # Agent and task state
│   └── utils/
│       ├── llm_interface.py                  # LLM provider abstraction
│       ├── evaluation.py                     # Performance evaluation
│       └── environment.py                    # Environment utilities
├── demos/
│   ├── demo_all_agents.py                    # Demonstration of all agents
│   └── complete_multi_agent_project.py       # Comprehensive integration
├── notebooks/
│   ├── 01_Multi_Agent_Reasoning_Fundamentals.ipynb
│   ├── 02_Advanced_Collaborative_Reasoning.ipynb
│   ├── 03_Meta_Thinking_Agents.ipynb
│   └── 04_Complete_Multi_Agent_Project.ipynb
├── tests/
│   └── test_agents.py                        # Unit tests
├── docs/
│   └── architecture.md                       # System architecture
├── data/
│   └── execution_report.json                 # Execution logs
└── requirements.txt                          # Dependencies

🚀 Quick Start

Installation

# Clone the repository
cd CAs/CA14_multi_agent_reasoning

# Install dependencies
pip install -r requirements.txt

Basic Usage

1. ReAct Agent

from src.agents.react_agent import ReActAgent
from src.utils.llm_interface import LLMInterface

# Define tools
def search_web(query: str) -> str:
    return f"Search results for: {query}"

tools = {"search_web": search_web}

# Create agent
llm = LLMInterface(primary_provider="mock")
agent = ReActAgent(tools=tools, llm_interface=llm, max_steps=5)

# Execute task
result = agent.execute("Find information about AI safety")
print(f"Success: {result.success}")
print(f"Answer: {result.final_answer}")

2. Collaborative Reasoning

from src.agents.collaborative_reasoning_agent import (
    CollaborativeReasoningAgent, Hypothesis, Evidence
)

# Create agents
agent1 = CollaborativeReasoningAgent("analyst_1", "financial_analysis")
agent2 = CollaborativeReasoningAgent("analyst_2", "market_research")

# Add hypotheses
h1 = Hypothesis("H1", "Market will grow", prior_probability=0.6)
agent1.add_hypothesis(h1)
agent2.add_hypothesis(h1)

# Add evidence
e1 = Evidence("E1", "Strong demand signals",
              reliability=0.9, relevance=0.8, source="market_data")
agent1.add_evidence(e1)

# Analyze
result = agent1.analyze_competing_hypotheses()
print(f"Best hypothesis: {result['best_hypothesis']['description']}")

# Collaborate
collab_result = agent1.collaborate_with(agent2)
print(f"Joint confidence: {agent1.get_confidence():.2%}")

3. Meta-Thinking Agent

from src.agents.meta_thinking_agent import MetaThinkingAgent

# Create agent
agent = MetaThinkingAgent("meta_agent", "strategic_planning")

# Strategic planning
problem = "Launch new product in competitive market"
context = {"market_size": "large", "competition": "high"}

plan = agent.strategic_thinking(problem, context)
print(f"Strategy: {plan.strategy}")
print(f"Sub-goals: {plan.sub_goals}")

# Tactical execution
tactical_plan = agent.tactical_thinking(plan.sub_goals[0], context)
print(f"Tactical steps: {tactical_plan['tactical_steps']}")

# Monitor and adapt
monitoring = agent.monitor_and_adapt()
print(f"Success rate: {monitoring['progress']['success_rate']:.1%}")

4. Nexus Multi-Agent System

from src.agents.nexus_orchestrator import NexusMultiAgentSystem

# Create system with tools
nexus = NexusMultiAgentSystem(tools=tools)

# Execute complex task
result = nexus.execute_complex_task("Plan complete travel package to Paris")

print(f"Success: {result.success}")
print(f"Agents involved: {len(result.execution_results)}")
print(f"Final answer: {result.final_answer}")

📊 Running Demonstrations

Demo 1: All Agents Showcase

cd demos
python3 demo_all_agents.py

This demonstrates:

• Individual agent capabilities
• Communication protocols
• Memory systems
• Performance metrics

Demo 2: Complete Integration

cd demos
python3 complete_multi_agent_project.py

This runs three comprehensive scenarios:

1. Travel Planning: ReAct + Nexus coordination
2. Investment Decision: Collaborative reasoning with ACH
3. Product Launch: Hierarchical meta-thinking

📓 Jupyter Notebooks

Explore interactive tutorials in the notebooks/ directory:

1. 01_Multi_Agent_Reasoning_Fundamentals.ipynb

   • Message passing and communication
   • Working memory systems
   • ReAct agent basics
   • Nexus orchestration
   • Performance visualization

2. 02_Advanced_Collaborative_Reasoning.ipynb

   • Analysis of Competing Hypotheses (ACH)
   • Multi-agent collaboration
   • Evidence-based reasoning
   • Decision explanation

3. 03_Meta_Thinking_Agents.ipynb

   • Strategic planning
   • Tactical coordination
   • Operational execution
   • Adaptive monitoring

4. 04_Complete_Multi_Agent_Project.ipynb

   • End-to-end integration
   • Real-world scenarios
   • Performance analysis
   • Best practices

🧪 Testing

Run the test suite:

cd tests
python3 test_agents.py

🏗️ Architecture

Communication Layer

• MessageBroker: Asynchronous message passing
• CommunicationProtocol: Agent-to-agent communication
• Message Types: Task requests, responses, status updates, coordination

Memory System

• WorkingMemory: Short-term context storage
• Episodic Memory: Experience replay
• Semantic Memory: Knowledge representation

Agent Types

ReAct Agent

Input → Thought → Action → Observation → Thought → ... → Final Answer

Collaborative Agent

Hypotheses + Evidence → Evaluation Matrix → Ranking → Decision + Explanation

Meta-Thinking Agent

Strategic (What/Why) → Tactical (How/When) → Operational (Execute) → Monitor → Adapt

Nexus System

Supervisor: Task Analysis → Agent Assignment → Coordination
Workers: Specialized Execution
Supervisor: Result Integration → Final Output

🔧 Configuration

LLM Providers

The system supports multiple LLM providers:

from src.utils.llm_interface import LLMInterface

# OpenAI
llm = LLMInterface(primary_provider="openai", config={
    "openai": {"model": "gpt-4", "api_key": "your-key"}
})

# Anthropic
llm = LLMInterface(primary_provider="anthropic", config={
    "anthropic": {"model": "claude-3-sonnet-20240229", "api_key": "your-key"}
})

# Local models
llm = LLMInterface(primary_provider="local", config={
    "local": {"model_name": "gpt2", "device": "cuda"}
})

# Mock (for testing)
llm = LLMInterface(primary_provider="mock")

Agent Configuration

# ReAct Agent
agent = ReActAgent(
    tools=tools,
    llm_interface=llm,
    max_steps=10,
    agent_id="custom_agent"
)

# Update configuration
agent.update_config({
    "temperature": 0.5,
    "max_tokens": 300,
    "enable_self_correction": True,
    "confidence_threshold": 0.8
})

📈 Performance Metrics

The system tracks comprehensive metrics:

# Get agent performance stats
stats = agent.get_performance_stats()

print(f"Total executions: {stats['total_executions']}")
print(f"Success rate: {stats['success_rate']:.2%}")
print(f"Avg execution time: {stats['avg_execution_time']:.2f}s")
print(f"Avg reasoning quality: {stats['avg_reasoning_quality']:.2%}")
print(f"Most used tools: {stats['most_used_tools']}")

🌟 Advanced Features

1. Self-Correction

Agents can detect and correct their own mistakes through reflection.

2. Adaptive Planning

Meta-agents adjust strategies based on execution feedback.

3. Parallel Execution

Nexus system can coordinate parallel agent execution.

4. Evidence Weighting

Collaborative agents weight evidence by reliability and relevance.

5. Explanation Generation

All agents can explain their reasoning in natural language.

🔬 Research Papers

This implementation is based on:

1. ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al., 2023)
2. Analysis of Competing Hypotheses (Heuer, 1999)
3. Meta-Thinking for LLMs (Recent research on hierarchical reasoning)
4. Multi-Agent Systems: Coordination and cooperation frameworks

📚 Key Concepts Explained

Analysis of Competing Hypotheses (ACH)

ACH is a structured analytical technique that:

• Identifies alternative hypotheses
• Evaluates evidence against each hypothesis
• Systematically reduces cognitive biases
• Provides transparent decision-making

ReAct Pattern

The ReAct pattern alternates between:

• Reasoning: Thinking about what to do next
• Acting: Using tools to gather information
• Observing: Processing tool outputs
• Iterating: Continuing until task completion

Hierarchical Reasoning

Meta-thinking separates concerns across levels:

• Strategic: High-level goals and strategies
• Tactical: Resource allocation and coordination
• Operational: Specific task execution

🎓 Learning Path

1. Beginner: Start with 01_Multi_Agent_Reasoning_Fundamentals.ipynb
2. Intermediate: Explore 02_Advanced_Collaborative_Reasoning.ipynb
3. Advanced: Study 03_Meta_Thinking_Agents.ipynb
4. Expert: Build with 04_Complete_Multi_Agent_Project.ipynb

🤝 Contributing

Contributions are welcome! Areas for improvement:

• Additional agent architectures
• More sophisticated planning algorithms
• Enhanced communication protocols
• Better evaluation metrics
• Real-world case studies

📝 License

This project is part of the System2_in_AI course materials.

🔗 Related Projects

• CA11: Chain of Thought Reasoning
• CA12: Tree of Thoughts
• CA13: Game of 24 (Multi-agent competition)
• CA24: Multi-Agent Systems (General framework)

📧 Contact

For questions or feedback about this project, please refer to the course materials or documentation.

---

🎯 Example Use Cases

1. Research Analysis

Multiple agents with different expertise collaborate to analyze research papers and generate insights.

2. Investment Decision

Financial, market, and risk analysts work together using ACH to make informed investment decisions.

3. Product Development

Strategic planning agent decomposes product launch into tactical and operational tasks.

4. Travel Planning

Specialized agents coordinate to plan flights, hotels, and activities for complex trips.

5. Problem Solving

ReAct agents use tools and reasoning to solve complex, multi-step problems.

🚀 Future Enhancements

• Reinforcement learning for agent improvement
• Distributed multi-agent execution
• Advanced memory architectures
• Real-time collaboration interfaces
• Integration with external APIs
• Visualization dashboard
• Performance benchmarking suite

---

Note: This project demonstrates advanced AI reasoning techniques and is intended for educational purposes. For production use, additional error handling, security measures, and optimization would be required.