@hienlh/ppm 0.9.81 → 0.9.82

package/.opencode/skills/ai-multimodal/scripts/gemini_batch_process.py

@@ -1,1187 +0,0 @@
-#!/usr/bin/env python3
-"""
-Batch process multiple media files using Gemini API.
-
-Supports all Gemini modalities:
-- Audio: Transcription, analysis, summarization
-- Image: Captioning, detection, OCR, analysis
-- Video: Summarization, Q&A, scene detection
-- Document: PDF extraction, structured output
-- Generation: Image creation via Imagen 4 or Nano Banana (Gemini native)
-  - Nano Banana 2 (gemini-3.1-flash-image-preview): NEW DEFAULT - fastest, near-Pro quality, web grounding
-  - Nano Banana Flash (gemini-2.5-flash-image): Previous default, stable
-  - Nano Banana Pro (gemini-3-pro-image-preview): Quality/4K text/reasoning
-  - Imagen 4 (imagen-4.0-*): Production-grade generation
-"""
-
-import argparse
-import json
-import os
-import sys
-import time
-from pathlib import Path
-from typing import List, Dict, Any, Optional
-import csv
-import shutil
-
-# Import centralized environment resolver (works for both local and global installs)
-CLAUDE_ROOT = Path(__file__).parent.parent.parent.parent
-sys.path.insert(0, str(CLAUDE_ROOT / 'scripts'))
-try:
-    from resolve_env import resolve_env
-    CENTRALIZED_RESOLVER_AVAILABLE = True
-except ImportError:
-    # Fallback if centralized resolver not available
-    CENTRALIZED_RESOLVER_AVAILABLE = False
-    try:
-        from dotenv import load_dotenv
-    except ImportError:
-        load_dotenv = None
-
-# Import key rotation support
-sys.path.insert(0, str(Path(__file__).parent.parent.parent / 'common'))
-try:
-    from api_key_rotator import KeyRotator, is_rate_limit_error
-    from api_key_helper import find_all_api_keys
-    KEY_ROTATION_AVAILABLE = True
-except ImportError:
-    KEY_ROTATION_AVAILABLE = False
-    KeyRotator = None
-    is_rate_limit_error = None
-    find_all_api_keys = None
-
-try:
-    from google import genai
-    from google.genai import types
-except ImportError:
-    print("Error: google-genai package not installed")
-    print("Install with: pip install google-genai")
-    sys.exit(1)
-
-
-# Image generation model configuration
-# Default: gemini-3.1-flash-image-preview (Nano Banana 2 - fastest, near-Pro quality)
-# Alternative: imagen-4.0-generate-001 (production quality)
-# All image generation requires billing - no completely free option exists
-IMAGE_MODEL_DEFAULT = 'gemini-3.1-flash-image-preview'  # Nano Banana 2 (fastest, ~$0.045-0.151/image)
-IMAGE_MODEL_FALLBACK = 'gemini-2.5-flash-image'  # Fallback if Nano Banana 2 fails
-IMAGEN_MODELS = {
-    'imagen-4.0-generate-001',
-    'imagen-4.0-ultra-generate-001',
-    'imagen-4.0-fast-generate-001',
-}
-# Video models have no fallback - Veo always requires billing
-
-
-def find_api_key() -> Optional[str]:
-    """Find Gemini API key using centralized resolver or fallback.
-
-    Uses ~/.opencode/scripts/resolve_env.py for consistent resolution across all skills.
-    Falls back to local resolution if centralized resolver not available.
-
-    Priority order (highest to lowest):
-    1. process.env (runtime environment variables)
-    2. PROJECT/.opencode/skills/ai-multimodal/.env (skill-specific)
-    3. PROJECT/.opencode/skills/.env (shared skills)
-    4. PROJECT/.opencode/.env (project global)
-    5. ~/.opencode/skills/ai-multimodal/.env (user skill-specific)
-    6. ~/.opencode/skills/.env (user shared)
-    7. ~/.opencode/.env (user global)
-    """
-    if CENTRALIZED_RESOLVER_AVAILABLE:
-        # Use centralized resolver (recommended)
-        return resolve_env('GEMINI_API_KEY', skill='ai-multimodal')
-
-    # Fallback: Local resolution (legacy)
-    api_key = os.getenv('GEMINI_API_KEY')
-    if api_key:
-        return api_key
-
-    if load_dotenv:
-        script_dir = Path(__file__).parent
-        skill_dir = script_dir.parent
-        skills_dir = skill_dir.parent
-        claude_dir = skills_dir.parent
-
-        env_files = [
-            claude_dir / '.env',
-            skills_dir / '.env',
-            skill_dir / '.env',
-        ]
-
-        for env_file in env_files:
-            if env_file.exists():
-                load_dotenv(env_file, override=True)
-
-        api_key = os.getenv('GEMINI_API_KEY')
-        if api_key:
-            return api_key
-
-    return None
-
-
-def get_default_model(task: str) -> str:
-    """Get default model for task from environment or fallback.
-
-    Priority:
-    1. Environment variable for specific capability
-    2. Legacy GEMINI_MODEL variable
-    3. Hard-coded defaults
-    """
-    if task == 'generate':  # Image generation
-        model = os.getenv('IMAGE_GEN_MODEL')
-        if model:
-            return model
-        # Fallback to legacy
-        model = os.getenv('GEMINI_IMAGE_GEN_MODEL')
-        if model:
-            return model
-        # Default to Nano Banana 2 (fastest, near-Pro quality, web grounding)
-        # Alternative: gemini-2.5-flash-image (stable), imagen-4.0-generate-001 (production)
-        return 'gemini-3.1-flash-image-preview'
-
-    elif task == 'generate-video':
-        model = os.getenv('VIDEO_GEN_MODEL')
-        if model:
-            return model
-        return 'veo-3.1-generate-preview'  # New default
-
-    elif task in ['analyze', 'transcribe', 'extract']:
-        model = os.getenv('MULTIMODAL_MODEL')
-        if model:
-            return model
-        # Fallback to legacy
-        model = os.getenv('GEMINI_MODEL')
-        if model:
-            return model
-        return 'gemini-2.5-flash'  # Existing default
-
-    return 'gemini-2.5-flash'
-
-
-def validate_model_task_combination(model: str, task: str) -> None:
-    """Validate model is compatible with task.
-
-    Raises:
-        ValueError: If combination is invalid
-    """
-    # Video generation requires Veo
-    if task == 'generate-video':
-        if not model.startswith('veo-'):
-            raise ValueError(
-                f"Video generation requires Veo model, got '{model}'\n"
-                f"Valid models: veo-3.1-generate-preview, veo-3.1-fast-generate-preview, "
-                f"veo-3.0-generate-001, veo-3.0-fast-generate-001"
-            )
-
-    # Image generation models
-    if task == 'generate':
-        valid_image_models = [
-            'imagen-4.0-generate-001',
-            'imagen-4.0-ultra-generate-001',
-            'imagen-4.0-fast-generate-001',
-            'gemini-3.1-flash-image-preview',
-            'gemini-3-pro-image-preview',
-            'gemini-2.5-flash-image',
-            'gemini-2.5-flash-image-preview',
-        ]
-        if model not in valid_image_models:
-            # Allow gemini models for analysis-based generation (backward compat)
-            if not model.startswith('gemini-'):
-                raise ValueError(
-                    f"Image generation requires Imagen/Gemini image model, got '{model}'\n"
-                    f"Valid models: {', '.join(valid_image_models)}"
-                )
-
-
-def infer_task_from_file(file_path: str) -> str:
-    """Infer task type from file extension.
-
-    Returns:
-        'transcribe' for audio files
-        'analyze' for image/video/document files
-    """
-    ext = Path(file_path).suffix.lower()
-
-    audio_extensions = {'.mp3', '.wav', '.aac', '.flac', '.ogg', '.aiff', '.m4a'}
-    image_extensions = {'.jpg', '.jpeg', '.png', '.webp', '.heic', '.heif', '.gif', '.bmp'}
-    video_extensions = {'.mp4', '.mpeg', '.mov', '.avi', '.flv', '.mpg', '.webm', '.wmv', '.3gpp', '.mkv'}
-    document_extensions = {'.pdf', '.txt', '.html', '.md', '.doc', '.docx'}
-
-    if ext in audio_extensions:
-        return 'transcribe'
-    elif ext in image_extensions:
-        return 'analyze'
-    elif ext in video_extensions:
-        return 'analyze'
-    elif ext in document_extensions:
-        return 'extract'
-
-    # Default to analyze for unknown types
-    return 'analyze'
-
-
-def get_mime_type(file_path: str) -> str:
-    """Determine MIME type from file extension."""
-    ext = Path(file_path).suffix.lower()
-
-    mime_types = {
-        # Audio
-        '.mp3': 'audio/mp3',
-        '.wav': 'audio/wav',
-        '.aac': 'audio/aac',
-        '.flac': 'audio/flac',
-        '.ogg': 'audio/ogg',
-        '.aiff': 'audio/aiff',
-        # Image
-        '.jpg': 'image/jpeg',
-        '.jpeg': 'image/jpeg',
-        '.png': 'image/png',
-        '.webp': 'image/webp',
-        '.heic': 'image/heic',
-        '.heif': 'image/heif',
-        # Video
-        '.mp4': 'video/mp4',
-        '.mpeg': 'video/mpeg',
-        '.mov': 'video/quicktime',
-        '.avi': 'video/x-msvideo',
-        '.flv': 'video/x-flv',
-        '.mpg': 'video/mpeg',
-        '.webm': 'video/webm',
-        '.wmv': 'video/x-ms-wmv',
-        '.3gpp': 'video/3gpp',
-        # Document
-        '.pdf': 'application/pdf',
-        '.txt': 'text/plain',
-        '.html': 'text/html',
-        '.md': 'text/markdown',
-    }
-
-    return mime_types.get(ext, 'application/octet-stream')
-
-
-def upload_file(client: genai.Client, file_path: str, verbose: bool = False) -> Any:
-    """Upload file to Gemini File API."""
-    if verbose:
-        print(f"Uploading {file_path}...")
-
-    myfile = client.files.upload(file=file_path)
-
-    # Wait for processing (video/audio files need processing)
-    mime_type = get_mime_type(file_path)
-    if mime_type.startswith('video/') or mime_type.startswith('audio/'):
-        max_wait = 300  # 5 minutes
-        elapsed = 0
-        while myfile.state.name == 'PROCESSING' and elapsed < max_wait:
-            time.sleep(2)
-            myfile = client.files.get(name=myfile.name)
-            elapsed += 2
-            if verbose and elapsed % 10 == 0:
-                print(f"  Processing... {elapsed}s")
-
-        if myfile.state.name == 'FAILED':
-            raise ValueError(f"File processing failed: {file_path}")
-
-        if myfile.state.name == 'PROCESSING':
-            raise TimeoutError(f"Processing timeout after {max_wait}s: {file_path}")
-
-    if verbose:
-        print(f"  Uploaded: {myfile.name}")
-
-    return myfile
-
-
-def _is_billing_error(error: Exception) -> bool:
-    """Check if error is due to billing/access restrictions."""
-    error_str = str(error).lower()
-    billing_indicators = [
-        'billing',
-        'billed users',
-        'payment',
-        'access denied',
-        'not authorized',
-        'permission denied',
-    ]
-    return any(indicator in error_str for indicator in billing_indicators)
-
-
-def _is_free_tier_quota_error(error: Exception) -> bool:
-    """Check if error indicates free tier has zero quota for this model.
-
-    Free tier users have NO access to image/video generation models.
-    The API returns 'limit: 0' or 'RESOURCE_EXHAUSTED' with quota details.
-    """
-    error_str = str(error)
-    # Check for zero quota indicators
-    return (
-        'RESOURCE_EXHAUSTED' in error_str and
-        ('limit: 0' in error_str or 'free_tier' in error_str.lower())
-    )
-
-
-FREE_TIER_NO_ACCESS_MSG = """
-[FREE TIER LIMITATION] Image/Video generation is NOT available on free tier.
-
-Free tier users have zero quota (limit: 0) for:
-- All Imagen models (imagen-4.0-*)
-- All Veo models (veo-*)
-- Gemini image models (gemini-*-image, gemini-*-image-preview)
-
-To use image/video generation:
-1. Enable billing: https://aistudio.google.com/apikey
-2. Or use Google Cloud $300 free credits: https://cloud.google.com/free
-
-STOP: Do not retry image/video generation on free tier - it will always fail.
-""".strip()
-
-
-def generate_image_imagen4(
-    client,
-    prompt: str,
-    model: str,
-    num_images: int = 1,
-    aspect_ratio: str = '1:1',
-    size: str = '1K',
-    verbose: bool = False
-) -> Dict[str, Any]:
-    """Generate image using Imagen 4 models.
-
-    Returns special status 'billing_required' if model needs billing,
-    allowing caller to fallback to free-tier generate_content API.
-    """
-    try:
-        # Build config based on model (Fast doesn't support imageSize)
-        config_params = {
-            'numberOfImages': num_images,
-            'aspectRatio': aspect_ratio
-        }
-
-        # Only Standard and Ultra support imageSize parameter
-        if 'fast' not in model.lower() and model.startswith('imagen-'):
-            config_params['imageSize'] = size
-
-        gen_config = types.GenerateImagesConfig(**config_params)
-
-        if verbose:
-            print(f"  Generating with: {model}")
-            print(f"  Config: {num_images} images, {aspect_ratio}", end='')
-            if 'fast' not in model.lower() and model.startswith('imagen-'):
-                print(f", {size}")
-            else:
-                print()
-
-        response = client.models.generate_images(
-            model=model,
-            prompt=prompt,
-            config=gen_config
-        )
-
-        # Save images
-        generated_files = []
-        for i, generated_image in enumerate(response.generated_images):
-            # Find project root
-            script_dir = Path(__file__).parent
-            project_root = script_dir
-            for parent in [script_dir] + list(script_dir.parents):
-                if (parent / '.git').exists() or (parent / '.claude').exists():
-                    project_root = parent
-                    break
-
-            output_dir = project_root / 'docs' / 'assets'
-            output_dir.mkdir(parents=True, exist_ok=True)
-            output_file = output_dir / f"imagen4_generated_{int(time.time())}_{i}.png"
-
-            with open(output_file, 'wb') as f:
-                f.write(generated_image.image.image_bytes)
-            generated_files.append(str(output_file))
-
-            if verbose:
-                print(f"  Saved: {output_file}")
-
-        return {
-            'status': 'success',
-            'generated_images': generated_files,
-            'model': model
-        }
-
-    except Exception as e:
-        # Return special status for billing errors so caller can fallback
-        if _is_billing_error(e) and model in IMAGEN_MODELS:
-            return {
-                'status': 'billing_required',
-                'original_model': model,
-                'error': str(e)
-            }
-
-        if verbose:
-            print(f"  Error: {str(e)}")
-            import traceback
-            traceback.print_exc()
-        return {
-            'status': 'error',
-            'error': str(e)
-        }
-
-
-def generate_video_veo(
-    client,
-    prompt: str,
-    model: str,
-    resolution: str = '1080p',
-    aspect_ratio: str = '16:9',
-    reference_images: Optional[List[str]] = None,
-    verbose: bool = False
-) -> Dict[str, Any]:
-    """Generate video using Veo models.
-
-    For image-to-video with first/last frames (Veo 3.1):
-    - First reference image becomes the opening frame (image parameter)
-    - Second reference image becomes the closing frame (last_frame config)
-    - Model interpolates between them to create smooth video
-    """
-    try:
-        # Build config with snake_case for Python SDK
-        config_params = {
-            'aspect_ratio': aspect_ratio,
-            'resolution': resolution
-        }
-
-        # Prepare first frame and last frame images
-        first_frame = None
-        last_frame = None
-
-        if reference_images:
-            import mimetypes
-
-            def load_image(img_path_str: str) -> types.Image:
-                """Load image file as types.Image with bytes and mime type."""
-                img_path = Path(img_path_str)
-                image_bytes = img_path.read_bytes()
-                mime_type, _ = mimetypes.guess_type(str(img_path))
-                if not mime_type:
-                    mime_type = 'image/png'
-                return types.Image(
-                    image_bytes=image_bytes,
-                    mime_type=mime_type
-                )
-
-            # First image = opening frame
-            if len(reference_images) >= 1:
-                first_frame = load_image(reference_images[0])
-
-            # Second image = closing frame (last_frame in config)
-            if len(reference_images) >= 2:
-                last_frame = load_image(reference_images[1])
-                config_params['last_frame'] = last_frame
-
-        gen_config = types.GenerateVideosConfig(**config_params)
-
-        if verbose:
-            print(f"  Generating video with Veo: {model}")
-            print(f"  Config: {resolution}, {aspect_ratio}")
-            if first_frame:
-                print(f"  First frame: provided")
-            if last_frame:
-                print(f"  Last frame: provided (interpolation mode)")
-
-        start = time.time()
-
-        if verbose:
-            print(f"  Starting video generation (this may take 11s-6min)...")
-
-        # Call generate_videos with image parameter for first frame
-        operation = client.models.generate_videos(
-            model=model,
-            prompt=prompt,
-            image=first_frame,  # First frame as opening image
-            config=gen_config
-        )
-
-        # Poll operation until complete
-        poll_count = 0
-        while not operation.done:
-            poll_count += 1
-            if verbose and poll_count % 3 == 0:  # Update every 30s
-                elapsed = time.time() - start
-                print(f"  Still generating... ({elapsed:.0f}s elapsed)")
-            time.sleep(10)
-            operation = client.operations.get(operation)
-
-        duration = time.time() - start
-
-        # Access generated video from operation response
-        generated_video = operation.response.generated_videos[0]
-
-        # Download the video file first
-        client.files.download(file=generated_video.video)
-
-        # Save video
-        script_dir = Path(__file__).parent
-        project_root = script_dir
-        for parent in [script_dir] + list(script_dir.parents):
-            if (parent / '.git').exists() or (parent / '.claude').exists():
-                project_root = parent
-                break
-
-        output_dir = project_root / 'docs' / 'assets'
-        output_dir.mkdir(parents=True, exist_ok=True)
-        output_file = output_dir / f"veo_generated_{int(time.time())}.mp4"
-
-        # Now save to file
-        generated_video.video.save(str(output_file))
-
-        file_size = output_file.stat().st_size / (1024 * 1024)  # MB
-
-        if verbose:
-            print(f"  Generated in {duration:.1f}s")
-            print(f"  File size: {file_size:.2f} MB")
-            print(f"  Saved: {output_file}")
-
-        return {
-            'status': 'success',
-            'generated_video': str(output_file),
-            'generation_time': duration,
-            'file_size_mb': file_size,
-            'model': model
-        }
-
-    except Exception as e:
-        if verbose:
-            print(f"  Error: {str(e)}")
-            import traceback
-            traceback.print_exc()
-        return {
-            'status': 'error',
-            'error': str(e)
-        }
-
-
-def process_file(
-    client: genai.Client,
-    file_path: Optional[str],
-    prompt: str,
-    model: str,
-    task: str,
-    format_output: str,
-    aspect_ratio: Optional[str] = None,
-    image_size: Optional[str] = None,
-    verbose: bool = False,
-    max_retries: int = 3
-) -> Dict[str, Any]:
-    """Process a single file with retry logic.
-
-    Args:
-        image_size: Image size for Nano Banana models (1K, 2K, 4K). Must be uppercase K.
-                    Note: Not all models support image_size - only pass when explicitly needed.
-    """
-
-    for attempt in range(max_retries):
-        try:
-            # For generation tasks without input files
-            if task == 'generate' and not file_path:
-                content = [prompt]
-            else:
-                # Process input file
-                file_path = Path(file_path)
-                # Determine if we need File API
-                file_size = file_path.stat().st_size
-                use_file_api = file_size > 20 * 1024 * 1024  # >20MB
-
-                if use_file_api:
-                    # Upload to File API
-                    myfile = upload_file(client, str(file_path), verbose)
-                    content = [prompt, myfile]
-                else:
-                    # Inline data
-                    with open(file_path, 'rb') as f:
-                        file_bytes = f.read()
-
-                    mime_type = get_mime_type(str(file_path))
-                    content = [
-                        prompt,
-                        types.Part.from_bytes(data=file_bytes, mime_type=mime_type)
-                    ]
-
-            # Configure request
-            config_args = {}
-            if task == 'generate':
-                # Nano Banana requires fully uppercase 'IMAGE' per API spec
-                config_args['response_modalities'] = ['IMAGE']
-                # Build image_config with aspect_ratio and/or image_size
-                image_config_args = {}
-                if aspect_ratio:
-                    image_config_args['aspect_ratio'] = aspect_ratio
-                if image_size:
-                    # image_size must be uppercase K (1K, 2K, 4K)
-                    image_config_args['image_size'] = image_size
-                if image_config_args:
-                    config_args['image_config'] = types.ImageConfig(**image_config_args)
-
-            if format_output == 'json':
-                config_args['response_mime_type'] = 'application/json'
-
-            config = types.GenerateContentConfig(**config_args) if config_args else None
-
-            # Generate content
-            response = client.models.generate_content(
-                model=model,
-                contents=content,
-                config=config
-            )
-
-            # Extract response
-            result = {
-                'file': str(file_path) if file_path else 'generated',
-                'status': 'success',
-                'response': response.text if hasattr(response, 'text') else None
-            }
-
-            # Handle image output
-            if task == 'generate' and hasattr(response, 'candidates'):
-                for i, part in enumerate(response.candidates[0].content.parts):
-                    if part.inline_data:
-                        # Determine output directory - use project root docs/assets
-                        if file_path:
-                            output_dir = Path(file_path).parent
-                            base_name = Path(file_path).stem
-                        else:
-                            # Find project root (look for .git or .claude directory)
-                            script_dir = Path(__file__).parent
-                            project_root = script_dir
-                            for parent in [script_dir] + list(script_dir.parents):
-                                if (parent / '.git').exists() or (parent / '.claude').exists():
-                                    project_root = parent
-                                    break
-
-                            output_dir = project_root / 'docs' / 'assets'
-                            output_dir.mkdir(parents=True, exist_ok=True)
-                            base_name = "generated"
-
-                        output_file = output_dir / f"{base_name}_generated_{i}.png"
-                        with open(output_file, 'wb') as f:
-                            f.write(part.inline_data.data)
-                        result['generated_image'] = str(output_file)
-                        if verbose:
-                            print(f"  Saved image to: {output_file}")
-
-            return result
-
-        except Exception as e:
-            # Don't retry on billing/free tier errors - they won't resolve
-            if _is_billing_error(e) or _is_free_tier_quota_error(e):
-                return {
-                    'file': str(file_path) if file_path else 'generated',
-                    'status': 'error',
-                    'error': str(e)
-                }
-
-            # Check if this is a rate limit error (candidate for key rotation)
-            is_rate_limited = (
-                KEY_ROTATION_AVAILABLE and
-                is_rate_limit_error and
-                is_rate_limit_error(e)
-            )
-
-            if attempt == max_retries - 1:
-                return {
-                    'file': str(file_path) if file_path else 'generated',
-                    'status': 'error',
-                    'error': str(e),
-                    'rate_limited': is_rate_limited  # Flag for caller to handle rotation
-                }
-
-            wait_time = 2 ** attempt
-            if verbose:
-                print(f"  Retry {attempt + 1} after {wait_time}s: {e}")
-            time.sleep(wait_time)
-
-
-def batch_process(
-    files: List[str],
-    prompt: str,
-    model: str,
-    task: str,
-    format_output: str,
-    aspect_ratio: Optional[str] = None,
-    num_images: int = 1,
-    size: str = '1K',
-    resolution: str = '1080p',
-    reference_images: Optional[List[str]] = None,
-    output_file: Optional[str] = None,
-    verbose: bool = False,
-    dry_run: bool = False
-) -> List[Dict[str, Any]]:
-    """Batch process multiple files with automatic key rotation."""
-
-    # Initialize key rotator or fall back to single key
-    rotator = None
-    api_key = None
-
-    if KEY_ROTATION_AVAILABLE and find_all_api_keys:
-        all_keys = find_all_api_keys()
-        if all_keys:
-            if len(all_keys) > 1:
-                rotator = KeyRotator(keys=all_keys, verbose=verbose)
-                api_key = rotator.get_key()
-                if verbose:
-                    print(f"✓ Key rotation enabled with {len(all_keys)} keys", file=sys.stderr)
-            else:
-                api_key = all_keys[0]
-                if verbose:
-                    print(f"✓ Using single API key: {api_key[:8]}...", file=sys.stderr)
-
-    # Fallback to original single-key lookup
-    if not api_key:
-        api_key = find_api_key()
-
-    if not api_key:
-        print("Error: GEMINI_API_KEY not found")
-        print("\nSetup options:")
-        print("1. Run setup checker: python scripts/check_setup.py")
-        print("2. Show hierarchy: python ~/.opencode/scripts/resolve_env.py --show-hierarchy --skill ai-multimodal")
-        print("3. Quick setup: export GEMINI_API_KEY='your-key'")
-        print("4. Create .env: cd ~/.opencode/skills/ai-multimodal && cp .env.example .env")
-        print("\nFor key rotation, add multiple keys:")
-        print("   GEMINI_API_KEY=key1")
-        print("   GEMINI_API_KEY_2=key2")
-        print("   GEMINI_API_KEY_3=key3")
-        sys.exit(1)
-
-    if dry_run:
-        print("DRY RUN MODE - No API calls will be made")
-        print(f"Files to process: {len(files)}")
-        print(f"Model: {model}")
-        print(f"Task: {task}")
-        print(f"Prompt: {prompt}")
-        if rotator:
-            print(f"API keys available: {rotator.key_count}")
-        return []
-
-    # Create client with current key
-    client = genai.Client(api_key=api_key)
-    results = []
-
-    def get_client_with_rotation(error: Optional[Exception] = None) -> Optional[genai.Client]:
-        """Get client, rotating key if rate limited."""
-        nonlocal client, api_key
-
-        if error and rotator and is_rate_limit_error and is_rate_limit_error(error):
-            # Try to rotate to next key
-            if rotator.mark_rate_limited(str(error)):
-                new_key = rotator.get_key()
-                if new_key:
-                    api_key = new_key
-                    client = genai.Client(api_key=api_key)
-                    return client
-            # All keys exhausted
-            return None
-        return client
-
-    # For generation tasks without input files, process once
-    if task == 'generate' and not files:
-        if verbose:
-            print(f"\nGenerating image from prompt...")
-
-        # Use Imagen 4 API for imagen models
-        if model.startswith('imagen-') or model in IMAGEN_MODELS:
-            result = generate_image_imagen4(
-                client=client,
-                prompt=prompt,
-                model=model,
-                num_images=num_images,
-                aspect_ratio=aspect_ratio or '1:1',
-                size=size or '1K',  # Default to 1K for Imagen models
-                verbose=verbose
-            )
-
-            # Silent fallback to cheaper model if Imagen billing required
-            if result.get('status') == 'billing_required':
-                if verbose:
-                    print(f"  Falling back to: {IMAGE_MODEL_FALLBACK}")
-                result = process_file(
-                    client=client,
-                    file_path=None,
-                    prompt=prompt,
-                    model=IMAGE_MODEL_FALLBACK,
-                    task=task,
-                    format_output=format_output,
-                    aspect_ratio=aspect_ratio,
-                    image_size=size,
-                    verbose=verbose
-                )
-                # Check if free tier (zero quota) - stop immediately with clear message
-                error_str = result.get('error', '')
-                if result.get('status') == 'error':
-                    if _is_free_tier_quota_error(Exception(error_str)):
-                        result['error'] = FREE_TIER_NO_ACCESS_MSG
-                    elif _is_billing_error(Exception(error_str)):
-                        result['error'] = (
-                            "Image generation requires billing. Enable billing at: "
-                            "https://aistudio.google.com/apikey or use Google Cloud credits."
-                        )
-        else:
-            # Nano Banana (Flash/Pro) or other models via generate_content API
-            result = process_file(
-                client=client,
-                file_path=None,
-                prompt=prompt,
-                model=model,
-                task=task,
-                format_output=format_output,
-                aspect_ratio=aspect_ratio,
-                image_size=size,
-                verbose=verbose
-            )
-            # Check for free tier error
-            if result.get('status') == 'error':
-                error_str = result.get('error', '')
-                if _is_free_tier_quota_error(Exception(error_str)):
-                    result['error'] = FREE_TIER_NO_ACCESS_MSG
-
-        results.append(result)
-
-        if verbose:
-            status = result.get('status', 'unknown')
-            print(f"  Status: {status}")
-
-    elif task == 'generate-video' and not files:
-        if verbose:
-            print(f"\nGenerating video from prompt...")
-
-        result = generate_video_veo(
-            client=client,
-            prompt=prompt,
-            model=model,
-            resolution=resolution,
-            aspect_ratio=aspect_ratio or '16:9',
-            reference_images=reference_images,
-            verbose=verbose
-        )
-
-        # Check for free tier error - video gen has NO free tier access
-        if result.get('status') == 'error':
-            error_str = result.get('error', '')
-            if _is_free_tier_quota_error(Exception(error_str)) or _is_billing_error(Exception(error_str)):
-                result['error'] = FREE_TIER_NO_ACCESS_MSG
-
-        results.append(result)
-
-        if verbose:
-            status = result.get('status', 'unknown')
-            print(f"  Status: {status}")
-    else:
-        # Process input files with key rotation support
-        for i, file_path in enumerate(files, 1):
-            if verbose:
-                print(f"\n[{i}/{len(files)}] Processing: {file_path}")
-
-            # Try processing with key rotation on rate limit
-            max_rotation_attempts = rotator.key_count if rotator else 1
-            result = None
-
-            for rotation_attempt in range(max_rotation_attempts):
-                result = process_file(
-                    client=client,
-                    file_path=file_path,
-                    prompt=prompt,
-                    model=model,
-                    task=task,
-                    format_output=format_output,
-                    aspect_ratio=aspect_ratio,
-                    image_size=size,
-                    verbose=verbose
-                )
-
-                # Check if rate limited and can rotate
-                if (result.get('rate_limited') and rotator and
-                    rotation_attempt < max_rotation_attempts - 1):
-                    new_client = get_client_with_rotation(Exception(result.get('error', '')))
-                    if new_client:
-                        client = new_client
-                        if verbose:
-                            print(f"  Retrying with rotated key...")
-                        continue
-                    else:
-                        # All keys exhausted - mark result with clear error
-                        if verbose:
-                            print(f"  ⚠ All API keys exhausted (on cooldown)", file=sys.stderr)
-                        result['error'] = "All API keys exhausted (rate limited). Try again later."
-                break
-
-            results.append(result)
-
-            if verbose:
-                status = result.get('status', 'unknown')
-                print(f"  Status: {status}")
-
-    # Save results
-    if output_file:
-        save_results(results, output_file, format_output)
-
-    return results
-
-
-def print_results(results: List[Dict[str, Any]], task: str) -> None:
-    """Print results to stdout for LLM workflows.
-
-    Always prints actual results (not just success/fail counts) so LLMs
-    can continue processing based on the output.
-    """
-    if not results:
-        return
-
-    print("\n=== RESULTS ===\n")
-
-    for result in results:
-        file_name = result.get('file', 'generated')
-        status = result.get('status', 'unknown')
-
-        print(f"[{file_name}]")
-        print(f"Status: {status}")
-
-        if status == 'success':
-            # Print task-specific output
-            if task in ['analyze', 'transcribe', 'extract']:
-                response = result.get('response')
-                if response:
-                    print(f"Result:\n{response}")
-
-            elif task == 'generate':
-                # Image generation
-                generated_images = result.get('generated_images', [])
-                if generated_images:
-                    print(f"Generated images: {len(generated_images)}")
-                    for img in generated_images:
-                        print(f"  - {img}")
-                else:
-                    generated_image = result.get('generated_image')
-                    if generated_image:
-                        print(f"Generated image: {generated_image}")
-
-            elif task == 'generate-video':
-                generated_video = result.get('generated_video')
-                if generated_video:
-                    print(f"Generated video: {generated_video}")
-                    gen_time = result.get('generation_time')
-                    if gen_time:
-                        print(f"Generation time: {gen_time:.1f}s")
-                    file_size = result.get('file_size_mb')
-                    if file_size:
-                        print(f"File size: {file_size:.2f} MB")
-
-        elif status == 'error':
-            error = result.get('error', 'Unknown error')
-            print(f"Error: {error}")
-
-        print()  # Blank line between results
-
-
-def save_results(results: List[Dict[str, Any]], output_file: str, format_output: str):
-    """Save results to file."""
-    output_path = Path(output_file)
-
-    # Special handling for image generation - if output has image extension, copy the generated image
-    image_extensions = {'.png', '.jpg', '.jpeg', '.webp', '.gif', '.bmp'}
-    video_extensions = {'.mp4', '.mov', '.avi', '.webm'}
-
-    if output_path.suffix.lower() in image_extensions and len(results) == 1:
-        # Ensure output directory exists
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Check for multiple generated images
-        generated_images = results[0].get('generated_images')
-        if generated_images:
-            # Copy first image to the specified output location
-            shutil.copy2(generated_images[0], output_path)
-            return
-
-        # Legacy single image field
-        generated_image = results[0].get('generated_image')
-        if generated_image:
-            shutil.copy2(generated_image, output_path)
-            return
-        else:
-            # Don't write text reports to image files - save error as .txt instead
-            output_path = output_path.with_suffix('.error.txt')
-            output_path.parent.mkdir(parents=True, exist_ok=True)  # Ensure directory exists
-            print(f"Warning: Generation failed, saving error report to: {output_path}")
-
-    if output_path.suffix.lower() in video_extensions and len(results) == 1:
-        # Ensure output directory exists
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-
-        generated_video = results[0].get('generated_video')
-        if generated_video:
-            shutil.copy2(generated_video, output_path)
-            return
-        else:
-            output_path = output_path.with_suffix('.error.txt')
-            output_path.parent.mkdir(parents=True, exist_ok=True)
-            print(f"Warning: Video generation failed, saving error report to: {output_path}")
-
-    if format_output == 'json':
-        with open(output_path, 'w', encoding='utf-8') as f:
-            json.dump(results, f, indent=2)
-    elif format_output == 'csv':
-        with open(output_path, 'w', newline='', encoding='utf-8') as f:
-            fieldnames = ['file', 'status', 'response', 'error']
-            writer = csv.DictWriter(f, fieldnames=fieldnames)
-            writer.writeheader()
-            for result in results:
-                writer.writerow({
-                    'file': result.get('file', ''),
-                    'status': result.get('status', ''),
-                    'response': result.get('response', ''),
-                    'error': result.get('error', '')
-                })
-    else:  # markdown
-        with open(output_path, 'w', encoding='utf-8') as f:
-            f.write("# Batch Processing Results\n\n")
-            for i, result in enumerate(results, 1):
-                f.write(f"## {i}. {result.get('file', 'Unknown')}\n\n")
-                f.write(f"**Status**: {result.get('status', 'unknown')}\n\n")
-                if result.get('response'):
-                    f.write(f"**Response**:\n\n{result['response']}\n\n")
-                if result.get('error'):
-                    f.write(f"**Error**: {result['error']}\n\n")
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description='Batch process media files with Gemini API',
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  # Transcribe multiple audio files
-  %(prog)s --files *.mp3 --task transcribe --model gemini-2.5-flash
-
-  # Analyze images
-  %(prog)s --files *.jpg --task analyze --prompt "Describe this image" \\
-    --model gemini-2.5-flash
-
-  # Process PDFs to JSON
-  %(prog)s --files *.pdf --task extract --prompt "Extract data as JSON" \\
-    --format json --output results.json
-
-  # Generate images with Nano Banana 2 (fastest, near-Pro quality) - NEW DEFAULT
-  %(prog)s --task generate --prompt "A mountain landscape at sunset" \\
-    --model gemini-3.1-flash-image-preview --aspect-ratio 16:9 --size 2K
-
-  # Generate images with Nano Banana Pro (4K text, reasoning)
-  %(prog)s --task generate --prompt "Travel poster with text 'EXPLORE'" \\
-    --model gemini-3-pro-image-preview --aspect-ratio 3:4 --size 4K
-
-  # Generate images with Imagen 4 (production quality)
-  %(prog)s --task generate --prompt "Product photo of coffee mug" \\
-    --model imagen-4.0-ultra-generate-001 --aspect-ratio 1:1 --size 2K
-        """
-    )
-
-    parser.add_argument('--files', nargs='*', help='Input files to process')
-    parser.add_argument('--task',
-                       choices=['transcribe', 'analyze', 'extract', 'generate', 'generate-video'],
-                       help='Task to perform (auto-detected from file type if not specified)')
-    parser.add_argument('--prompt', help='Prompt for analysis/generation')
-    parser.add_argument('--model',
-                       help='Model to use (default: auto-detected from task and env vars)')
-    parser.add_argument('--format', dest='format_output', default='text',
-                       choices=['text', 'json', 'csv', 'markdown'],
-                       help='Output format (default: text)')
-
-    # Image generation options
-    # All 10 aspect ratios supported by Nano Banana / Imagen 4
-    parser.add_argument('--aspect-ratio',
-                       choices=['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9'],
-                       help='Aspect ratio for image/video generation')
-    parser.add_argument('--num-images', type=int, default=1,
-                       help='Number of images to generate (1-4, default: 1)')
-    # 4K available for Nano Banana Pro (gemini-3-pro-image-preview)
-    # Note: Not all models support --size, only use when needed
-    parser.add_argument('--size', choices=['1K', '2K', '4K'], default=None,
-                       help='Image size - 1K/2K for Imagen 4, 1K/2K/4K for Nano Banana (optional)')
-
-    # Video generation options
-    parser.add_argument('--resolution', choices=['720p', '1080p'], default='1080p',
-                       help='Video resolution (default: 1080p)')
-    parser.add_argument('--reference-images', nargs='+',
-                       help='Reference images for video generation (max 3)')
-
-    parser.add_argument('--output', help='Output file for results')
-    parser.add_argument('--verbose', '-v', action='store_true',
-                       help='Verbose output')
-    parser.add_argument('--dry-run', action='store_true',
-                       help='Show what would be done without making API calls')
-
-    args = parser.parse_args()
-
-    # Auto-detect task from file type if not specified
-    if not args.task:
-        if args.files and len(args.files) > 0:
-            args.task = infer_task_from_file(args.files[0])
-            if args.verbose:
-                print(f"Auto-detected task: {args.task} (from file extension)")
-        else:
-            parser.error("--task required when no input files provided")
-
-    # Auto-detect model if not specified
-    if not args.model:
-        args.model = get_default_model(args.task)
-        if args.verbose:
-            print(f"Auto-detected model: {args.model}")
-
-    # Validate model/task combination
-    try:
-        validate_model_task_combination(args.model, args.task)
-    except ValueError as e:
-        parser.error(str(e))
-
-    # Validate arguments
-    if args.task not in ['generate', 'generate-video'] and not args.files:
-        parser.error("--files required for non-generation tasks")
-
-    if args.task in ['generate', 'generate-video'] and not args.prompt:
-        parser.error("--prompt required for generation tasks")
-
-    if args.task not in ['generate', 'generate-video'] and not args.prompt:
-        # Set default prompts
-        if args.task == 'transcribe':
-            args.prompt = 'Generate a transcript with timestamps'
-        elif args.task == 'analyze':
-            args.prompt = 'Analyze this content'
-        elif args.task == 'extract':
-            args.prompt = 'Extract key information'
-
-    # Process files
-    files = args.files or []
-    results = batch_process(
-        files=files,
-        prompt=args.prompt,
-        model=args.model,
-        task=args.task,
-        format_output=args.format_output,
-        aspect_ratio=args.aspect_ratio,
-        num_images=args.num_images,
-        size=args.size,
-        resolution=args.resolution,
-        reference_images=args.reference_images,
-        output_file=args.output,
-        verbose=args.verbose,
-        dry_run=args.dry_run
-    )
-
-    # Print results and summary
-    if not args.dry_run and results:
-        # Always print actual results for LLM workflows
-        print_results(results, args.task)
-
-        # Print summary
-        success = sum(1 for r in results if r.get('status') == 'success')
-        failed = len(results) - success
-        print(f"{'='*50}")
-        print(f"Summary: {len(results)} processed, {success} success, {failed} failed")
-        if args.output:
-            print(f"Results saved to: {args.output}")
-
-
-if __name__ == '__main__':
-    main()