Gamma APIgamma.app ↗

"""
Gamma API Client via Parse.bot
AI-powered presentation generation with Gamma.app

Get your API key from: https://gamma.app/settings/api
"""

import os
import time
import requests
from typing import Optional, Any, Dict, List


class ParseClient:
    """Client for interacting with Gamma API through Parse.bot scraper."""

    def __init__(self, api_key: Optional[str] = None):
        """
        Initialize the Parse API client.
        
        Args:
            api_key: Parse API key. Defaults to PARSE_API_KEY environment variable.
        """
        self.base_url = "https://api.parse.bot"
        self.scraper_id = "e7bdebeb-3e3e-4708-a3b2-68d721909cd5"
        self.api_key = api_key or os.getenv("PARSE_API_KEY")
        
        if not self.api_key:
            raise ValueError("API key required. Set PARSE_API_KEY or pass api_key parameter.")

    def _call(self, endpoint: str, method: str = "POST", **params) -> Dict[str, Any]:
        """
        Make a request to the Parse API endpoint.
        
        Args:
            endpoint: The endpoint name (e.g., 'generate_content')
            method: HTTP method ('GET' or 'POST')
            **params: Query/body parameters
            
        Returns:
            Response JSON as dictionary
        """
        url = f"{self.base_url}/scraper/{self.scraper_id}/{endpoint}"
        headers = {
            "X-API-Key": self.api_key,
            "Content-Type": "application/json"
        }
        
        if method.upper() == "GET":
            response = requests.get(url, headers=headers, params=params)
        elif method.upper() == "POST":
            response = requests.post(url, headers=headers, json=params)
        else:
            raise ValueError(f"Unsupported method: {method}")
        
        response.raise_for_status()
        return response.json()

    def generate_content(
        self,
        input_text: str,
        text_mode: str = "generate",
        format: Optional[str] = None,
        num_cards: Optional[int] = None,
        theme_id: Optional[str] = None,
        export_as: Optional[str] = None,
        additional_instructions: Optional[str] = None,
        image_options: Optional[Dict] = None,
        text_options: Optional[Dict] = None,
        card_options: Optional[Dict] = None,
        sharing_options: Optional[Dict] = None,
        folder_ids: Optional[str] = None,
        card_split: Optional[str] = None,
    ) -> str:
        """
        Generate a new AI-powered gamma (presentation, document, or webpage).
        
        Args:
            input_text: The content or topic to generate from
            text_mode: How to process input ('generate', 'condense', 'preserve')
            format: Type of content ('presentation', 'document', 'social', 'webpage')
            num_cards: Number of cards to generate
            theme_id: ID of the theme to apply
            export_as: Auto-export as 'pdf' or 'pptx'
            additional_instructions: Extra AI instructions
            image_options: JSON object for image settings
            text_options: JSON object for text settings
            card_options: JSON object for card settings
            sharing_options: JSON object for sharing settings
            folder_ids: Folder ID or comma-separated string
            card_split: How to split content into cards
            
        Returns:
            Generation ID string
        """
        params = {
            "input_text": input_text,
            "text_mode": text_mode,
            "api_key": self.api_key
        }
        
        if format:
            params["format"] = format
        if num_cards:
            params["numCards"] = num_cards
        if theme_id:
            params["themeId"] = theme_id
        if export_as:
            params["exportAs"] = export_as
        if additional_instructions:
            params["additionalInstructions"] = additional_instructions
        if image_options:
            params["imageOptions"] = image_options
        if text_options:
            params["textOptions"] = text_options
        if card_options:
            params["cardOptions"] = card_options
        if sharing_options:
            params["sharingOptions"] = sharing_options
        if folder_ids:
            params["folderIds"] = folder_ids
        if card_split:
            params["cardSplit"] = card_split
            
        response = self._call("generate_content", method="POST", **params)
        return response["data"]["id"]

    def get_generation_status(self, generation_id: str) -> Dict[str, Any]:
        """
        Poll the status of an async generation job.
        
        Args:
            generation_id: The ID of the generation to check
            
        Returns:
            Status response with 'status', 'gammaId', 'id'
        """
        params = {
            "generation_id": generation_id,
            "api_key": self.api_key
        }
        response = self._call("get_generation_status", method="GET", **params)
        return response["data"]

    def get_export_urls(self, generation_id: str) -> Dict[str, str]:
        """
        Retrieve PDF and PPTX export URLs for a generation.
        
        Args:
            generation_id: The ID of the generation
            
        Returns:
            Dictionary with 'pdfUrl' and 'pptxUrl' download URLs
        """
        params = {
            "generation_id": generation_id,
            "api_key": self.api_key
        }
        response = self._call("get_export_urls", method="GET", **params)
        return response["data"]

    def create_from_template(
        self,
        template_gamma_id: str,
        prompt: str,
        theme_id: Optional[str] = None,
        export_as: Optional[str] = None,
        image_options: Optional[Dict] = None,
        sharing_options: Optional[Dict] = None,
        folder_ids: Optional[str] = None,
    ) -> str:
        """
        Create a new gamma based on an existing template.
        
        Args:
            template_gamma_id: The ID of the template gamma to use
            prompt: Instructions for creating from the template
            theme_id: ID of the theme to apply
            export_as: Auto-export as 'pdf' or 'pptx'
            image_options: JSON object for image settings
            sharing_options: JSON object for sharing settings
            folder_ids: Folder ID or comma-separated string
            
        Returns:
            Generation ID string
        """
        params = {
            "template_gamma_id": template_gamma_id,
            "prompt": prompt,
            "api_key": self.api_key
        }
        
        if theme_id:
            params["themeId"] = theme_id
        if export_as:
            params["exportAs"] = export_as
        if image_options:
            params["imageOptions"] = image_options
        if sharing_options:
            params["sharingOptions"] = sharing_options
        if folder_ids:
            params["folderIds"] = folder_ids
            
        response = self._call("create_from_template", method="POST", **params)
        return response["data"]["id"]

    def list_themes(
        self,
        query: Optional[str] = None,
        limit: Optional[int] = None,
        after: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        List themes available in the workspace.
        
        Args:
            query: Search for themes by name
            limit: Max results to return
            after: Cursor token for pagination
            
        Returns:
            Dictionary with 'data', 'hasMore', and pagination info
        """
        params = {"api_key": self.api_key}
        
        if query:
            params["query"] = query
        if limit:
            params["limit"] = limit
        if after:
            params["after"] = after
            
        response = self._call("list_themes", method="GET", **params)
        return response["data"]

    def list_folders(
        self,
        query: Optional[str] = None,
        limit: Optional[int] = None,
        after: Optional[str] = None
    ) -> Dict[str, Any]:
        """
        List folders in the workspace.
        
        Args:
            query: Search for folders by name
            limit: Max results to return
            after: Cursor token for pagination
            
        Returns:
            Dictionary with 'data', 'hasMore', and pagination info
        """
        params = {"api_key": self.api_key}
        
        if query:
            params["query"] = query
        if limit:
            params["limit"] = limit
        if after:
            params["after"] = after
            
        response = self._call("list_folders", method="GET", **params)
        return response["data"]


def poll_until_complete(
    client: ParseClient,
    generation_id: str,
    max_wait_seconds: int = 600,
    poll_interval: int = 5
) -> Optional[Dict[str, Any]]:
    """
    Poll until a generation completes.
    
    Args:
        client: ParseClient instance
        generation_id: ID of the generation to monitor
        max_wait_seconds: Maximum time to wait in seconds
        poll_interval: Seconds between polls
        
    Returns:
        Final status response if completed, None if timeout
    """
    start_time = time.time()
    
    while time.time() - start_time < max_wait_seconds:
        status_data = client.get_generation_status(generation_id)
        status = status_data.get("status")
        
        if status == "completed":
            return status_data
        elif status == "failed":
            print(f"      ✗ Generation failed")
            return None
        
        print(f"      ⏳ Status: {status}")
        time.sleep(poll_interval)
    
    print(f"      ⚠ Timeout waiting for generation")
    return None


if __name__ == "__main__":
    client = ParseClient()
    
    print("\n" + "=" * 70)
    print("GAMMA API: COMPLETE WORKFLOW")
    print("=" * 70)
    
    # Step 1: Discover themes and folders
    print("\n[Step 1] Discovering themes and folders in workspace...")
    
    themes_data = client.list_themes(limit=5)
    themes = themes_data.get("data", [])
    print(f"  Found {len(themes)} available themes")
    
    selected_theme_id = None
    if themes:
        selected_theme = themes[0]
        selected_theme_id = selected_theme.get("id")
        print(f"    → Selected theme: {selected_theme.get('name', 'Unknown')}")
    
    folders_data = client.list_folders(limit=5)
    folders = folders_data.get("data", [])
    print(f"  Found {len(folders)} available folders")
    
    selected_folder_id = None
    if folders:
        selected_folder = folders[0]
        selected_folder_id = selected_folder.get("id")
        print(f"    → Selected folder: {selected_folder.get('name', 'Unknown')}")
    
    # Step 2: Generate presentations on different topics
    print("\n[Step 2] Generating presentations from topics...")
    
    topics = [
        {
            "title": "AI in Healthcare",
            "description": "Medical applications and patient care innovations"
        },
        {
            "title": "Sustainable Energy",
            "description": "Renewable sources and environmental impact"
        }
    ]
    
    generations = {}
    
    for topic in topics:
        title = topic["title"]
        description = topic["description"]
        prompt = f"{title}: {description}"
        
        print(f"\n  Generating: '{title}'")
        
        try:
            gen_id = client.generate_content(
                input_text=prompt,
                text_mode="generate",
                format="presentation",
                num_cards=6,
                theme_id=selected_theme_id,
                folder_ids=selected_folder_id,
                additional_instructions="Include real-world examples and statistics"
            )
            
            generations[title] = {
                "generation_id": gen_id,
                "status": "pending",
                "gamma_id": None,
                "export_urls": None
            }
            print(f"    ✓ Started: {gen_id}")
            
        except Exception as e:
            print(f"    ✗ Error: {str(e)}")
    
    # Step 3: Monitor all generations
    print("\n[Step 3] Monitoring generation progress...")
    
    for title, gen_info in generations.items():
        gen_id = gen_info["generation_id"]
        print(f"\n  '{title}' ({gen_id}):")
        
        status_response = poll_until_complete(client, gen_id, max_wait_seconds=120)
        
        if status_response:
            gen_info["status"] = status_response.get("status")
            gen_info["gamma_id"] = status_response.get("gammaId")
            print(f"    ✓ Complete! Gamma ID: {gen_info['gamma_id']}")
        else:
            gen_info["status"] = "failed"
            print(f"    ✗ Generation did not complete")
    
    # Step 4: Retrieve export URLs for completed generations
    print("\n[Step 4] Retrieving export URLs...")
    
    completed_count = 0
    
    for title, gen_info in generations.items():
        if gen_info["status"] != "completed":
            continue
        
        gen_id = gen_info["generation_id"]
        print(f"\n  '{title}':")
        
        try:
            export_urls = client.get_export_urls(gen_id)
            
            gen_info["export_urls"] = export_urls
            completed_count += 1
            
            pdf_url = export_urls.get("pdfUrl", "N/A")
            pptx_url = export_urls.get("pptxUrl", "N/A")
            
            if pdf_url != "N/A":
                print(f"    📄 PDF:  {pdf_url[:50]}...")
            if pptx_url != "N/A":
                print(f"    📊 PPTX: {pptx_url[:50]}...")
            
        except Exception as e:
            print(f"    ✗ Error retrieving URLs: {str(e)}")
    
    # Summary
    print("\n" + "=" * 70)
    print(f"SUMMARY: {completed_count}/{len(generations)} presentations ready")
    print("=" * 70)
    
    for title, gen_info in generations.items():
        status_symbol = "✓" if gen_info["status"] == "completed" else "✗"
        gamma_id = gen_info.get("gamma_id", "N/A")
        print(f"  {status_symbol} {title:<25} → {gamma_id}")
    
    print()