antigravity-seo-kit 2.0.0

package/extensions/banana/install.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Banana Image Generation Extension Installer for SEO Kit
+# Wraps everything in main() to prevent partial execution on network failure
+
+main() {
+    SKILL_DIR=".agent/skills/seo-image-gen"
+    AGENT_DIR=".agent/skills"
+    SEO_SKILL_DIR=".agent/skills/seo"
+    SETTINGS_FILE="MCP_settings_path"
+
+    echo "════════════════════════════════════════"
+    echo "║  Banana Image Gen - SEO Extension    ║"
+    echo "║  For SEO Kit                      ║"
+    echo "════════════════════════════════════════"
+    echo ""
+
+    # Check prerequisites
+    if [ ! -d "${SEO_SKILL_DIR}" ]; then
+        echo "✗ SEO Kit is not installed."
+        echo "  Install it first: curl -fsSL https://raw.githubusercontent.com/AgriciDaniel/seo-kit/main/install.sh | bash"
+        exit 1
+    fi
+    echo "✓ SEO Kit detected"
+
+    if ! command -v node >/dev/null 2>&1; then
+        echo "✗ Node.js is required but not installed."
+        echo "  Install Node.js 20+: https://nodejs.org/"
+        exit 1
+    fi
+
+    NODE_VERSION=$(node -v | sed 's/v//' | cut -d. -f1)
+    if [ "${NODE_VERSION}" -lt 20 ]; then
+        echo "✗ Node.js 20+ required (found v${NODE_VERSION})."
+        echo "  Update: https://nodejs.org/"
+        exit 1
+    fi
+    echo "✓ Node.js v$(node -v | sed 's/v//') detected"
+
+    if ! command -v npx >/dev/null 2>&1; then
+        echo "✗ npx is required but not found (comes with npm)."
+        exit 1
+    fi
+    echo "✓ npx detected"
+
+    # Determine script directory (works for both ./install.sh and repo-relative paths)
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+    # Check if running from repo or standalone
+    if [ -f "${SCRIPT_DIR}/skills/seo-image-gen/SKILL.md" ]; then
+        SOURCE_DIR="${SCRIPT_DIR}"
+    elif [ -f "${SCRIPT_DIR}/extensions/banana/skills/seo-image-gen/SKILL.md" ]; then
+        SOURCE_DIR="${SCRIPT_DIR}/extensions/banana"
+    else
+        echo "✗ Cannot find extension source files."
+        echo "  Run this script from the seo-kit repo: ./extensions/banana/install.sh"
+        exit 1
+    fi
+
+    # Check if nanobanana-mcp is already configured
+    MCP_CONFIGURED=false
+    if [ -f "${SETTINGS_FILE}" ]; then
+        if python3 -c "
+import json
+with open('${SETTINGS_FILE}', 'r') as f:
+    settings = json.load(f)
+if 'mcpServers' in settings and 'nanobanana-mcp' in settings['mcpServers']:
+    exit(0)
+else:
+    exit(1)
+" 2>/dev/null; then
+            MCP_CONFIGURED=true
+            echo "✓ nanobanana-mcp already configured in settings.json"
+        fi
+    fi
+
+    # If MCP not configured, prompt for API key
+    if [ "${MCP_CONFIGURED}" = false ]; then
+        echo ""
+        echo "Google AI API key required for image generation."
+        echo "Get a free key at: https://aistudio.google.com/apikey"
+        echo ""
+
+        read -rsp "Google AI API key (GOOGLE_AI_API_KEY): " GOOGLE_AI_API_KEY
+        echo ""
+        if [ -z "${GOOGLE_AI_API_KEY}" ]; then
+            echo "✗ API key cannot be empty."
+            exit 1
+        fi
+
+        # Configure MCP server
+        echo "→ Configuring nanobanana-mcp server..."
+        python3 -c "
+import json, os
+
+settings_path = '${SETTINGS_FILE}'
+
+# Read existing settings or create new
+if os.path.exists(settings_path):
+    with open(settings_path, 'r') as f:
+        settings = json.load(f)
+else:
+    settings = {}
+
+# Ensure mcpServers key exists
+if 'mcpServers' not in settings:
+    settings['mcpServers'] = {}
+
+# Add nanobanana-mcp server config
+settings['mcpServers']['nanobanana-mcp'] = {
+    'command': 'npx',
+    'args': ['-y', '@ycse/nanobanana-mcp@latest'],
+    'env': {
+        'GOOGLE_AI_API_KEY': '''${GOOGLE_AI_API_KEY}'''
+    }
+}
+
+# Write back
+os.makedirs(os.path.dirname(settings_path), exist_ok=True)
+with open(settings_path, 'w') as f:
+    json.dump(settings, f, indent=2)
+
+print('  ✓ nanobanana-mcp configured in settings.json')
+" || {
+            echo "✗ Could not auto-configure MCP server."
+            echo "  See: extensions/banana/docs/BANANA-SETUP.md"
+            exit 1
+        }
+    fi
+
+    # Install skill
+    echo ""
+    echo "→ Installing seo-image-gen skill..."
+    mkdir -p "${SKILL_DIR}"
+    cp "${SOURCE_DIR}/skills/seo-image-gen/SKILL.md" "${SKILL_DIR}/SKILL.md"
+
+    # Install agent
+    echo "→ Installing seo-image-gen agent..."
+    mkdir -p "${AGENT_DIR}"
+    cp "${SOURCE_DIR}/agents/seo-image-gen.md" "${AGENT_DIR}/seo-image-gen.md"
+
+    # Copy scripts and references to skill directory for ${CLAUDE_SKILL_DIR} resolution
+    echo "→ Installing scripts and references..."
+    mkdir -p "${SKILL_DIR}/scripts" "${SKILL_DIR}/references"
+    cp "${SOURCE_DIR}/scripts/"*.py "${SKILL_DIR}/scripts/"
+    cp "${SOURCE_DIR}/references/"*.md "${SKILL_DIR}/references/"
+
+    # Pre-warm npx package
+    echo "→ Pre-downloading nanobanana-mcp..."
+    npx -y @ycse/nanobanana-mcp@latest --help >/dev/null 2>&1 || true
+
+    echo ""
+    echo "✓ Banana Image Generation extension installed successfully!"
+    echo ""
+    echo "Usage:"
+    echo "  1. Open your workspace in your AI agent"
+    echo "  2. Run commands:"
+    echo "     /seo image-gen og \"Professional SaaS dashboard\""
+    echo "     /seo image-gen hero \"Dramatic sunset over city skyline\""
+    echo "     /seo image-gen product \"Wireless headphones on marble\""
+    echo "     /seo image-gen infographic \"SEO ranking factors 2026\""
+    echo "     /seo image-gen custom \"Any creative concept\""
+    echo "     /seo image-gen batch \"Product variations\" 3"
+    echo ""
+    echo "Full docs: extensions/banana/README.md"
+    echo "To uninstall: ./extensions/banana/uninstall.sh"
+}
+
+main "$@"

package/extensions/banana/references/cost-tracking.md

@@ -0,0 +1,47 @@
+# Cost Tracking Reference
+
+> Load this on-demand when the user asks about costs or before batch operations.
+
+## Pricing Table
+
+| Model | Resolution | Cost/Image | Notes |
+|-------|-----------|-----------|-------|
+| 3.1 Flash | 512 | $0.020 | Quick drafts |
+| 3.1 Flash | 1K | $0.039 | Standard (default) |
+| 3.1 Flash | 2K | $0.078 | Quality assets |
+| 3.1 Flash | 4K | $0.156 | Print/hero images |
+| 2.5 Flash | 512 | $0.020 | Draft fallback |
+| 2.5 Flash | 1K | $0.039 | Standard fallback |
+| Batch API | Any | 50% of above | Asynchronous, higher latency |
+
+Pricing is approximate, based on ~1,290 output tokens per image.
+Research suggests actual costs may be ~$0.067/img. Verify at https://ai.google.dev/gemini-api/docs/pricing
+
+## Free Tier Limits
+
+- ~10 requests per minute (RPM)
+- ~500 requests per day (RPD)
+- Per Google Cloud project, resets midnight Pacific
+
+## Cost Tracker Commands
+
+```bash
+# Log a generation
+cost_tracker.py log --model gemini-3.1-flash-image-preview --resolution 1K --prompt "coffee shop hero"
+
+# View summary (total + last 7 days)
+cost_tracker.py summary
+
+# Today's usage
+cost_tracker.py today
+
+# Estimate before batch
+cost_tracker.py estimate --model gemini-3.1-flash-image-preview --resolution 1K --count 10
+
+# Reset ledger
+cost_tracker.py reset --confirm
+```
+
+## Storage
+
+Ledger stored at `~/.banana/costs.json`. Created automatically on first use.

package/extensions/banana/references/gemini-models.md

@@ -0,0 +1,200 @@
+# Gemini Image Generation Models
+
+> Last updated: 2026-03-13
+> Aligned with Google's March 2026 API state
+
+## Available Models
+
+### gemini-3.1-flash-image-preview (Recommended)
+| Property | Value |
+|----------|-------|
+| **Model ID** | `gemini-3.1-flash-image-preview` |
+| **Tier** | Nano Banana 2 (Flash) |
+| **Speed** | Fast - optimized for high-volume use |
+| **Aspect Ratios** | All 14 ratios (see table below) |
+| **Max Resolution** | Up to 4096×4096 (4K tier) |
+| **Features** | Google Search grounding (web + image), thinking levels, image-only output, extreme aspect ratios |
+| **Rate Limits (Free)** | ~10 RPM / ~500 RPD (per Google Cloud project, resets midnight Pacific) |
+| **Output Tokens** | ~1,290 output tokens per image |
+| **Best For** | Most use cases, rapid iteration, batch generation |
+
+### gemini-2.5-flash-image
+| Property | Value |
+|----------|-------|
+| **Model ID** | `gemini-2.5-flash-image` |
+| **Tier** | Nano Banana 2 (Flash, previous gen) |
+| **Speed** | Fast |
+| **Aspect Ratios** | 1:1, 16:9, 9:16, 4:3, 3:4 |
+| **Max Resolution** | Up to 1024×1024 (1K tier) |
+| **Rate Limits (Free)** | ~10 RPM / ~500 RPD |
+| **Best For** | Stable fallback, proven quality |
+
+## Deprecated Models (DO NOT USE)
+
+### gemini-3-pro-image-preview
+- **Status:** Base model deprecated March 9, 2026. **Image generation variant may still be accessible**. Use at your own discretion via `set_model`. Prefer 3.1 Flash.
+- **Was:** Nano Banana Pro tier (professional asset production, 4K output, 14 reference images)
+- **Migration:** Use `gemini-3.1-flash-image-preview` instead
+
+### gemini-2.0-flash-exp
+- **Status:** Deprecated, replaced by gemini-2.5-flash-image
+
+## Aspect Ratios
+
+All 14 supported ratios. Availability varies by model:
+
+| Ratio | Orientation | Use Cases | 3.1 Flash | 2.5 Flash |
+|-------|-------------|-----------|:---------:|:---------:|
+| `1:1` | Square | Social posts, avatars, thumbnails | ✅ | ✅ |
+| `16:9` | Landscape | Blog headers, YouTube thumbnails, presentations | ✅ | ✅ |
+| `9:16` | Portrait | Stories, Reels, TikTok, mobile | ✅ | ✅ |
+| `4:3` | Landscape | Product shots, classic display | ✅ | ✅ |
+| `3:4` | Portrait | Book covers, portrait framing | ✅ | ✅ |
+| `2:3` | Portrait | Pinterest pins, posters | ✅ | ❌ |
+| `3:2` | Landscape | DSLR standard, photo prints | ✅ | ❌ |
+| `4:5` | Portrait | Instagram portrait, social | ✅ | ❌ |
+| `5:4` | Landscape | Large format photography | ✅ | ❌ |
+| `1:4` | Tall strip | Vertical banners, side panels | ✅ | ❌ |
+| `4:1` | Wide strip | Website banners, headers | ✅ | ❌ |
+| `1:8` | Extreme tall | Narrow vertical strips | ✅ | ❌ |
+| `8:1` | Extreme wide | Ultra-wide banners | ✅ | ❌ |
+| `21:9` | Ultra-wide | Cinematic, film-grade, ultra-wide monitors | ✅ | ❌ |
+
+## Resolution Tiers
+
+Control output resolution with the `imageSize` parameter. Note the **uppercase K** requirement.
+
+| `imageSize` Value | Pixel Range | Model Availability | Use Case |
+|-------------------|-------------|-------------------|----------|
+| `512` | Up to 512×512 | All models | Drafts, quick iteration, low bandwidth |
+| `1K` (default) | Up to 1024×1024 | All models | Standard web use, social media |
+| `2K` | Up to 2048×2048 | 3.1 Flash | Quality assets, detailed work |
+| `4K` | Up to 4096×4096 | 3.1 Flash | Print production, hero images, final assets |
+
+**Notes:**
+- Actual pixel dimensions depend on aspect ratio (e.g., 4K at 16:9 = 4096×2304)
+- Higher resolutions consume more tokens and cost more
+- Default is `1K` if `imageSize` is not specified
+
+## API Configuration
+
+### Endpoint
+```
+https://generativelanguage.googleapis.com/v1beta/models/{model-id}:generateContent
+```
+
+### Required Parameters
+```json
+{
+  "contents": [{"parts": [{"text": "your prompt here"}]}],
+  "generationConfig": {
+    "responseModalities": ["TEXT", "IMAGE"],
+    "imageConfig": {
+      "aspectRatio": "16:9",
+      "imageSize": "1K"
+    }
+  }
+}
+```
+
+### Image-Only Output Mode
+Force the model to return only an image (no text response):
+```json
+{
+  "generationConfig": {
+    "responseModalities": ["IMAGE"]
+  }
+}
+```
+
+### Thinking Level
+Control how much the model "thinks" before generating. Higher levels improve complex compositions but increase latency:
+```json
+{
+  "generationConfig": {
+    "thinkingConfig": {
+      "thinkingLevel": "medium"
+    }
+  }
+}
+```
+Levels: `minimal`, `low`, `medium`, `high`
+
+### Google Search Grounding
+Ground generation in real-world visual references. Supports web and image search (3.1 Flash):
+```json
+{
+  "tools": [{"googleSearch": {}}]
+}
+```
+**Prompt pattern:** `[Search/source request] + [Analytical task] + [Visual translation]`
+
+Example: "Search for the latest SpaceX Starship design, analyze its proportions and markings, then generate a photorealistic image of it at sunset on the launch pad."
+
+### Multi-Image Input
+Up to 14 reference images can be provided:
+- **10 object references**: for style, composition, or visual matching
+- **4 character references**: assign distinct names to preserve features across generations
+
+Useful for character consistency, style transfer, and brand-aligned generation.
+
+## Rate Limits by Tier
+
+| Tier | RPM | RPD | Notes |
+|------|-----|-----|-------|
+| Free | ~10 | ~500 | Per Google Cloud project, resets midnight Pacific. Reduced Dec 2025. |
+| Pay-as-you-go | 30 | 10,000 | Production workloads |
+| Enterprise | Custom | Custom | Contact Google |
+
+## Pricing
+
+| Model | Resolution | Cost per Image | Notes |
+|-------|-----------|---------------|-------|
+| 3.1 Flash | 1K | ~$0.039 | Standard |
+| 3.1 Flash | 2K | ~$0.078 | 2× standard |
+| 3.1 Flash | 4K | ~$0.156 | 4× standard |
+| 2.5 Flash | 1K | ~$0.039 | Standard |
+| Batch API | Any | 50% discount | Asynchronous, higher latency |
+
+Pricing is approximate and based on ~1,290 output tokens per image.
+Research suggests NB2 pricing may be ~$0.067/img (vs documented $0.039). Verify current pricing at https://ai.google.dev/gemini-api/docs/pricing
+
+## Image Output Specs
+
+| Property | Value |
+|----------|-------|
+| **Format** | PNG |
+| **Max Resolution** | Up to 4096×4096 (4K tier, 3.1 Flash) |
+| **Color Space** | sRGB |
+| **Text Rendering** | Supported - best under 25 characters |
+| **Style Control** | Via prompt engineering |
+
+## Safety Filters
+
+Gemini uses a two-layer safety architecture:
+
+1. **Input filters**: block prompts containing prohibited content before generation
+2. **Output filters**: analyze generated images and block unsafe results
+
+| `finishReason` | Meaning | Retryable? |
+|----------------|---------|:----------:|
+| `STOP` | Successful generation | N/A |
+| `IMAGE_SAFETY` | Output blocked by safety filter | Rephrase prompt |
+| `PROHIBITED_CONTENT` | Content policy violation | No - topic is blocked |
+| `SAFETY` | General safety block | Rephrase prompt |
+| `RECITATION` | Detected copyrighted content | Rephrase prompt |
+
+**Known issue:** Filters are known to be overly cautious. Benign prompts may be blocked. Iterate with rephrased wording if this happens.
+
+## Content Credentials
+
+- **SynthID watermarks** are always embedded in generated images (invisible, machine-readable)
+- **C2PA metadata** is included on Pro/paid outputs (verifiable provenance chain)
+
+## Key Limitations
+- No video generation (image only)
+- No transparent backgrounds (PNG but always with background)
+- Text rendering quality varies; keep text under 25 characters for best results
+- Safety filters may block some prompts (violence, NSFW, public figures), known to be overly cautious
+- Session context resets between your AI agent conversations
+- `imageSize` and thinking level depend on MCP package version support

package/extensions/banana/references/mcp-tools.md

@@ -0,0 +1,115 @@
+# MCP Tools Reference: @ycse/nanobanana-mcp
+
+> Package: `@ycse/nanobanana-mcp`
+> GitHub: https://github.com/YCSE/nanobanana-mcp
+
+## Tools
+
+### gemini_generate_image
+Generate an image from a text prompt.
+
+**Parameters:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `prompt` | string | Yes | Text description of the image to generate |
+
+**Returns:** Image data + file path (saved to `~/Documents/nanobanana_generated/`)
+
+**Example usage in your AI agent:**
+```
+User: "Generate a sunset over mountains in watercolor style"
+→ Claude calls gemini_generate_image with prompt
+→ Returns image path and description
+```
+
+### gemini_edit_image
+Edit an existing image with text instructions.
+
+**Parameters:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `imagePath` | string | Yes | Path to the image file to edit |
+| `prompt` | string | Yes | Edit instructions |
+
+**Returns:** Modified image data + file path
+
+**Example:**
+```
+User: "Remove the background from ~/Documents/photo.png"
+→ Claude calls gemini_edit_image with path and instruction
+```
+
+### gemini_chat
+Multi-turn visual conversation maintaining session context.
+
+**Parameters:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `message` | string | Yes | Chat message (can reference previous images) |
+
+**Returns:** Text response + optional image
+
+**Key feature:** Session consistency, which maintains style, characters, and context across turns. Great for iterative refinement.
+
+### set_aspect_ratio
+Configure the aspect ratio for subsequent image generations.
+
+**Parameters:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `ratio` | string | Yes | Aspect ratio (e.g., "16:9", "1:1", "9:16") |
+
+**Supported ratios:** 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 1:4, 4:1, 1:8, 8:1, 21:9
+
+### set_model
+Switch the active Gemini model.
+
+**Parameters:**
+| Param | Type | Required | Description |
+|-------|------|----------|-------------|
+| `model` | string | Yes | Model identifier |
+
+**Available models:**
+- `gemini-3.1-flash-image-preview` (default, recommended)
+- `gemini-2.5-flash-image` (stable fallback)
+
+### get_image_history
+Retrieve list of images generated in the current session.
+
+**Parameters:** None
+
+**Returns:** Array of image entries with paths and prompts
+
+### clear_conversation
+Reset session context and conversation history.
+
+**Parameters:** None
+
+**Returns:** Confirmation of reset
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GOOGLE_AI_API_KEY` | Yes | API key from https://aistudio.google.com/apikey |
+| `NANOBANANA_MODEL` | No | Override default model (default: `gemini-3.1-flash-image-preview`) |
+
+## Output Directory
+All generated images are saved to: `~/Documents/nanobanana_generated/`
+
+Images are named with timestamps for easy identification.
+
+## Feature Availability via MCP
+
+Some newer Gemini API features depend on the MCP package version of `@ycse/nanobanana-mcp`. Check the package version to confirm support:
+
+| Feature | API Status | MCP Support |
+|---------|-----------|-------------|
+| `imageSize` (resolution control) | Available | Depends on package version |
+| Thinking level (`thinkingConfig`) | Available | Depends on package version |
+| Search grounding (`googleSearch`) | Available | Depends on package version |
+| Image-only output (`responseModalities: ["IMAGE"]`) | Available | Depends on package version |
+| Multi-image input (up to 14 refs) | Available | Via `gemini_chat` with image paths |
+| All 14 aspect ratios | Available | Via `set_aspect_ratio` |
+
+If a feature is not yet supported by the MCP package, you can still use it via direct API calls with `curl` or the Google AI SDK.