Circle of Mages 🧙‍♂️

A multi-agent AI research system that leverages both PhD-level and Masters-level AI agents to conduct comprehensive industry surveys and synthesize findings into academic survey papers.

Overview

Circle of Mages is an intelligent research orchestration system that combines the depth of academic research with the breadth of industry analysis. The system employs multiple specialized AI agents working in collaboration to produce publication-ready survey papers with automatic PDF generation.

System Architecture

User Query → [PhD Agent + Masters Agent] → Synthesis Agent → PDF Survey Paper

The Circle of Mages consists of:

• PhD Agent (o3-deep-research): Advanced researcher for deep, comprehensive analysis
• Masters Agent (o4-mini-deep-research): Efficient researcher for broad coverage and rapid insights
• Synthesis Agent (o3): Combines findings into structured academic survey papers
• PDF Generator: Produces publication-ready documents

Features

• 🔬 Multi-Agent Research: Parallel research by PhD and Masters level agents
• 📚 Academic Rigor: PhD agent focuses on peer-reviewed research and technical depth
• 🎓 Industry Coverage: Masters agent provides broad market analysis and current trends
• ✍️ Automated Synthesis: Intelligent combination of findings into cohesive survey papers
• 📄 PDF Generation: Automatic creation of publication-ready documents
• 🌐 Web Search Integration: Real-time access to current information and sources
• 📊 Structured Output: Standardized academic paper format with proper citations

Quick Start

Prerequisites

• Python 3.12.3
• OpenAI API key with access to o3 and o4-mini-deep-research models

Installation

1. Clone the repository:

   git clone <repository-url>
   cd CircleOfMages

2. Install dependencies using uv (recommended) or pip:

   # Using uv (faster)
   uv sync
   
   # Or using pip
   pip install -r requirements.txt

3. Activate the virtual environment:

   # If using uv
   source .venv/bin/activate
   
   # Or if using pip/venv
   source venv/bin/activate

Usage

Option 1: Jupyter Notebook Interface

1. Start Jupyter:

   jupyter notebook

2. Open circle_of_magi.ipynb

3. Run the cells to initialize the system and conduct research:

   # Example research query
   result = await collaborative_deep_research(
       "Create a survey paper on the recent emergence of Context Engineering"
   )

Option 2: Direct API Usage

Open deep_research_api.ipynb for examples of using the research agents directly through the OpenAI API.

Project Structure

CircleOfMages/
├── circle_of_magi.ipynb          # Main research orchestration system
├── deep_research_api.ipynb       # Direct API usage examples
├── pyproject.toml                # Project configuration and dependencies
├── uv.lock                       # Dependency lock file
├── .python-version               # Python version specification
├── .venv/                        # Virtual environment
└── README.md                     # This file

Agent Specifications

PhD Agent (o3-deep-research)

• Focus: Academic depth and rigor
• Sources: Peer-reviewed research, academic publications, government reports
• Approach: Critical analysis, methodological evaluation, technical depth
• Output: Comprehensive analysis with proper citations and limitation acknowledgments

Masters Agent (o4-mini-deep-research)

• Focus: Industry breadth and current trends
• Sources: Industry news, market research, company reports, expert commentary
• Approach: Rapid synthesis, practical applications, stakeholder perspectives
• Output: Timely insights with market dynamics and real-world implementations

Synthesis Agent (o3)

• Focus: Academic paper creation
• Approach: Critical synthesis, gap identification, future directions
• Output: Publication-ready survey papers with proper academic structure

Output Format

Generated survey papers include:

• Abstract (150-250 words)
• Introduction with problem statement and scope
• Methodology explaining the survey approach
• Findings organized by themes/categories
• Discussion of implications and controversies
• Conclusions and future work recommendations
• References section with proper citations

Dependencies

• jupyter>=1.1.1 - Notebook interface
• openai>=1.88 - OpenAI API client
• openai-agents>=0.0.19 - OpenAI Agents framework
• reportlab>=4.4.2 - PDF generation
• markdown>=3.8.2 - Markdown processing

Configuration

The system supports Zero Data Retention (ZDR) for enterprise environments by setting:

os.environ["OPENAI_AGENTS_DISABLE_TRACING"] = "1"

Examples

Research Topics

• AI and Future of Work Economic Impact
• Context Engineering in Large Language Models
• Emerging Trends in Generative AI
• Industry-specific AI Applications
• Regulatory Landscape Analysis

Generated Files

• Survey papers are automatically saved as PDF files
• Filename format: circle_of_magi_{query}_{timestamp}.pdf
• Research session metadata is preserved for analysis

Contributing

This project is part of the AI Makerspace Events series. Contributions are welcome for:

• Additional agent configurations
• New research methodologies
• Enhanced PDF formatting
• Integration with additional data sources

License

[Add appropriate license information]

Acknowledgments

Built using the OpenAI Agents framework and powered by state-of-the-art language models including o3 and o4-mini-deep-research variants.

---

Circle of Mages: Where AI agents collaborate to advance human knowledge 🧙‍♂️✨