python-sdk/examples/parallel_ai_doc_editing.py

#!/usr/bin/env python3
"""
Parallel AI Documentation Editing using Hanzo-MCP Batch Tool

This demonstrates how to edit multiple AI documentation files in parallel
using the batch tool to delegate to different CLI agents (claude, codex, gemini, grok).
"""

import json
from typing import Any, Dict, List

# Example of how to use hanzo-mcp batch tool for parallel edits
# In practice, this would be called through the MCP interface


def create_parallel_edit_batch():
    """
    Create batch invocations for parallel document editing.
    Each agent works on a different file simultaneously.
    """

    batch_invocations = [
        {
            "tool_name": "claude",
            "input": {
                "prompt": """
                Read and enhance CLAUDE.md with:
                1. Add section on Claude's computer use capabilities
                2. Include Claude's vision capabilities for code screenshots
                3. Add patterns for using Claude's analysis tools
                4. Include Claude 3.5 Sonnet's latest improvements
                5. Add section on prompt caching for cost optimization
                
                Return the complete enhanced content maintaining all existing sections.
                Focus on Claude-specific strengths and unique features.
                """
            },
        },
        {
            "tool_name": "codex",
            "input": {
                "prompt": """
                Read and enhance LLM.md with:
                1. Add section on OpenAI's latest GPT-4 Turbo capabilities
                2. Include advanced function calling patterns
                3. Add OpenAI's Assistants API integration
                4. Include batch API usage for cost optimization
                5. Add fine-tuning patterns for custom models
                
                Return the complete enhanced content maintaining all existing sections.
                Focus on OpenAI-specific optimizations and features.
                """
            },
        },
        {
            "tool_name": "gemini",
            "input": {
                "prompt": """
                Read and enhance GEMINI.md with:
                1. Add section on Gemini's latest 1.5 Flash improvements
                2. Include Gemini Code capabilities
                3. Add patterns for Gemini's grounding with Google Search
                4. Include Gemini's extensions and plugins
                5. Add section on Gemini Advanced features
                
                Return the complete enhanced content maintaining all existing sections.
                Focus on Google-specific integrations and multimodal strengths.
                """
            },
        },
        {
            "tool_name": "grok",
            "input": {
                "prompt": """
                Create a new GROK.md file with:
                1. Grok model family overview (Grok-1, Grok-2)
                2. Real-time information access patterns
                3. X (Twitter) integration capabilities
                4. Code generation optimizations
                5. Humor and personality in responses
                6. Integration with xAI ecosystem
                7. Best practices for Grok usage
                
                Follow the same structure as other AI doc files.
                Include code examples and practical patterns.
                """
            },
        },
    ]

    return batch_invocations


def create_agent_editing_batch():
    """
    Create batch for editing AGENTS.md using multiple agents.
    Each agent enhances a different section.
    """

    batch_invocations = [
        {
            "tool_name": "claude",
            "input": {
                "prompt": """
                Enhance the 'Agent Communication Protocols' section in AGENTS.md:
                - Add WebSocket-based real-time communication
                - Include event-driven messaging patterns
                - Add distributed consensus protocols
                - Include agent negotiation strategies
                Write only the enhanced section content.
                """
            },
        },
        {
            "tool_name": "codex",
            "input": {
                "prompt": """
                Enhance the 'Git Worktree Management' section in AGENTS.md:
                - Add automated merge conflict resolution
                - Include CI/CD integration patterns
                - Add branch protection strategies
                - Include automated PR generation
                Write only the enhanced section content.
                """
            },
        },
        {
            "tool_name": "gemini",
            "input": {
                "prompt": """
                Enhance the 'Swarm Coordination Patterns' section in AGENTS.md:
                - Add emergent behavior patterns
                - Include load balancing strategies
                - Add fault tolerance mechanisms
                - Include performance optimization
                Write only the enhanced section content.
                """
            },
        },
    ]

    return batch_invocations


def create_review_and_merge_batch(edited_content: Dict[str, str]):
    """
    Create batch for reviewing and merging edits using consensus.
    Multiple agents review each other's work.
    """

    batch_invocations = [
        {
            "tool_name": "claude",
            "input": {
                "prompt": f"""
                Review the Codex edits to LLM.md:
                {edited_content.get("llm_edits", "")}
                
                Check for:
                1. Technical accuracy
                2. Consistency with existing content
                3. Code example correctness
                4. Best practices alignment
                
                Provide feedback and improved version if needed.
                """
            },
        },
        {
            "tool_name": "codex",
            "input": {
                "prompt": f"""
                Review the Claude edits to CLAUDE.md:
                {edited_content.get("claude_edits", "")}
                
                Check for:
                1. Implementation feasibility
                2. Performance implications
                3. Security considerations
                4. Integration complexity
                
                Provide feedback and improved version if needed.
                """
            },
        },
        {
            "tool_name": "gemini",
            "input": {
                "prompt": f"""
                Review all edits and create integration tests:
                
                Files edited:
                - LLM.md (by Codex)
                - CLAUDE.md (by Claude)
                - GEMINI.md (by Gemini)
                - AGENTS.md (by multiple)
                
                Generate:
                1. Cross-reference validation
                2. Consistency checks
                3. Integration test cases
                4. Documentation validation script
                """
            },
        },
    ]

    return batch_invocations


class ParallelDocumentEditor:
    """
    Orchestrates parallel editing of documentation using multiple AI agents.
    """

    def __init__(self):
        self.agents = ["claude", "codex", "gemini", "grok"]
        self.files = ["LLM.md", "AGENTS.md", "GEMINI.md", "CLAUDE.md"]

    async def execute_parallel_edits(self):
        """
        Execute parallel edits using batch tool.
        """

        # Phase 1: Initial parallel edits
        print("🚀 Phase 1: Initiating parallel edits...")
        initial_batch = create_parallel_edit_batch()

        # This would be executed as:
        # results = await batch(
        #     description="Edit AI documentation files",
        #     invocations=initial_batch
        # )

        # Simulated results for demonstration
        results_phase1 = {
            "claude": "Enhanced CLAUDE.md content...",
            "codex": "Enhanced LLM.md content...",
            "gemini": "Enhanced GEMINI.md content...",
            "grok": "New GROK.md content...",
        }

        print("✅ Phase 1 complete: All files edited in parallel")

        # Phase 2: Parallel section enhancements
        print("\n🚀 Phase 2: Enhancing specific sections...")
        section_batch = create_agent_editing_batch()

        # results = await batch(
        #     description="Enhance AGENTS.md sections",
        #     invocations=section_batch
        # )

        results_phase2 = {
            "communication": "Enhanced communication section...",
            "worktree": "Enhanced worktree section...",
            "swarm": "Enhanced swarm section...",
        }

        print("✅ Phase 2 complete: Sections enhanced")

        # Phase 3: Cross-review and validation
        print("\n🚀 Phase 3: Cross-reviewing edits...")
        review_batch = create_review_and_merge_batch(results_phase1)

        # results = await batch(
        #     description="Review and validate edits",
        #     invocations=review_batch
        # )

        print("✅ Phase 3 complete: All edits reviewed and validated")

        return {"phase1": results_phase1, "phase2": results_phase2, "status": "completed"}

    async def apply_edits_in_parallel(self, edits: Dict[str, str]):
        """
        Apply validated edits to files in parallel.
        """

        write_batch = [
            {"tool_name": "write", "input": {"file_path": f"/Users/z/work/hanzo/python-sdk/{file}", "content": content}}
            for file, content in edits.items()
        ]

        # Execute all writes in parallel
        # results = await batch(
        #     description="Write updated documentation",
        #     invocations=write_batch
        # )

        print("✅ All files updated in parallel")


# Practical example of batch execution in MCP context
BATCH_EXAMPLE = """
# In Claude Desktop or hanzo-mcp CLI, you would execute:

batch --description "Edit AI docs in parallel" --invocations '[
  {
    "tool_name": "claude",
    "input": {
      "prompt": "Enhance CLAUDE.md with latest features"
    }
  },
  {
    "tool_name": "codex", 
    "input": {
      "prompt": "Enhance LLM.md with OpenAI patterns"
    }
  },
  {
    "tool_name": "gemini",
    "input": {
      "prompt": "Enhance GEMINI.md with multimodal examples"
    }
  },
  {
    "tool_name": "grok",
    "input": {
      "prompt": "Create GROK.md documentation"
    }
  }
]'
"""


def demonstrate_batch_patterns():
    """
    Demonstrate various batch execution patterns.
    """

    print("=" * 60)
    print("PARALLEL AI DOCUMENTATION EDITING PATTERNS")
    print("=" * 60)

    # Pattern 1: Parallel file editing
    print("\n📝 Pattern 1: Parallel File Editing")
    print("-" * 40)

    parallel_edit = {
        "description": "Edit 4 files simultaneously",
        "invocations": [
            {"tool": "claude", "target": "CLAUDE.md"},
            {"tool": "codex", "target": "LLM.md"},
            {"tool": "gemini", "target": "GEMINI.md"},
            {"tool": "grok", "target": "AGENTS.md"},
        ],
    }

    print(json.dumps(parallel_edit, indent=2))

    # Pattern 2: Sequential with parallel stages
    print("\n📝 Pattern 2: Sequential Stages with Parallel Tasks")
    print("-" * 40)

    staged_execution = {
        "stage1": {
            "description": "Analyze all files in parallel",
            "parallel": True,
            "tasks": ["analyze_claude.md", "analyze_llm.md", "analyze_agents.md"],
        },
        "stage2": {
            "description": "Edit based on analysis",
            "parallel": True,
            "tasks": ["edit_claude.md", "edit_llm.md", "edit_agents.md"],
        },
        "stage3": {"description": "Review all edits", "parallel": False, "tasks": ["consensus_review"]},
    }

    print(json.dumps(staged_execution, indent=2))

    # Pattern 3: Divide and conquer
    print("\n📝 Pattern 3: Divide and Conquer")
    print("-" * 40)

    divide_conquer = {
        "description": "Each agent handles specific sections",
        "file": "AGENTS.md",
        "parallel_sections": [
            {"agent": "claude", "section": "Communication Protocols", "expertise": "System design"},
            {"agent": "codex", "section": "Code Generation", "expertise": "Implementation"},
            {"agent": "gemini", "section": "Testing Strategies", "expertise": "Quality assurance"},
        ],
    }

    print(json.dumps(divide_conquer, indent=2))

    # Pattern 4: Consensus editing
    print("\n📝 Pattern 4: Consensus-Based Editing")
    print("-" * 40)

    consensus_edit = {
        "description": "Multiple agents edit same content",
        "target": "architecture.md",
        "agents": ["claude", "codex", "gemini"],
        "strategy": "Each agent provides version, then consensus",
        "final_review": "grok",
    }

    print(json.dumps(consensus_edit, indent=2))


if __name__ == "__main__":
    import asyncio

    # Demonstrate patterns
    demonstrate_batch_patterns()

    # Example execution (would be async in practice)
    print("\n" + "=" * 60)
    print("EXAMPLE PARALLEL EXECUTION")
    print("=" * 60)

    editor = ParallelDocumentEditor()

    # In practice, this would be:
    # asyncio.run(editor.execute_parallel_edits())

    print("\n✨ Parallel editing demonstration complete!")

    print("\n" + "=" * 60)
    print("BATCH TOOL USAGE IN MCP")
    print("=" * 60)
    print(BATCH_EXAMPLE)