dantelabs-agentic-school 1.0.0 → 1.2.0

package/plugins/common/skills/kie-image-generator/scripts/generate_image.py

@@ -0,0 +1,285 @@
+#!/usr/bin/env python3
+"""
+Kie.ai Image Generation CLI
+
+Generate images using Kie.ai's diverse AI models.
+"""
+
+import sys
+import argparse
+from pathlib import Path
+from typing import Dict, Any
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent))
+
+from utils import (
+    load_api_key,
+    get_credits,
+    print_credits,
+    print_models,
+    select_model_interactive,
+    confirm_generation,
+    submit_task,
+    poll_task,
+    download_image,
+    generate_filename,
+    MODELS,
+    CREDIT_TO_USD,
+    GENERATION_ENDPOINTS,
+    RECORD_INFO_ENDPOINTS,
+    JOBS_API_MODELS
+)
+from models import (
+    build_gpt4o_payload,
+    build_flux_payload,
+    build_nano_payload,
+    build_nano_pro_payload,
+    build_seedream_payload,
+    build_imagen_payload,
+    build_ideogram_payload
+)
+from models.seedream_edit import build_seedream_edit_payload
+from models.nano_banana_edit import build_nano_edit_payload
+
+
+AVAILABLE_MODELS = list(GENERATION_ENDPOINTS.keys())
+
+MODEL_PAYLOAD_BUILDERS = {
+    'gpt4o-image': build_gpt4o_payload,
+    'flux-kontext-pro': build_flux_payload,
+    'flux-kontext-max': build_flux_payload,
+    'nano-banana': build_nano_payload,
+    'nano-banana-pro': build_nano_pro_payload,
+    'nano-banana-edit': build_nano_edit_payload,
+    'seedream-v4': build_seedream_payload,
+    'seedream-v4-edit': build_seedream_edit_payload,
+    'imagen-4-ultra': build_imagen_payload,
+    'imagen-4': build_imagen_payload,
+    'imagen-4-fast': build_imagen_payload,
+    'ideogram-v3': lambda prompt, **kw: build_ideogram_payload(prompt, 'ideogram-v3', **kw),
+    'ideogram-character': lambda prompt, **kw: build_ideogram_payload(prompt, 'ideogram-character', **kw),
+}
+
+
+def parse_arguments():
+    """Parse command-line arguments"""
+    parser = argparse.ArgumentParser(
+        description='Generate images using Kie.ai models',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s --credits                             # Check available credits
+  %(prog)s --list-models                         # List all models with pricing
+  %(prog)s "a beautiful sunset"                  # Interactive model selection
+  %(prog)s "cyberpunk city" --model flux-kontext-pro
+  %(prog)s "abstract art" --model seedream-v4 --resolution 4K
+  %(prog)s "portrait" --model imagen-4-ultra --aspect-ratio 3:4
+        """
+    )
+
+    # Positional argument (optional for info commands)
+    parser.add_argument(
+        'prompt',
+        nargs='?',
+        help='Image generation prompt'
+    )
+
+    # Info commands
+    parser.add_argument(
+        '--credits', '-c',
+        action='store_true',
+        help='Show current account credits'
+    )
+    parser.add_argument(
+        '--list-models', '-l',
+        action='store_true',
+        help='List all available models with pricing'
+    )
+
+    # Model selection
+    parser.add_argument(
+        '--model', '-m',
+        choices=AVAILABLE_MODELS,
+        help='Model to use (interactive selection if not specified)'
+    )
+
+    # Skip confirmation
+    parser.add_argument(
+        '--yes', '-y',
+        action='store_true',
+        help='Skip confirmation prompts'
+    )
+
+    # No download
+    parser.add_argument(
+        '--no-download',
+        action='store_true',
+        help='Skip image download (print URL only)'
+    )
+
+    parser.add_argument(
+        '--output', '-o',
+        type=Path,
+        default=Path.home() / 'Downloads' / 'images',
+        help='Output directory (default: ~/Downloads/images/)'
+    )
+
+    # Common parameters
+    parser.add_argument('--size', help='Image size/aspect ratio')
+    parser.add_argument('--ratio', help='Image ratio (Flux models)')
+    parser.add_argument('--format', help='Output format')
+    parser.add_argument('--resolution', help='Image resolution (Seedream)')
+    parser.add_argument('--aspect-ratio', help='Aspect ratio (Imagen)')
+    parser.add_argument('--rendering', help='Rendering speed (Ideogram)')
+    parser.add_argument('--style', help='Style preset (Ideogram)')
+    parser.add_argument('--variants', type=int, help='Number of variants (GPT-4O)')
+    parser.add_argument('--images', type=int, help='Number of images')
+    parser.add_argument('--num-images', type=int, help='Number of images (alias)')
+    parser.add_argument('--seed', type=int, help='Random seed')
+    parser.add_argument('--negative', help='Negative prompt')
+    parser.add_argument('--negative-prompt', help='Negative prompt (alias)')
+    parser.add_argument('--expand-prompt', action='store_true', help='Enable prompt enhancement')
+    parser.add_argument('--reference', help='Reference image URL (Ideogram Character)')
+    parser.add_argument('--reference-images', help='Reference image URLs (Ideogram Character)')
+
+    return parser.parse_args()
+
+
+def main():
+    """Main execution function"""
+    args = parse_arguments()
+
+    try:
+        # Load API key
+        api_key = load_api_key()
+
+        # Handle info commands
+        if args.credits:
+            print_credits(api_key)
+            return 0
+
+        if args.list_models:
+            print_models()
+            return 0
+
+        # Require prompt for generation
+        if not args.prompt:
+            print("❌ Error: Please provide a prompt or use --credits / --list-models")
+            print("   Run with --help for usage information")
+            return 1
+
+        print("🎨 Kie.ai Image Generator")
+        print(f"Prompt: {args.prompt}\n")
+
+        # Get current credits
+        credits, usd = get_credits(api_key)
+        print(f"💰 Current Balance: {credits:,.1f} credits (${usd:.2f})")
+
+        # Model selection
+        has_image = bool(args.reference or args.reference_images)
+
+        if args.model:
+            model_id = args.model
+            # Validate image requirement
+            model = MODELS.get(model_id)
+            if model and model.get('type') == 'image-to-image' and not has_image:
+                print(f"\n⚠️  Model '{model_id}' requires an image input.")
+                print("   Use --reference <url> to provide an image.")
+                return 1
+        else:
+            # Interactive selection
+            model_id = select_model_interactive(has_image)
+            if not model_id:
+                print("\n👋 Generation cancelled.")
+                return 0
+
+        # Confirm generation
+        if not args.yes:
+            if not confirm_generation(model_id, credits):
+                print("\n👋 Generation cancelled.")
+                return 0
+
+        print(f"\nModel: {MODELS.get(model_id, {}).get('name', model_id)}")
+
+        # Get endpoints for model
+        generation_endpoint = GENERATION_ENDPOINTS.get(model_id)
+        record_info_endpoint = RECORD_INFO_ENDPOINTS.get(model_id)
+
+        if not generation_endpoint or not record_info_endpoint:
+            raise ValueError(f"Unsupported model: {model_id}")
+
+        # Build payload using model-specific builder
+        payload_builder = MODEL_PAYLOAD_BUILDERS.get(model_id)
+        if not payload_builder:
+            raise ValueError(f"No payload builder for model: {model_id}")
+
+        # Collect model parameters from args
+        params = {}
+        for param in ['size', 'ratio', 'format', 'resolution', 'aspect_ratio',
+                      'rendering', 'style', 'variants', 'images', 'num_images',
+                      'seed', 'negative', 'negative_prompt', 'expand_prompt',
+                      'reference', 'reference_images']:
+            value = getattr(args, param.replace('-', '_'), None)
+            if value is not None:
+                params[param.replace('-', '_')] = value
+
+        # Map reference_images to image_urls for seedream-edit
+        if 'reference_images' in params:
+            params['image_urls'] = params['reference_images']
+
+        # Build payload
+        payload = payload_builder(args.prompt, **params)
+        print(f"\n📋 Payload: {payload}\n")
+
+        # Submit task (use Jobs API for certain models)
+        jobs_model_id = JOBS_API_MODELS.get(model_id)
+        task_id = submit_task(api_key, generation_endpoint, payload, model_id=jobs_model_id)
+
+        # Poll for completion
+        image_url = poll_task(
+            api_key,
+            record_info_endpoint,
+            task_id,
+            max_attempts=60,
+            poll_interval=2
+        )
+
+        print(f"\n🖼️  Image URL: {image_url}")
+
+        # Download image
+        if not args.no_download:
+            # Determine output file extension
+            if 'jpeg' in image_url.lower() or payload.get('output_format', '').lower() == 'jpeg':
+                extension = 'jpg'
+            else:
+                extension = 'png'
+
+            # Generate filename
+            filename = generate_filename(model_id, args.prompt, extension)
+
+            # Download image
+            output_path = download_image(image_url, args.output, filename)
+            print(f"\n✨ Success! Image saved to: {output_path}")
+        else:
+            print("\n✨ Image generated successfully!")
+
+        # Report updated credits
+        new_credits, new_usd = get_credits(api_key)
+        used = credits - new_credits
+        print(f"\n💰 Credits used: {used:,.1f} (${used * CREDIT_TO_USD:.2f})")
+        print(f"   Remaining: {new_credits:,.1f} credits (${new_usd:.2f})")
+
+        return 0
+
+    except KeyboardInterrupt:
+        print("\n\n⚠️  Operation cancelled by user")
+        return 130
+
+    except Exception as e:
+        print(f"\n❌ Error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugins/common/skills/kie-image-generator/scripts/models/__init__.py

@@ -0,0 +1,19 @@
+"""Model-specific parameter handlers"""
+
+from .gpt4o import build_gpt4o_payload
+from .flux_kontext import build_flux_payload
+from .nano_banana import build_nano_payload
+from .nano_banana_pro import build_nano_pro_payload
+from .seedream import build_seedream_payload
+from .imagen import build_imagen_payload
+from .ideogram import build_ideogram_payload
+
+__all__ = [
+    'build_gpt4o_payload',
+    'build_flux_payload',
+    'build_nano_payload',
+    'build_nano_pro_payload',
+    'build_seedream_payload',
+    'build_imagen_payload',
+    'build_ideogram_payload',
+]

package/plugins/common/skills/kie-image-generator/scripts/models/flux_kontext.py

@@ -0,0 +1,36 @@
+"""Flux Kontext parameter handler"""
+
+from typing import Dict, Any
+
+
+def build_flux_payload(prompt: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for Flux Kontext Pro/Max models.
+
+    Parameters:
+        prompt: Image description
+        ratio: Image ratio (16:9, 21:9, 4:3, 1:1, 3:4, 9:16, 16:21) [default: 1:1]
+        format: Output format (jpeg, png) [default: png]
+
+    Returns:
+        API request payload
+    """
+    payload = {'prompt': prompt}
+
+    # Image ratio
+    ratio = kwargs.get('ratio', '1:1')
+    if ratio:
+        valid_ratios = ['16:9', '21:9', '4:3', '1:1', '3:4', '9:16', '16:21']
+        if ratio not in valid_ratios:
+            raise ValueError(f"Invalid ratio. Must be one of: {', '.join(valid_ratios)}")
+        payload['image_ratio'] = ratio
+
+    # Output format
+    fmt = kwargs.get('format', 'png')
+    if fmt:
+        valid_formats = ['jpeg', 'png']
+        if fmt.lower() not in valid_formats:
+            raise ValueError(f"Invalid format. Must be one of: {', '.join(valid_formats)}")
+        payload['output_format'] = fmt.lower()
+
+    return payload

package/plugins/common/skills/kie-image-generator/scripts/models/gpt4o.py

@@ -0,0 +1,36 @@
+"""GPT-4O Image parameter handler"""
+
+from typing import Dict, Any
+
+
+def build_gpt4o_payload(prompt: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for GPT-4O Image model.
+
+    Parameters:
+        prompt: Image description
+        size: Aspect ratio (1:1, 3:2, 2:3) [default: 1:1]
+        variants: Number of variants (1-4) [default: 1]
+
+    Returns:
+        API request payload
+    """
+    payload = {'prompt': prompt}
+
+    # Size parameter
+    size = kwargs.get('size', '1:1')
+    if size:
+        valid_sizes = ['1:1', '3:2', '2:3']
+        if size not in valid_sizes:
+            raise ValueError(f"Invalid size. Must be one of: {', '.join(valid_sizes)}")
+        payload['size'] = size
+
+    # Number of variants
+    variants = kwargs.get('variants', 1)
+    if variants:
+        variants = int(variants)
+        if not 1 <= variants <= 4:
+            raise ValueError("variants must be between 1 and 4")
+        payload['nVariants'] = variants
+
+    return payload

package/plugins/common/skills/kie-image-generator/scripts/models/ideogram.py

@@ -0,0 +1,85 @@
+"""Ideogram V3 and Character parameter handler"""
+
+from typing import Dict, Any, Optional, List
+
+
+def build_ideogram_payload(prompt: str, model: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for Ideogram V3 and Ideogram Character models.
+
+    Parameters:
+        prompt: Image description
+        model: Model ID ('ideogram-v3' or 'ideogram-character')
+        rendering: Rendering speed (TURBO, BALANCED, QUALITY) [default: BALANCED]
+        style: Style preset (AUTO, GENERAL, REALISTIC, DESIGN, FICTION) [default: AUTO]
+        size: Image size/aspect ratio
+        num_images: Number of images (1-4) [default: 1]
+        expand_prompt: Enable MagicPrompt enhancement [default: False]
+        seed: Random seed for reproducibility
+        negative_prompt: Elements to exclude
+        reference_images: Reference image URLs (for ideogram-character)
+
+    Returns:
+        API request payload
+    """
+    payload = {'prompt': prompt}
+
+    # Rendering speed
+    rendering = kwargs.get('rendering', 'BALANCED')
+    if rendering:
+        valid_speeds = ['TURBO', 'BALANCED', 'QUALITY']
+        rendering_upper = rendering.upper()
+        if rendering_upper not in valid_speeds:
+            raise ValueError(f"Invalid rendering. Must be one of: {', '.join(valid_speeds)}")
+        payload['rendering_speed'] = rendering_upper
+
+    # Style
+    style = kwargs.get('style', 'AUTO')
+    if style:
+        if model == 'ideogram-v3':
+            valid_styles = ['AUTO', 'GENERAL', 'REALISTIC', 'DESIGN']
+        else:  # ideogram-character
+            valid_styles = ['AUTO', 'REALISTIC', 'FICTION']
+
+        style_upper = style.upper()
+        if style_upper not in valid_styles:
+            raise ValueError(f"Invalid style. Must be one of: {', '.join(valid_styles)}")
+        payload['style'] = style_upper
+
+    # Image size
+    size = kwargs.get('size')
+    if size:
+        payload['image_size'] = size
+
+    # Number of images (API expects string)
+    num_images = kwargs.get('num_images', 1)
+    if num_images:
+        num_images = int(num_images)
+        if not 1 <= num_images <= 4:
+            raise ValueError("num_images must be between 1 and 4")
+        payload['num_images'] = str(num_images)
+
+    # Expand prompt (MagicPrompt)
+    expand_prompt = kwargs.get('expand_prompt', False)
+    if expand_prompt:
+        payload['expand_prompt'] = bool(expand_prompt)
+
+    # Seed
+    seed = kwargs.get('seed')
+    if seed is not None:
+        payload['seed'] = int(seed)
+
+    # Negative prompt
+    negative = kwargs.get('negative_prompt') or kwargs.get('negative')
+    if negative:
+        payload['negative_prompt'] = negative
+
+    # Reference images (for ideogram-character)
+    if model == 'ideogram-character':
+        reference_images = kwargs.get('reference_images') or kwargs.get('reference')
+        if reference_images:
+            if isinstance(reference_images, str):
+                reference_images = [reference_images]
+            payload['reference_image_urls'] = reference_images
+
+    return payload

package/plugins/common/skills/kie-image-generator/scripts/models/imagen.py

@@ -0,0 +1,48 @@
+"""Imagen 4 parameter handler"""
+
+from typing import Dict, Any, Optional
+
+
+def build_imagen_payload(prompt: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for Imagen 4 models (Ultra, Standard, Fast).
+
+    Parameters:
+        prompt: Image description
+        negative_prompt: Elements to exclude
+        aspect_ratio: Aspect ratio (1:1, 16:9, 9:16, 3:4, 4:3) [default: 1:1]
+        num_images: Number of images (1-4) [default: 1]
+        seed: Random seed for reproducibility
+
+    Returns:
+        API request payload
+    """
+    payload = {'prompt': prompt}
+
+    # Negative prompt
+    negative = kwargs.get('negative_prompt') or kwargs.get('negative')
+    if negative:
+        payload['negative_prompt'] = negative
+
+    # Aspect ratio
+    aspect_ratio = kwargs.get('aspect_ratio', '1:1')
+    if aspect_ratio:
+        valid_ratios = ['1:1', '16:9', '9:16', '3:4', '4:3']
+        if aspect_ratio not in valid_ratios:
+            raise ValueError(f"Invalid aspect_ratio. Must be one of: {', '.join(valid_ratios)}")
+        payload['aspect_ratio'] = aspect_ratio
+
+    # Number of images (API expects string)
+    num_images = kwargs.get('num_images', 1)
+    if num_images:
+        num_images = int(num_images)
+        if not 1 <= num_images <= 4:
+            raise ValueError("num_images must be between 1 and 4")
+        payload['num_images'] = str(num_images)
+
+    # Seed
+    seed = kwargs.get('seed')
+    if seed is not None:
+        payload['seed'] = int(seed)
+
+    return payload

package/plugins/common/skills/kie-image-generator/scripts/models/nano_banana.py

@@ -0,0 +1,40 @@
+"""Nano Banana (Gemini 2.5 Flash) parameter handler"""
+
+from typing import Dict, Any
+
+
+def build_nano_payload(prompt: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for Nano Banana (Gemini 2.5 Flash) model via Jobs API.
+
+    Parameters:
+        prompt: Image description (max 5000 chars)
+        format: Output format (png, jpeg) [default: png]
+        size: Image size (1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9, auto) [default: 1:1]
+
+    Returns:
+        API request payload for Jobs API
+    """
+    if len(prompt) > 5000:
+        raise ValueError("Prompt must be 5000 characters or less")
+
+    payload = {'prompt': prompt}
+
+    # Output format (lowercase for Jobs API)
+    fmt = kwargs.get('format', 'png')
+    if fmt:
+        valid_formats = ['png', 'jpeg']
+        fmt_lower = fmt.lower()
+        if fmt_lower not in valid_formats:
+            raise ValueError(f"Invalid format. Must be one of: {', '.join(valid_formats)}")
+        payload['output_format'] = fmt_lower
+
+    # Image size
+    size = kwargs.get('size', '1:1')
+    if size:
+        valid_sizes = ['1:1', '9:16', '16:9', '3:4', '4:3', '3:2', '2:3', '5:4', '4:5', '21:9', 'auto']
+        if size not in valid_sizes:
+            raise ValueError(f"Invalid size. Must be one of: {', '.join(valid_sizes)}")
+        payload['image_size'] = size
+
+    return payload

package/plugins/common/skills/kie-image-generator/scripts/models/nano_banana_edit.py

@@ -0,0 +1,55 @@
+"""Nano Banana Edit (Gemini 2.5 Flash) parameter handler"""
+
+from typing import Dict, Any, List
+
+def build_nano_edit_payload(prompt: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for Nano Banana Edit model via Jobs API.
+
+    Parameters:
+        prompt: Image editing instruction (max 5000 chars)
+        image_urls: List of input image URLs (required, up to 10 images)
+        format: Output format (png, jpeg) [default: png]
+        size: Image size (1:1, 9:16, 16:9, 3:4, 4:3, 3:2, 2:3, 5:4, 4:5, 21:9, auto) [default: 1:1]
+
+    Returns:
+        API request payload for Jobs API
+    """
+    if len(prompt) > 5000:
+        raise ValueError("Prompt must be 5000 characters or less")
+
+    # image_urls is required for edit model
+    image_urls = kwargs.get('image_urls') or kwargs.get('image_url') or kwargs.get('reference') or kwargs.get('reference_images')
+    if not image_urls:
+        raise ValueError("image_urls parameter is required for nano-banana-edit model. Use --reference or --reference-images")
+
+    # Convert single URL to list
+    if isinstance(image_urls, str):
+        image_urls = [image_urls]
+
+    if len(image_urls) > 10:
+        raise ValueError("Maximum 10 input images allowed")
+
+    payload = {
+        'prompt': prompt,
+        'image_urls': image_urls
+    }
+
+    # Output format (lowercase for Jobs API)
+    fmt = kwargs.get('format', 'png')
+    if fmt:
+        valid_formats = ['png', 'jpeg']
+        fmt_lower = fmt.lower()
+        if fmt_lower not in valid_formats:
+            raise ValueError(f"Invalid format. Must be one of: {', '.join(valid_formats)}")
+        payload['output_format'] = fmt_lower
+
+    # Image size
+    size = kwargs.get('size', '1:1')
+    if size:
+        valid_sizes = ['1:1', '9:16', '16:9', '3:4', '4:3', '3:2', '2:3', '5:4', '4:5', '21:9', 'auto']
+        if size not in valid_sizes:
+            raise ValueError(f"Invalid size. Must be one of: {', '.join(valid_sizes)}")
+        payload['image_size'] = size
+
+    return payload

package/plugins/common/skills/kie-image-generator/scripts/models/nano_banana_pro.py

@@ -0,0 +1,47 @@
+"""Nano Banana Pro (DeepSeed) parameter handler - Jobs API v1"""
+
+from typing import Dict, Any, List, Optional
+
+
+def build_nano_pro_payload(prompt: str, **kwargs) -> Dict[str, Any]:
+    """
+    Build payload for Nano Banana Pro model via Jobs API v1.
+
+    Parameters:
+        prompt: Image description (required)
+        aspect_ratio: Aspect ratio (1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9, 9:21) [default: 1:1]
+        format: Output format (jpg, png, webp) [default: png]
+        image_input: Reference image URLs (up to 4 images)
+
+    Returns:
+        API request payload for Jobs API v1
+    """
+    payload = {'prompt': prompt}
+
+    # Aspect ratio
+    aspect_ratio = kwargs.get('aspect_ratio') or kwargs.get('size') or kwargs.get('ratio')
+    if aspect_ratio:
+        valid_ratios = ['1:1', '3:2', '2:3', '4:3', '3:4', '16:9', '9:16', '21:9', '9:21']
+        if aspect_ratio not in valid_ratios:
+            raise ValueError(f"Invalid aspect_ratio. Must be one of: {', '.join(valid_ratios)}")
+        payload['aspect_ratio'] = aspect_ratio
+
+    # Output format (only if specified)
+    fmt = kwargs.get('format') or kwargs.get('output_format')
+    if fmt:
+        valid_formats = ['jpg', 'png', 'webp']
+        fmt_lower = fmt.lower()
+        if fmt_lower not in valid_formats:
+            raise ValueError(f"Invalid format. Must be one of: {', '.join(valid_formats)}")
+        payload['output_format'] = fmt_lower
+
+    # Reference images (optional, up to 4)
+    image_input = kwargs.get('image_input') or kwargs.get('reference_images')
+    if image_input:
+        if isinstance(image_input, str):
+            image_input = [image_input]
+        if len(image_input) > 4:
+            raise ValueError("Maximum 4 reference images allowed")
+        payload['image_input'] = image_input
+
+    return payload