moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-ai-nano-banana/scripts/generate_image.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""
+Nano Banana Pro - Single Image Generation Script
+
+Generates images using the gemini-3-pro-image-preview model (Nano Banana Pro).
+This script is the canonical implementation for single image generation tasks.
+
+Features:
+    - 1K, 2K, 4K resolution support
+    - 10 aspect ratios (1:1, 16:9, etc.)
+    - Style prefix support for consistent aesthetics
+    - Exponential backoff retry for API quota errors
+    - Google Search grounding integration
+
+Usage:
+    python generate_image.py -p "A futuristic cityscape" -o city.png
+    python generate_image.py -p "Dashboard UI" -o ui.png -r 4K -a 16:9
+    python generate_image.py -p "Logo design" -o logo.png --style "minimalist, vector"
+
+Environment Variables Required:
+    GOOGLE_API_KEY - Your Google AI Studio API key
+
+Model: gemini-3-pro-image-preview (hardcoded)
+"""
+
+import argparse
+import os
+import random
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+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)
+
+try:
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except ImportError:
+    pass  # dotenv is optional
+
+
+# Fixed model - Nano Banana Pro
+MODEL_NAME = "gemini-3-pro-image-preview"
+
+# Supported configurations
+SUPPORTED_ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"]
+SUPPORTED_RESOLUTIONS = ["1K", "2K", "4K"]  # Must be uppercase
+
+# Retry configuration
+MAX_RETRIES = 5
+BASE_DELAY = 2.0
+MAX_DELAY = 60.0
+
+
+def get_api_key() -> str:
+    """Get API key from environment variable."""
+    api_key = os.getenv("GOOGLE_API_KEY")
+    if not api_key:
+        print("Error: GOOGLE_API_KEY environment variable not set.")
+        print("Set up your API key:")
+        print("  1. Get your key from https://aistudio.google.com/apikey")
+        print("  2. Create .env file with: GOOGLE_API_KEY=your_key_here")
+        print("  3. Or set environment variable: export GOOGLE_API_KEY=your_key_here")
+        sys.exit(1)
+    return api_key
+
+
+def validate_aspect_ratio(ratio: str) -> str:
+    """Validate and normalize aspect ratio."""
+    if ratio not in SUPPORTED_ASPECT_RATIOS:
+        print(f"Warning: '{ratio}' is not a standard aspect ratio.")
+        print(f"Supported ratios: {', '.join(SUPPORTED_ASPECT_RATIOS)}")
+        print("Using default: 16:9")
+        return "16:9"
+    return ratio
+
+
+def validate_resolution(resolution: str) -> str:
+    """Validate and normalize resolution (must be uppercase K)."""
+    normalized = resolution.upper()
+    if normalized not in SUPPORTED_RESOLUTIONS:
+        print(f"Warning: '{resolution}' is not a valid resolution.")
+        print(f"Supported resolutions: {', '.join(SUPPORTED_RESOLUTIONS)}")
+        print("Using default: 2K")
+        return "2K"
+    return normalized
+
+
+def build_prompt_with_style(prompt: str, style: Optional[str] = None) -> str:
+    """Build final prompt with optional style prefix."""
+    if style:
+        return f"{style}: {prompt}"
+    return prompt
+
+
+def calculate_backoff_delay(attempt: int, jitter: bool = True) -> float:
+    """Calculate exponential backoff delay with optional jitter."""
+    delay = min(BASE_DELAY * (2**attempt), MAX_DELAY)
+    if jitter:
+        delay = delay * (0.5 + random.random())
+    return delay
+
+
+def generate_image(
+    prompt: str,
+    output_path: str,
+    aspect_ratio: str = "16:9",
+    resolution: str = "2K",
+    style: Optional[str] = None,
+    enable_grounding: bool = False,
+    max_retries: int = MAX_RETRIES,
+    verbose: bool = False,
+) -> dict:
+    """
+    Generate an image using Nano Banana Pro (gemini-3-pro-image-preview).
+
+    Args:
+        prompt: The image generation prompt
+        output_path: Path to save the generated image
+        aspect_ratio: Image aspect ratio (default: 16:9)
+        resolution: Image resolution - 1K, 2K, or 4K (default: 2K)
+        style: Optional style prefix (e.g., "photorealistic", "minimalist")
+        enable_grounding: Enable Google Search grounding (default: False)
+        max_retries: Maximum retry attempts for transient errors (default: 5)
+        verbose: Print detailed progress information
+
+    Returns:
+        dict with generation metadata including success status, file path, and timing
+    """
+    # Validate inputs
+    aspect_ratio = validate_aspect_ratio(aspect_ratio)
+    resolution = validate_resolution(resolution)
+    final_prompt = build_prompt_with_style(prompt, style)
+
+    # Get API key
+    api_key = get_api_key()
+
+    if verbose:
+        print(f"  Model: {MODEL_NAME}")
+        print(f"  Final Prompt: {final_prompt[:100]}{'...' if len(final_prompt) > 100 else ''}")
+        print(f"  Style: {style or 'None'}")
+        print("-" * 50)
+
+    # Initialize client
+    client = genai.Client(api_key=api_key)
+
+    # Build configuration
+    config_params = {
+        "response_modalities": ["TEXT", "IMAGE"],
+        "image_config": types.ImageConfig(aspect_ratio=aspect_ratio, image_size=resolution),
+    }
+
+    # Optionally enable Google Search grounding
+    if enable_grounding:
+        config_params["tools"] = [{"google_search": {}}]
+
+    config = types.GenerateContentConfig(**config_params)
+
+    # Retry logic with exponential backoff
+    last_error = None
+    for attempt in range(max_retries):
+        try:
+            if verbose:
+                print(f"  Attempt {attempt + 1}/{max_retries}...")
+
+            start_time = time.time()
+
+            # Generate image
+            response = client.models.generate_content(model=MODEL_NAME, contents=final_prompt, config=config)
+
+            generation_time = time.time() - start_time
+
+            # Ensure output directory exists
+            output_dir = Path(output_path).parent
+            if output_dir and str(output_dir) != "." and not output_dir.exists():
+                output_dir.mkdir(parents=True, exist_ok=True)
+
+            # Save image
+            image_saved = False
+            text_response = ""
+
+            for part in response.candidates[0].content.parts:
+                if part.inline_data is not None:
+                    with open(output_path, "wb") as f:
+                        f.write(part.inline_data.data)
+                    image_saved = True
+                elif hasattr(part, "text") and part.text:
+                    text_response = part.text
+
+            if not image_saved:
+                raise RuntimeError("No image data in response. The model may have returned text-only response.")
+
+            # Return success metadata
+            return {
+                "success": True,
+                "model": MODEL_NAME,
+                "prompt": prompt,
+                "final_prompt": final_prompt,
+                "style": style,
+                "output_path": str(Path(output_path).absolute()),
+                "aspect_ratio": aspect_ratio,
+                "resolution": resolution,
+                "generation_time_seconds": round(generation_time, 2),
+                "timestamp": datetime.now().isoformat(),
+                "text_response": text_response if text_response else None,
+                "grounding_enabled": enable_grounding,
+                "attempts": attempt + 1,
+            }
+
+        except Exception as e:
+            last_error = e
+            error_str = str(e).lower()
+
+            # Check for non-retryable errors
+            if "permission" in error_str or "api_key" in error_str or "invalid_api_key" in error_str:
+                print(f"Error: API key issue - {e}")
+                print("Check your GOOGLE_API_KEY in .env file or environment variable.")
+                break
+
+            if "invalid" in error_str and "argument" in error_str:
+                print(f"Error: Invalid argument - {e}")
+                print(f"Check aspect_ratio ({aspect_ratio}) and resolution ({resolution}).")
+                break
+
+            # Check for quota/rate limit errors - apply exponential backoff
+            is_quota_error = any(kw in error_str for kw in ["quota", "rate", "429", "resource_exhausted", "too_many"])
+
+            if attempt < max_retries - 1:
+                delay = calculate_backoff_delay(attempt, jitter=is_quota_error)
+                if is_quota_error:
+                    print(f"  Rate limit hit (attempt {attempt + 1}). Waiting {delay:.1f}s...")
+                else:
+                    print(f"  Attempt {attempt + 1} failed: {e}")
+                    print(f"  Retrying in {delay:.1f}s...")
+                time.sleep(delay)
+            else:
+                print(f"  All {max_retries} attempts failed.")
+
+    # Return failure metadata
+    return {
+        "success": False,
+        "model": MODEL_NAME,
+        "prompt": prompt,
+        "final_prompt": final_prompt,
+        "style": style,
+        "error": str(last_error),
+        "timestamp": datetime.now().isoformat(),
+        "attempts": max_retries,
+    }
+
+
+def main():
+    """Main entry point for CLI usage."""
+    parser = argparse.ArgumentParser(
+        description="Generate images using Nano Banana Pro (gemini-3-pro-image-preview)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    # Basic usage
+    python generate_image.py -p "A fluffy cat eating a banana" -o cat.png
+
+    # High resolution with specific aspect ratio
+    python generate_image.py -p "Modern dashboard UI" -o dashboard.png -a 16:9 -r 4K
+
+    # With style prefix
+    python generate_image.py -p "Mountain landscape" -o landscape.png \\
+        --style "photorealistic, dramatic lighting"
+
+    # With Google Search grounding for factual content
+    python generate_image.py -p "Mount Fuji at sunset" -o fuji.png -g
+
+    # Verbose mode with all options
+    python generate_image.py -p "Tech company logo" -o logo.png \\
+        -r 4K -a 1:1 --style "minimalist, vector art" -v
+
+Style Prefix Examples:
+    - "photorealistic, 8K, detailed"
+    - "minimalist, vector art, clean"
+    - "watercolor painting, soft colors"
+    - "3D render, cinematic lighting"
+    - "anime style, vibrant colors"
+
+Environment:
+    GOOGLE_API_KEY - Required. Get from https://aistudio.google.com/apikey
+        """,
+    )
+
+    parser.add_argument("-p", "--prompt", required=True, help="Image generation prompt (descriptive text)")
+
+    parser.add_argument("-o", "--output", required=True, help="Output file path for the generated image (PNG format)")
+
+    parser.add_argument(
+        "-a", "--aspect-ratio", default="16:9", choices=SUPPORTED_ASPECT_RATIOS, help="Aspect ratio (default: 16:9)"
+    )
+
+    parser.add_argument(
+        "-r",
+        "--resolution",
+        default="2K",
+        choices=SUPPORTED_RESOLUTIONS,
+        help="Resolution: 1K, 2K, or 4K (default: 2K)",
+    )
+
+    parser.add_argument("--style", help="Style prefix to prepend to prompt (e.g., 'photorealistic', 'minimalist')")
+
+    parser.add_argument(
+        "-g", "--enable-grounding", action="store_true", help="Enable Google Search grounding for factual content"
+    )
+
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=MAX_RETRIES,
+        help=f"Maximum retry attempts for transient errors (default: {MAX_RETRIES})",
+    )
+
+    parser.add_argument("-v", "--verbose", action="store_true", help="Print detailed progress information")
+
+    args = parser.parse_args()
+
+    print(f"Generating image with {MODEL_NAME}...")
+    print(f"  Prompt: {args.prompt[:80]}{'...' if len(args.prompt) > 80 else ''}")
+    if args.style:
+        print(f"  Style: {args.style}")
+    print(f"  Aspect Ratio: {args.aspect_ratio}")
+    print(f"  Resolution: {args.resolution}")
+    print(f"  Output: {args.output}")
+
+    result = generate_image(
+        prompt=args.prompt,
+        output_path=args.output,
+        aspect_ratio=args.aspect_ratio,
+        resolution=args.resolution,
+        style=args.style,
+        enable_grounding=args.enable_grounding,
+        max_retries=args.max_retries,
+        verbose=args.verbose,
+    )
+
+    if result["success"]:
+        print("\nSuccess!")
+        print(f"  File: {result['output_path']}")
+        print(f"  Time: {result['generation_time_seconds']}s")
+        print(f"  Attempts: {result['attempts']}")
+        if result.get("text_response"):
+            print(f"  Model Note: {result['text_response'][:200]}")
+    else:
+        print(f"\nFailed: {result['error']}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

moai_adk/templates/.claude/skills/moai-docs-generation/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: "moai-docs-generation"
+description: "Documentation generation patterns for technical specs, API docs, user guides, and knowledge bases using real tools like Sphinx, MkDocs, TypeDoc, and Nextra. Use when creating docs from code, building doc sites, or automating documentation workflows."
+version: 2.1.0
+category: "workflow"
+modularized: true
+context: fork
+agent: general-purpose
+tags: ['workflow', 'documentation', 'sphinx', 'mkdocs', 'typedoc', 'api-docs', 'static-sites']
+updated: 2026-01-08
+status: "active"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - Bash
+  - mcp__context7__resolve-library-id
+  - mcp__context7__get-library-docs
+---
+
+# Documentation Generation Patterns
+
+## Quick Reference (30 seconds)
+
+Purpose: Generate professional documentation using established tools and frameworks.
+
+Core Documentation Tools:
+- Python: Sphinx with autodoc, MkDocs with Material theme, pydoc
+- TypeScript/JavaScript: TypeDoc, JSDoc, TSDoc
+- API Documentation: OpenAPI/Swagger from FastAPI/Express, Redoc, Stoplight
+- Static Sites: Nextra (Next.js), Docusaurus (React), VitePress (Vue)
+- Universal: Markdown, MDX, reStructuredText
+
+When to Use This Skill:
+- Generating API documentation from code annotations
+- Building documentation sites with search and navigation
+- Creating user guides and technical specifications
+- Automating documentation updates in CI/CD pipelines
+- Converting between documentation formats
+
+---
+
+## Implementation Guide (5 minutes)
+
+### Python Documentation with Sphinx
+
+Sphinx Setup and Configuration:
+
+Install Sphinx and extensions with pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme myst-parser
+
+Initialize a Sphinx project by running sphinx-quickstart docs which creates the basic structure.
+
+Configure conf.py with the following key settings:
+- Set extensions to include autodoc, napoleon, typehints, and myst_parser
+- Configure html_theme to sphinx_rtd_theme for a professional look
+- Add autodoc_typehints set to description for inline type hints
+
+Generate API documentation by running sphinx-apidoc with the source directory, outputting to docs/api, then run make html in the docs directory.
+
+### Python Documentation with MkDocs
+
+MkDocs Material Setup:
+
+Install with pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python
+
+Create mkdocs.yml configuration:
+- Set site_name and site_url
+- Configure theme with name material and desired color palette
+- Add plugins including search and mkdocstrings
+- Define nav structure with sections and pages
+
+Use mkdocstrings syntax in Markdown files with ::: module.path to auto-generate API docs from docstrings.
+
+Serve locally with mkdocs serve, build with mkdocs build, deploy with mkdocs gh-deploy.
+
+### TypeScript Documentation with TypeDoc
+
+TypeDoc Setup:
+
+Install with npm install typedoc --save-dev
+
+Add to package.json scripts: typedoc --out docs/api src/index.ts
+
+Configure with typedoc.json:
+- Set entryPoints to source files
+- Configure out to docs/api
+- Enable includeVersion and categorizeByGroup
+- Set theme to default or install custom themes
+
+Generate documentation by running npm run docs:generate
+
+### JavaScript Documentation with JSDoc
+
+JSDoc Setup:
+
+Install with npm install jsdoc --save-dev
+
+Create jsdoc.json configuration:
+- Set source include paths and includePattern
+- Configure templates and output destination
+- Enable markdown plugin for rich formatting
+
+Document functions with JSDoc comments using tags:
+- @param for parameters with type and description
+- @returns for return value documentation
+- @example for usage examples
+- @throws for error documentation
+
+### OpenAPI/Swagger Documentation
+
+FastAPI Auto-Documentation:
+
+FastAPI provides automatic OpenAPI docs. Access Swagger UI at /docs and ReDoc at /redoc.
+
+Enhance documentation by:
+- Adding docstrings to route handlers
+- Using response_model for typed responses
+- Defining examples in Pydantic model Config class
+- Setting tags for endpoint grouping
+- Adding detailed descriptions in route decorators
+
+Export OpenAPI spec programmatically with app.openapi() and save to openapi.json.
+
+Express with Swagger:
+
+Install swagger-jsdoc and swagger-ui-express.
+
+Configure swagger-jsdoc with OpenAPI definition and API file paths.
+
+Add @openapi comments to route handlers documenting paths, parameters, and responses.
+
+Serve Swagger UI at /api-docs endpoint.
+
+### Static Documentation Sites
+
+Nextra (Next.js):
+
+Reference Skill("moai-library-nextra") for comprehensive Nextra patterns.
+
+Key advantages: MDX support, file-system routing, built-in search, theme customization.
+
+Create with npx create-nextra-app, configure theme.config.tsx, organize pages in pages directory.
+
+Docusaurus (React):
+
+Initialize with npx create-docusaurus@latest my-docs classic
+
+Configure in docusaurus.config.js:
+- Set siteMetadata with title, tagline, url
+- Configure presets with docs and blog settings
+- Add themeConfig for navbar and footer
+- Enable search with algolia plugin
+
+Organize documentation in docs folder with category.json files for sidebar structure.
+
+VitePress (Vue):
+
+Initialize with npm init vitepress
+
+Configure in .vitepress/config.js:
+- Set title, description, base path
+- Define themeConfig with nav and sidebar
+- Configure search and social links
+
+Use Markdown with Vue components, code highlighting, and frontmatter.
+
+---
+
+## Advanced Patterns (10+ minutes)
+
+### Documentation from SPEC Files
+
+Pattern for generating documentation from MoAI SPEC files:
+
+Read SPEC file content and extract key sections: id, title, description, requirements, api_endpoints.
+
+Generate structured Markdown documentation:
+- Create overview section from description
+- List requirements as feature bullets
+- Document each API endpoint with method, path, and description
+- Add usage examples based on endpoint definitions
+
+Save generated docs to appropriate location in docs directory.
+
+### CI/CD Documentation Pipeline
+
+GitHub Actions Workflow:
+
+Create .github/workflows/docs.yml that triggers on push to main branch when src or docs paths change.
+
+Workflow steps:
+- Checkout repository
+- Setup language runtime (Python, Node.js)
+- Install documentation dependencies
+- Generate documentation using appropriate tool
+- Deploy to GitHub Pages, Netlify, or Vercel
+
+Example for Python/Sphinx:
+- Install with pip install sphinx sphinx-rtd-theme
+- Generate with sphinx-build -b html docs/source docs/build
+- Deploy using actions-gh-pages action
+
+Example for TypeScript/TypeDoc:
+- Install with npm ci
+- Generate with npm run docs:generate
+- Deploy to Pages
+
+### Documentation Validation
+
+Link Checking:
+
+Use linkchecker for local link validation in HTML output.
+
+For Markdown, use markdown-link-check in pre-commit hooks.
+
+Spell Checking:
+
+Use pyspelling with Aspell for automated spell checking.
+
+Configure .pyspelling.yml with matrix entries for different file types.
+
+Documentation Coverage:
+
+For Python, use interrogate to check docstring coverage.
+
+Configure minimum coverage thresholds in pyproject.toml.
+
+Fail CI builds if coverage drops below threshold.
+
+### Multi-Language Documentation
+
+Internationalization with Nextra:
+
+Configure i18n in next.config.js with locales array and defaultLocale.
+
+Create locale-specific pages in pages/[locale] directory.
+
+Use next-intl or similar for translations.
+
+Internationalization with Docusaurus:
+
+Configure i18n in docusaurus.config.js with defaultLocale and locales.
+
+Use docusaurus write-translations to generate translation files.
+
+Organize translations in i18n/[locale] directory structure.
+
+---
+
+## Works Well With
+
+Skills:
+- moai-library-nextra - Comprehensive Nextra documentation framework patterns
+- moai-lang-python - Python docstring conventions and typing
+- moai-lang-typescript - TypeScript/JSDoc documentation patterns
+- moai-domain-backend - API documentation for backend services
+- moai-workflow-project - Project documentation integration
+
+Agents:
+- manager-docs - Documentation workflow orchestration
+- expert-backend - API endpoint documentation
+- expert-frontend - Component documentation
+
+Commands:
+- /moai:3-sync - Documentation synchronization with code changes
+
+---
+
+## Tool Reference
+
+Python Documentation:
+- Sphinx: https://www.sphinx-doc.org/
+- MkDocs: https://www.mkdocs.org/
+- MkDocs Material: https://squidfunk.github.io/mkdocs-material/
+- mkdocstrings: https://mkdocstrings.github.io/
+
+JavaScript/TypeScript Documentation:
+- TypeDoc: https://typedoc.org/
+- JSDoc: https://jsdoc.app/
+- TSDoc: https://tsdoc.org/
+
+API Documentation:
+- OpenAPI Specification: https://spec.openapis.org/
+- Swagger UI: https://swagger.io/tools/swagger-ui/
+- Redoc: https://redocly.github.io/redoc/
+- Stoplight: https://stoplight.io/
+
+Static Site Generators:
+- Nextra: https://nextra.site/
+- Docusaurus: https://docusaurus.io/
+- VitePress: https://vitepress.dev/
+
+Style Guides:
+- Google Developer Documentation Style Guide: https://developers.google.com/style
+- Microsoft Writing Style Guide: https://learn.microsoft.com/style-guide/
+
+---
+
+Version: 2.0.0
+Last Updated: 2025-12-30