Multi-Agent Python Documentation System

A sophisticated documentation system that uses specialized AI agents to automatically generate, review, and insert high-quality docstrings into Python codebases.

📋 Table of Contents

• Project Overview
• Key Features
• Project Structure
• System Architecture
• Installation
• Usage
• Demo
• Technologies Used
• Testing
• Contributing
• License

🔍 Project Overview

This project is a comprehensive Python documentation system developed in three progressive parts:

Part 1: Documentation Agent with LlamaIndex

The foundation of the system, integrating documentation tools with LlamaIndex to create an agent that can help with Python code documentation tasks:

• Code parsing to extract function and class definitions
• Docstring generation using Google style format
• Docstring analysis to check completeness and identify issues
• Interactive agent for natural language documentation queries

Part 2: Web Browsing Integration

Extends the documentation assistant with web browsing capabilities:

• Web browsing capabilities using Playwright
• Searching documentation standards (e.g., Google Python Style Guide)
• Looking up library documentation online
• Improving docstrings based on best practices found on the web

Part 3: Multi-Agent Architecture

The complete system with a sophisticated multi-agent architecture:

• Coordinator Agent orchestrates the workflow between specialized agents
• Code Analyzer Agent analyzes code structure and detects undocumented elements
• Docstring Generator Agent creates appropriate docstrings for code elements
• Documentation Reviewer Agent reviews and improves generated docstrings
• File Tools for reading, writing, and manipulating Python files
• Configuration System for customizable documentation settings

✨ Key Features

• Automated Documentation: Automatically generate high-quality docstrings for Python code
• Multi-Agent Architecture: Specialized agents working together for optimal results
• Customizable Docstring Styles: Support for Google, NumPy, and Sphinx docstring formats
• Intelligent Code Analysis: Understands code structure and relationships
• Quality Assurance: Reviews and improves generated docstrings
• Web Integration: References documentation standards and library documentation online
• Configurable Workflow: Customize the documentation process to fit your needs
• Comprehensive Reporting: Detailed reports on the documentation process

📁 Project Structure

project/
├── part1/                      # Basic documentation agent
│   ├── agent.py                # LlamaIndex agent integration
│   ├── code_parser.py          # Code parsing functionality
│   ├── docstring_analyzer.py   # Docstring analysis tools
│   ├── docstring_generator.py  # Docstring generation tools
│   ├── main.py                 # Simple demo without agent
│   └── README.md               # Part 1 documentation
│
├── part2/                      # Web-enhanced documentation agent
│   ├── playwright_agent.py     # Agent with web browsing capabilities
│   ├── workflow_example.py     # Example workflows
│   └── README.md               # Part 2 documentation
│
├── part3/                      # Multi-agent documentation system
│   ├── code_analyzer_agent.py  # Code analysis agent
│   ├── coordinator_agent.py    # Workflow coordination agent
│   ├── docstring_generator_agent.py # Docstring generation agent
│   ├── doc_reviewer_agent.py   # Documentation review agent
│   ├── file_tools.py           # File manipulation utilities
│   ├── main.py                 # Main entry point
│   ├── multi_agent_manager.py  # Agent management system
│   └── README.md               # Part 3 documentation
│
├── tests/                      # Test suite
│   └── tests/                  # Test files
│       ├── test_code_analyzer.py
│       ├── test_docstring_generator.py
│       ├── test_docstring_inserter.py
│       ├── test_end_to_end.py
│       └── test_file_tools.py
│
└── servers/                    # MCP server implementations
    └── README.md               # Servers documentation

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────┐
│                DocumentationAgentManager                     │
│                                                             │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐  │
│  │ Coordinator │   │    Code     │   │  Docstring  │   │ Documentation│  │
│  │    Agent    │<->│  Analyzer   │<->│  Generator  │<->│   Reviewer   │  │
│  │             │   │    Agent    │   │    Agent    │   │     Agent    │  │
│  └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
           │                  │                  │
           ▼                  ▼                  ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │  Python     │    │  Generated  │    │  Documented  │
    │  Codebase   │ -> │  Docstrings │ -> │  Codebase    │
    └─────────────┘    └─────────────┘    └─────────────┘

🔧 Installation

Prerequisites

• Python 3.8 or higher
• OpenAI API key

Installation Steps

1. Clone the repository:

   git clone https://github.com/yourusername/python-documentation-system.git
   cd python-documentation-system

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install the required dependencies:

   # For basic documentation agent (Part 1)
   pip install -r part1/requirements.txt
   
   # For web-enhanced agent (Part 2)
   pip install -r part2/playwright_requirements.txt
   python -m playwright install
   
   # For multi-agent system (Part 3)
   pip install -r part3/requirements.txt

4. Set up your OpenAI API key:

   export OPENAI_API_KEY="your-api-key-here"
   # On Windows: set OPENAI_API_KEY=your-api-key-here

🚀 Usage

Basic Documentation Agent (Part 1)

Run the interactive agent:

cd part1
python agent.py

Example commands:

Document this function: def calculate_area(length, width): return length * width

Web-Enhanced Agent (Part 2)

Run the agent with web browsing capabilities:

cd part2
python playwright_agent.py

Example commands:

Look up Python docstring standards and tell me the recommended format

Multi-Agent System (Part 3)

Process a Python codebase:

cd part3
python main.py --directory path/to/your/python/code

Or use the Python API:

from multi_agent_manager import DocumentationAgentManager

# Initialize the documentation agent manager
manager = DocumentationAgentManager()

# Process a codebase
results = manager.process_codebase("path/to/your/python/code")

# Print a summary of the results
print(f"Files processed: {results['files_processed']}")
print(f"Files completed: {len(results['files_completed'])}")
print(f"Files with errors: {len(results['files_failed'])}")

🎮 Demo

A quick demo of the Multi-Agent Documentation System is available:

cd part3
./run_demo.sh

This will:

• Create a demo directory with a sample Python file
• Show the original undocumented code
• Run the documentation system on the file
• Show the newly documented code
• Explain the system architecture

💻 Technologies Used

• LlamaIndex: For agent framework and LLM integration
• OpenAI: For accessing language models
• Playwright: For web browsing capabilities
• astor & astunparse: For Python AST manipulation
• pytest: For testing
• pyyaml: For configuration file parsing

🧪 Testing

Run the test suite:

cd tests
pytest

Run specific tests:

# Run unit tests only
pytest -m unit

# Run a specific test file
pytest tests/test_code_analyzer.py

# Generate test coverage report
pytest --cov=. tests/

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.