Skip to content

Python SDK for AI agent monitoring, LLM cost tracking, benchmarking, and more. Integrates with most LLMs and agent frameworks including CrewAI, Agno, OpenAI Agents SDK, Langchain, Autogen, AG2, and CamelAI

6.3 KB
Raw Blame
#!/usr/bin/env python3
"""
Script to generate example MDX files from Jupyter notebooks.

This script converts a Jupyter notebook from the examples/ directory into a
corresponding .mdx file in docs/v2/examples/, matching the exact format and
structure used by the GitHub Actions workflow.

Usage:
    python examples/generate_documentation.py examples/openai/openai_example_sync.ipynb
"""

import argparse
import re
import subprocess
import sys
from pathlib import Path

# Constants
SCRIPT_TAGS = """<script type="module" src="/scripts/github_stars.js"></script>
<script type="module" src="/scripts/scroll-img-fadein-animation.js"></script>
<script type="module" src="/scripts/button_heartbeat_animation.js"></script>
<script type="module" src="/scripts/adjust_api_dynamically.js"></script>"""

# Title overrides to reflect correct names
TITLE_OVERRIDES = {
    "ag2": "AG2",
    "autogen": "AutoGen",
    "crewai": "CrewAI",
    "google_adk": "Google ADK",
    "google_genai": "Google GenAI",
    "langchain": "LangChain",
    "litellm": "LiteLLM",
    "llamaindex": "LlamaIndex",
    "openai": "OpenAI",
    "openai_agents": "OpenAI Agents",
    "watsonx": "WatsonX",
    "xai": "xAI",
}


def convert_notebook_to_markdown(notebook_path):
    """Convert Jupyter notebook to markdown using jupyter nbconvert."""
    try:
        result = subprocess.run(
            ["jupyter", "nbconvert", "--to", "markdown", "--stdout", notebook_path],
            capture_output=True,
            text=True,
            check=True,
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        sys.exit(f"Error: Failed to convert notebook: {e}\nstderr: {e.stderr}")
    except FileNotFoundError:
        sys.exit("Error: jupyter nbconvert not found. Please install jupyter: pip install jupyter")


def process_pip_installations(markdown_content):
    """Transform %pip install commands using regex for efficiency."""
    # Extract all packages from pip install commands
    packages = []
    for match in re.finditer(r"%pip install\s+([^\n#]+)", markdown_content):
        packages.extend(match.group(1).strip().split())

    if not packages:
        return markdown_content

    # Deduplicate packages
    unique_packages = " ".join(sorted(set(packages)))

    # Remove code blocks containing pip installs
    content = re.sub(r"```python\n(?:[^`])*?%pip install[^\n]*\n(?:[^`])*?```\n?", "", markdown_content)

    # Find insertion point for installation section
    first_pip_pos = markdown_content.find("%pip install")
    if first_pip_pos == -1:
        return markdown_content

    # Calculate line position and insert installation section
    line_pos = markdown_content[:first_pip_pos].count("\n")
    lines = content.split("\n")

    installation_section = f"""## Installation
<CodeGroup>
  ```bash pip
  pip install {unique_packages}
  ```
  ```bash poetry
  poetry add {unique_packages}
  ```
  ```bash uv
  uv add {unique_packages}
  ```
</CodeGroup>
"""

    lines.insert(line_pos, installation_section)
    return "\n".join(lines)


def get_existing_frontmatter(mdx_path):
    """Extract existing frontmatter if it has special configurations."""
    if not mdx_path.exists():
        return None

    content = mdx_path.read_text(encoding="utf-8")

    # Check for special configurations and extract frontmatter
    if any(config in content for config in ["mode:", "layout:"]):
        if content.startswith("---\n"):
            end_marker = content.find("\n---\n", 4)
            if end_marker != -1:
                return content[4:end_marker]

    return None


def generate_mdx_content(notebook_path, processed_content, frontmatter=None):
    """Generate MDX content with either provided or generated frontmatter."""
    if not frontmatter:
        # Generate new frontmatter
        folder_name = Path(notebook_path).parent.name

        # Check for title override, otherwise use default title case conversion
        if folder_name in TITLE_OVERRIDES:
            base_title = TITLE_OVERRIDES[folder_name]
        else:
            base_title = folder_name.replace("_", " ").title()

        title = f"{base_title}"

        # Extract description from first heading or use default
        description = f"{title} example using AgentOps"
        for line in processed_content.split("\n"):
            if line.startswith("# ") and len(line) > 2:
                description = line[2:].strip()
                break

        frontmatter = f"title: '{title}'\ndescription: '{description}'"

    return f"""---
{frontmatter}
---
{{/*  SOURCE_FILE: {notebook_path}  */}}

_View Notebook on <a href={{'https://github.com/AgentOps-AI/agentops/blob/main/{notebook_path}'}} target={{'_blank'}}>Github</a>_

{processed_content}

{SCRIPT_TAGS}"""


def main():
    parser = argparse.ArgumentParser(description="Generate example MDX files from Jupyter notebooks")
    parser.add_argument("notebook_path", help="Path to the Jupyter notebook")

    notebook_path = parser.parse_args().notebook_path

    # Validate notebook path
    notebook_file = Path(notebook_path)
    if not notebook_file.exists():
        sys.exit(f"Error: Notebook file not found: {notebook_path}")

    if notebook_file.suffix != ".ipynb":
        sys.exit(f"Error: File must be a Jupyter notebook (.ipynb): {notebook_path}")

    if not str(notebook_file).startswith("examples/"):
        sys.exit(f"Error: Notebook must be in the examples/ directory: {notebook_path}")

    # Generate output path
    folder_name = notebook_file.parent.name
    output_path = Path(f"docs/v2/examples/{folder_name}.mdx")

    print(f"Processing: {notebook_path} -> {output_path}")

    # Convert notebook to markdown and process
    markdown_content = convert_notebook_to_markdown(notebook_path)
    processed_content = process_pip_installations(markdown_content)

    # Check for existing special frontmatter
    existing_frontmatter = get_existing_frontmatter(output_path)

    if existing_frontmatter:
        final_content = generate_mdx_content(notebook_path, processed_content, existing_frontmatter)
    else:
        print("Generating new frontmatter and content")
        final_content = generate_mdx_content(notebook_path, processed_content)

    # Write the file
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_text(final_content, encoding="utf-8")

    print(f"Successfully generated: {output_path}")


if __name__ == "__main__":
    main()