codewave-openclaw-installer 1.0.2 → 2.1.0

package/skills/ppt-master/scripts/generate_examples_index.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Examples Index Generator
+
+Automatically scans the examples directory and generates a README.md index file.
+
+Usage:
+    python3 scripts/generate_examples_index.py
+    python3 scripts/generate_examples_index.py examples
+"""
+
+import sys
+from pathlib import Path
+from datetime import datetime
+from collections import defaultdict
+
+try:
+    from project_utils import find_all_projects, get_project_info, CANVAS_FORMATS
+except ImportError:
+    print("Error: Cannot import the project_utils module")
+    print("Please ensure project_utils.py is in the same directory")
+    sys.exit(1)
+
+
+def generate_examples_index(examples_dir: str = 'examples') -> str:
+    """
+    Generate a README.md index for the examples directory
+
+    Args:
+        examples_dir: Path to the examples directory
+
+    Returns:
+        Generated README.md content
+    """
+    examples_path = Path(examples_dir)
+
+    if not examples_path.exists():
+        print(f"[ERROR] Directory not found: {examples_dir}")
+        return ""
+
+    print(f"[SCAN] Scanning directory: {examples_dir}")
+
+    # Find all projects
+    projects = find_all_projects(examples_dir)
+
+    if not projects:
+        print("[WARN] No projects found")
+        return ""
+
+    print(f"Found {len(projects)} project(s)")
+
+    # Collect project information
+    projects_info = []
+    for project_path in projects:
+        info = get_project_info(str(project_path))
+        projects_info.append(info)
+
+    # Sort by date (newest first)
+    projects_info.sort(key=lambda x: x['date'], reverse=True)
+
+    # Group by format
+    by_format = defaultdict(list)
+    for info in projects_info:
+        by_format[info['format']].append(info)
+
+    # Generate README content
+    content = []
+    content.append("# PPT Master Example Projects Index\n")
+    content.append("> This file is auto-generated by `skills/ppt-master/scripts/generate_examples_index.py`\n")
+    content.append(f"> Last updated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+
+    # Overview statistics
+    content.append("## [Stats] Overview\n")
+    content.append(f"- **Total projects**: {len(projects_info)}")
+    content.append(f"- **Canvas formats**: {len(by_format)} type(s)")
+
+    total_svgs = sum(info['svg_count'] for info in projects_info)
+    content.append(f"- **SVG files**: {total_svgs}")
+
+    # Statistics by format
+    content.append("\n### Format Distribution\n")
+    for fmt_key in sorted(by_format.keys(), key=lambda x: len(by_format[x]), reverse=True):
+        count = len(by_format[fmt_key])
+        fmt_name = CANVAS_FORMATS.get(fmt_key, {}).get('name', fmt_key)
+        content.append(f"- **{fmt_name}**: {count} project(s)")
+
+    # Recently updated
+    content.append("\n## [New] Recently Updated\n")
+    for info in projects_info[:5]:
+        content.append(
+            f"- **{info['name']}** ({info['format_name']}) - {info['date_formatted']}")
+
+    # Project list by format
+    content.append("\n## [List] Project List\n")
+
+    # Define format display order
+    format_order = ['ppt169', 'ppt43', 'wechat',
+                    'xiaohongshu', 'moments', 'story', 'banner', 'a4']
+
+    for fmt_key in format_order:
+        if fmt_key not in by_format:
+            continue
+
+        fmt_info = CANVAS_FORMATS.get(fmt_key, {})
+        fmt_name = fmt_info.get('name', fmt_key)
+        dimensions = fmt_info.get('dimensions', '')
+
+        content.append(f"\n### {fmt_name} ({dimensions})\n")
+
+        projects_list = by_format[fmt_key]
+        # Sort by date
+        projects_list.sort(key=lambda x: x['date'], reverse=True)
+
+        for info in projects_list:
+            # Project name and link
+            project_link = f"./{info['dir_name']}"
+
+            # Build project entry
+            line = f"- **[{info['name']}]({project_link})**"
+
+            # Add date
+            line += f" - {info['date_formatted']}"
+
+            # Add SVG count
+            line += f" - {info['svg_count']} page(s)"
+
+            content.append(line)
+
+    # Other uncategorized formats
+    other_formats = set(by_format.keys()) - set(format_order)
+    if other_formats:
+        content.append("\n### Other Formats\n")
+        for fmt_key in sorted(other_formats):
+            projects_list = by_format[fmt_key]
+            for info in projects_list:
+                project_link = f"./{info['dir_name']}"
+                line = f"- **[{info['name']}]({project_link})**"
+                line += f" ({info['format_name']}) - {info['date_formatted']}"
+                line += f" - {info['svg_count']} page(s)"
+                content.append(line)
+
+    # Usage instructions
+    content.append("\n## [Docs] Usage Instructions\n")
+    content.append("### Preview Projects\n")
+    content.append("Each project contains the following files:\n")
+    content.append("- `README.md` - Project documentation")
+    content.append("- `Design Spec & Content Outline.md` - Full design specification")
+    content.append("- `svg_output/` - SVG output files\n")
+
+    content.append("**Method 1: Using an HTTP server (recommended)**\n")
+    content.append("```bash")
+    content.append(
+        "python3 -m http.server --directory examples/<project_name>/svg_output 8000")
+    content.append("# Visit http://localhost:8000")
+    content.append("```\n")
+
+    content.append("**Method 2: Open SVG directly**\n")
+    content.append("```bash")
+    content.append(
+        "open examples/<project_name>/svg_output/slide_01_cover.svg")
+    content.append("```\n")
+
+    # Create new project
+    content.append("### Create a New Project\n")
+    content.append("Refer to existing project structures, or use the project management tool:\n")
+    content.append("```bash")
+    content.append(
+        "python3 scripts/project_manager.py init my_project --format ppt169")
+    content.append("```\n")
+
+    # Contribution guidelines
+    content.append("## [Contribute] Contributing Example Projects\n")
+    content.append("We welcome you to share your projects in the examples directory!\n")
+    content.append("### Project Requirements\n")
+    content.append("1. Follow the standard project structure")
+    content.append("2. Include a complete README.md and design specification")
+    content.append("3. SVG files must comply with technical specifications")
+    content.append("4. Directory naming format: `{project_name}_{format}_{YYYYMMDD}`\n")
+
+    content.append("### Submission Process\n")
+    content.append("1. Create a project under the `examples/` directory")
+    content.append(
+        "2. Validate the project: `python3 scripts/project_manager.py validate examples/<project>`")
+    content.append("3. Update the index: `python3 scripts/generate_examples_index.py`")
+    content.append("4. Submit a Pull Request\n")
+
+    # Related resources
+    content.append("## [Resources] Related Resources\n")
+    content.append("- [Quick Start](../README.md)")
+    content.append("- [Workflow Tutorial](../../AGENTS.md)")
+    content.append("- [Canvas Formats](../references/canvas-formats.md)")
+    content.append("- [Role Definitions](../references/)")
+    content.append("- [Chart Templates](../templates/charts/README.md)\n")
+
+    # Footer
+    content.append("---\n")
+    content.append(
+        f"*Auto-generated on {datetime.now().strftime('%Y-%m-%d %H:%M:%S')} by PPT Master*")
+
+    return "\n".join(content)
+
+
+def main() -> None:
+    """Run the CLI entry point."""
+    examples_dir = 'examples'
+
+    if len(sys.argv) > 1:
+        examples_dir = sys.argv[1]
+
+    print("=" * 80)
+    print("PPT Master - Examples Index Generator")
+    print("=" * 80 + "\n")
+
+    # Generate index content
+    content = generate_examples_index(examples_dir)
+
+    if not content:
+        print("\n[ERROR] Generation failed")
+        sys.exit(1)
+
+    # Write to file
+    output_file = Path(examples_dir) / 'README.md'
+
+    try:
+        with open(output_file, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+        print(f"\n[OK] Index file generated: {output_file}")
+        print(f"   Contains {len(content.splitlines())} lines")
+
+        # Display statistics
+        projects_count = content.count('- **[')
+        print(f"   Indexed {projects_count} project(s)")
+
+    except Exception as e:
+        print(f"\n[ERROR] Failed to write file: {e}")
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/skills/ppt-master/scripts/image_backends/__init__.py

@@ -0,0 +1 @@
+"""Internal backend implementations for image_gen.py."""

package/skills/ppt-master/scripts/image_backends/backend_aigw_gemini.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+AIGW Gemini Image Generation Backend
+
+Generates images via AIGW's Gemini models using OpenAI-compatible chat completions API.
+Used by image_gen.py as a backend module.
+
+Configuration keys:
+  AIGW_GEMINI_API_KEY   (required)
+  AIGW_GEMINI_BASE_URL  (optional) Default: https://aigw.netease.com/v1
+  AIGW_GEMINI_MODEL     (optional) Override default model
+
+Dependencies:
+  pip install openai Pillow
+"""
+
+import base64
+import os
+import time
+import threading
+from openai import OpenAI
+from image_backends.backend_common import (
+    MAX_RETRIES,
+    is_rate_limit_error,
+    normalize_image_size,
+    resolve_output_path,
+    retry_delay,
+    save_image_bytes,
+)
+
+# Constants
+VALID_ASPECT_RATIOS = [
+    "1:1", "1:4", "1:8",
+    "2:3", "3:2", "3:4", "4:1", "4:3",
+    "4:5", "5:4", "8:1", "9:16", "16:9", "21:9"
+]
+
+VALID_IMAGE_SIZES = ["512px", "1K", "2K", "4K"]
+
+DEFAULT_MODEL = "gemini-2.5-flash-image-preview"
+
+
+def _generate_image(api_key: str, prompt: str, negative_prompt: str = None,
+                    aspect_ratio: str = "1:1", image_size: str = "1K",
+                    output_dir: str = None, filename: str = None,
+                    model: str = DEFAULT_MODEL, base_url: str = None) -> str:
+    """
+    Image generation via AIGW Gemini API using chat completions.
+
+    Returns:
+        Path of the saved image file
+
+    Raises:
+        RuntimeError: When generation fails
+    """
+    client = OpenAI(api_key=api_key, base_url=base_url or "https://aigw.netease.com/v1")
+
+    # Build prompt - must explicitly ask for image generation
+    final_prompt = f"Generate an image: {prompt}"
+    if negative_prompt:
+        final_prompt += f"\n\nAvoid: {negative_prompt}"
+
+    # Build vertexai config
+    vertexai_config = {
+        "response_modalities": ["TEXT", "IMAGE"],
+    }
+    
+    # Add image_config if supported by model
+    if "gemini-3" in model or "gemini-2.5" in model:
+        vertexai_config["image_config"] = {
+            "aspect_ratio": aspect_ratio,
+        }
+        if "gemini-3" in model or "gemini-3.1" in model:
+            vertexai_config["image_config"]["image_size"] = image_size
+
+    print(f"[AIGW Gemini]")
+    print(f"  Model:        {model}")
+    print(f"  Prompt:       {final_prompt[:120]}{'...' if len(final_prompt) > 120 else ''}")
+    print(f"  Aspect Ratio: {aspect_ratio}")
+    print(f"  Image Size:   {image_size}")
+    print()
+
+    start_time = time.time()
+    print(f"  ⏳ Generating...", end="", flush=True)
+
+    # Heartbeat thread
+    heartbeat_stop = threading.Event()
+
+    def _heartbeat():
+        while not heartbeat_stop.is_set():
+            heartbeat_stop.wait(5)
+            if not heartbeat_stop.is_set():
+                elapsed = time.time() - start_time
+                print(f" {elapsed:.0f}s...", end="", flush=True)
+
+    hb_thread = threading.Thread(target=_heartbeat, daemon=True)
+    hb_thread.start()
+
+    try:
+        resp = client.chat.completions.create(
+            model=model,
+            messages=[
+                {
+                    "role": "user",
+                    "content": final_prompt
+                }
+            ],
+            stream=False,
+            extra_body={
+                "vertexai": vertexai_config
+            }
+        )
+    finally:
+        heartbeat_stop.set()
+        hb_thread.join(timeout=1)
+
+    elapsed = time.time() - start_time
+    print(f"\n  ✅ Image generated ({elapsed:.1f}s)")
+
+    if resp is not None and resp.choices:
+        message = resp.choices[0].message
+
+        # --- Strategy 1: Check image_urls field (AIGW returns data URIs here) ---
+        raw_dict = resp.model_dump()
+        image_urls = raw_dict.get("choices", [{}])[0].get("message", {}).get("image_urls", [])
+        if image_urls:
+            for url in image_urls:
+                if isinstance(url, str) and url.startswith("data:image"):
+                    try:
+                        _header, b64data = url.split(",", 1)
+                        image_data = base64.b64decode(b64data)
+                        path = resolve_output_path(prompt, output_dir, filename, ".png")
+                        return save_image_bytes(image_data, path)
+                    except Exception as e:
+                        raise RuntimeError(f"Failed to decode image from image_urls: {e}")
+
+        # --- Strategy 2: Check content as raw base64 (legacy path) ---
+        content = message.content
+        if content and len(content) > 1000:
+            try:
+                image_data = base64.b64decode(content)
+                path = resolve_output_path(prompt, output_dir, filename, ".png")
+                return save_image_bytes(image_data, path)
+            except Exception as e:
+                raise RuntimeError(f"Failed to decode image from content: {e}")
+
+        # No image found
+        raise RuntimeError("No image was generated. The model may have returned text only.")
+
+    raise RuntimeError("No response from API")
+
+
+def generate(prompt: str, negative_prompt: str = None,
+             aspect_ratio: str = "1:1", image_size: str = "1K",
+             output_dir: str = None, filename: str = None,
+             model: str = None, max_retries: int = MAX_RETRIES) -> str:
+    """
+    AIGW Gemini image generation with automatic retry.
+
+    Reads credentials from environment or .env:
+      AIGW_GEMINI_API_KEY (falls back to OPENAI_API_KEY)
+      AIGW_GEMINI_BASE_URL (falls back to OPENAI_BASE_URL or https://aigw.netease.com/v1)
+      AIGW_GEMINI_MODEL (optional override)
+
+    Args:
+        prompt: Image description
+        negative_prompt: Things to avoid
+        aspect_ratio: Image aspect ratio
+        image_size: Image size (512px, 1K, 2K, 4K)
+        output_dir: Output directory
+        filename: Output filename
+        model: Model override
+        max_retries: Max retry attempts
+
+    Returns:
+        Path to saved image
+    """
+    api_key = os.environ.get("AIGW_GEMINI_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    base_url = os.environ.get("AIGW_GEMINI_BASE_URL") or os.environ.get("OPENAI_BASE_URL") or "https://aigw.netease.com/v1"
+    model = model or os.environ.get("AIGW_GEMINI_MODEL") or DEFAULT_MODEL
+
+    if not api_key:
+        raise RuntimeError("AIGW_GEMINI_API_KEY or OPENAI_API_KEY environment variable required")
+
+    last_error = None
+    for attempt in range(1, max_retries + 1):
+        try:
+            return _generate_image(
+                api_key=api_key,
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                aspect_ratio=aspect_ratio,
+                image_size=image_size,
+                output_dir=output_dir,
+                filename=filename,
+                model=model,
+                base_url=base_url
+            )
+        except Exception as e:
+            last_error = e
+            rate_limited = is_rate_limit_error(e)
+            if rate_limited and attempt < max_retries:
+                delay = retry_delay(attempt, rate_limited)
+                print(f"  ⚠️  Rate limited, retrying in {delay}s... (attempt {attempt}/{max_retries})")
+                time.sleep(delay)
+                continue
+            raise
+
+    raise last_error

package/skills/ppt-master/scripts/image_backends/backend_bfl.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Black Forest Labs FLUX image generation backend.
+
+Configuration keys:
+  BFL_API_KEY   (required)
+  BFL_BASE_URL  (optional)
+  BFL_MODEL     (optional)
+"""
+
+import os
+import time
+
+import requests
+
+from image_backends.backend_common import (
+    MAX_RETRIES,
+    download_image,
+    http_error,
+    is_rate_limit_error,
+    poll_json,
+    require_api_key,
+    resolve_output_path,
+    retry_delay,
+)
+
+
+VALID_ASPECT_RATIOS = [
+    "1:1", "2:3", "3:2", "3:4", "4:3",
+    "4:5", "5:4", "9:16", "16:9", "21:9",
+]
+
+DEFAULT_BASE_URL = "https://api.bfl.ai"
+DEFAULT_MODEL = "flux-pro-1.1-ultra"
+
+MODEL_ENDPOINTS = {
+    "flux-pro-1.1": "/v1/flux-pro-1.1",
+    "flux-pro-1.1-ultra": "/v1/flux-pro-1.1-ultra",
+    "flux-dev": "/v1/flux-dev",
+}
+
+ASPECT_RATIO_TO_DIMENSIONS = {
+    "1:1": (1024, 1024),
+    "2:3": (1024, 1536),
+    "3:2": (1536, 1024),
+    "3:4": (1024, 1365),
+    "4:3": (1365, 1024),
+    "4:5": (1024, 1280),
+    "5:4": (1280, 1024),
+    "9:16": (1024, 1820),
+    "16:9": (1820, 1024),
+    "21:9": (2048, 878),
+}
+
+
+def _submit_request(url: str, headers: dict, payload: dict) -> dict:
+    """Submit a BFL generation request and return the JSON response."""
+    response = requests.post(url, headers=headers, json=payload, timeout=180)
+    if response.status_code != 200:
+        raise http_error(response, "BFL generation request")
+    return response.json()
+
+
+def _generate_image(api_key: str, prompt: str, negative_prompt: str = None,
+                    aspect_ratio: str = "1:1", image_size: str = "1K",
+                    output_dir: str = None, filename: str = None,
+                    model: str = DEFAULT_MODEL, base_url: str = DEFAULT_BASE_URL) -> str:
+    """Generate one image with the Black Forest Labs backend."""
+    del image_size  # BFL quality is primarily controlled by model choice.
+
+    if aspect_ratio not in VALID_ASPECT_RATIOS:
+        raise ValueError(
+            f"Unsupported aspect ratio '{aspect_ratio}' for BFL backend. "
+            f"Supported: {VALID_ASPECT_RATIOS}"
+        )
+
+    normalized_model = model.strip().lower()
+    endpoint = MODEL_ENDPOINTS.get(normalized_model)
+    if not endpoint:
+        supported = sorted(MODEL_ENDPOINTS)
+        raise ValueError(f"Unsupported BFL model '{model}'. Supported: {supported}")
+
+    headers = {
+        "x-key": api_key,
+        "accept": "application/json",
+        "Content-Type": "application/json",
+    }
+
+    final_prompt = prompt
+    if negative_prompt:
+        final_prompt += f"\n\nAvoid the following: {negative_prompt}"
+
+    payload = {
+        "prompt": final_prompt,
+        "prompt_upsampling": False,
+        "output_format": "png",
+    }
+
+    if normalized_model.endswith("-ultra"):
+        payload["aspect_ratio"] = aspect_ratio
+        payload["raw"] = False
+    else:
+        width, height = ASPECT_RATIO_TO_DIMENSIONS[aspect_ratio]
+        payload["width"] = width
+        payload["height"] = height
+
+    url = base_url.rstrip("/") + endpoint
+
+    print("[Black Forest Labs]")
+    print(f"  Model:        {normalized_model}")
+    print(f"  Prompt:       {final_prompt[:120]}{'...' if len(final_prompt) > 120 else ''}")
+    print(f"  Aspect Ratio: {aspect_ratio}")
+    print()
+    print("  ⏳ Submitting request...", end="", flush=True)
+    start = time.time()
+    request_payload = _submit_request(url, headers, payload)
+    elapsed = time.time() - start
+    print(f"\n  ✅ Request accepted ({elapsed:.1f}s)")
+
+    polling_url = request_payload.get("polling_url")
+    if not polling_url:
+        raise RuntimeError(f"BFL response missing polling_url: {request_payload}")
+
+    print("  ⏳ Polling result...")
+    result_payload = poll_json(
+        polling_url,
+        {"x-key": api_key, "accept": "application/json"},
+        status_label="status",
+        ready_values=["Ready"],
+        failed_values=["Error", "Failed", "Request Moderated", "Content Moderated"],
+    )
+
+    image_url = ((result_payload.get("result") or {}).get("sample"))
+    if not image_url:
+        raise RuntimeError(f"BFL result missing sample URL: {result_payload}")
+
+    path = resolve_output_path(prompt, output_dir, filename, ".png")
+    return download_image(image_url, path)
+
+
+def generate(prompt: str, negative_prompt: str = None,
+             aspect_ratio: str = "1:1", image_size: str = "1K",
+             output_dir: str = None, filename: str = None,
+             model: str = None, max_retries: int = MAX_RETRIES) -> str:
+    """Generate an image with retries using the BFL backend."""
+    api_key = require_api_key(
+        "BFL_API_KEY",
+        message="No API key found. Set BFL_API_KEY in the current environment or the project-root .env.",
+    )
+    base_url = os.environ.get("BFL_BASE_URL") or DEFAULT_BASE_URL
+    resolved_model = model or os.environ.get("BFL_MODEL") or DEFAULT_MODEL
+
+    last_error = None
+    for attempt in range(max_retries + 1):
+        try:
+            return _generate_image(
+                api_key=api_key,
+                prompt=prompt,
+                negative_prompt=negative_prompt,
+                aspect_ratio=aspect_ratio,
+                image_size=image_size,
+                output_dir=output_dir,
+                filename=filename,
+                model=resolved_model,
+                base_url=base_url,
+            )
+        except Exception as exc:
+            last_error = exc
+            if attempt >= max_retries:
+                break
+            limited = is_rate_limit_error(exc)
+            delay = retry_delay(attempt, rate_limited=limited)
+            label = "Rate limit hit" if limited else f"Error: {exc}"
+            print(f"\n  ⚠️  {label}. Retrying in {delay}s...")
+            time.sleep(delay)
+
+    raise RuntimeError(f"Failed after {max_retries + 1} attempts. Last error: {last_error}")