@leejungkiin/awkit 1.6.6 → 1.7.0

package/skills/short-maker/scripts/google-flow-cli/README.md

@@ -1,168 +1,280 @@
-# gflow — CLI for Google Flow
+# Google Flow CLI (gflow)
 
-A command-line interface to [Google Flow](https://flow.google) (AI image & video generation), built using the same reverse-engineering approach as [tmc/nlm](https://github.com/tmc/nlm) for NotebookLM.
+> Reverse-engineered CLI for Google's [Flow](https://labs.google/fx/tools/flow) — **Imagen 4** image generation and **Veo 3.1** video generation, powered by the same APIs as the web UI.
 
-Lets AI agents and scripts generate images/videos via Google Flow without the GUI.
+## 🚀 Quick Start
 
-## Architecture
+```bash
+# 1. Activate virtual environment
+cd /path/to/google-flow-cli
+source .venv/bin/activate
+
+# 2. Authenticate (opens Chrome for Google login)
+gflow auth
+
+# 3. Generate an image
+gflow generate-image "a cute owl doctor mascot, chibi style" --json
 
+# 4. Generate a video
+gflow generate-video "a cat walking through a garden" --wait
 ```
-┌────────────────────────────────────┐
-│  CLI Layer (click)                 │  gflow/cli/main.py
-│  generate-image, generate-video,   │
-│  list, download, collections, raw  │
-├────────────────────────────────────┤
-│  API Client (FlowClient)          │  gflow/api/client.py
-│  High-level ops, polling, parsing  │
-├────────────────────────────────────┤
-│  BatchExecute Protocol            │  gflow/batchexecute/client.py
-│  RPC encoding, SAPISIDHASH,       │
-│  chunked response decoding         │
-├────────────────────────────────────┤
-│  Browser Auth                     │  gflow/auth/browser_auth.py
-│  Cookie extraction from Chrome,    │
-│  Selenium interactive login        │
-└────────────────────────────────────┘
+
+## 📦 Installation
+
+```bash
+# Clone and setup
+pip install -e .
+
+# Or just use the venv binary directly
+.venv/bin/gflow --help
 ```
 
-This is the same layered architecture as `tmc/nlm`:
-- **Auth** extracts Google cookies from your browser (browser_cookie3 or Selenium)
-- **BatchExecute** encodes RPCs into Google's wire format and decodes responses
-- **API Client** wraps BatchExecute with typed methods for each Flow feature
-- **CLI** exposes everything as clean subcommands
+## 🔐 Authentication
 
-## Install
+gflow uses Chrome browser cookies for authentication. A persistent Chrome instance runs in the background for reCAPTCHA solving.
 
 ```bash
-pip install -e .
+# First-time auth (opens Chrome, login with your Google account)
+gflow auth
+
+# Clear and re-authenticate (when getting 401 errors)
+gflow auth --clear
+gflow auth
+
+# Close background Chrome when done
+gflow close
 ```
 
-Or with optional Selenium support for interactive login:
+**Requirements:**
+- Google Chrome installed
+- A Google account with access to [labs.google/fx](https://labs.google/fx)
+- Chrome must stay running in background (for reCAPTCHA tokens)
+
+## 🎨 Image Generation
+
+### Basic Usage
+
 ```bash
-pip install -e ".[dev]"
-pip install selenium
+# Simple generation
+gflow generate-image "a sunset over mountains"
+
+# With options
+gflow generate-image "cute robot mascot" \
+  --aspect-ratio 1:1 \
+  --num 4 \
+  -m imagen4 \
+  --json
 ```
 
-## Quick Start
+### Options
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--aspect-ratio` | `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `square`, `portrait`, `landscape` | `landscape` | Image aspect ratio |
+| `--num` | `1-4` | `1` | Number of images to generate |
+| `-m`, `--model` | `imagen4`, `nano-banana-2` | `imagen4` | Image generation model |
+| `-i`, `--image` | path | — | Reference image for image-to-image |
+| `-o`, `--output` | path | auto | Output file path |
+| `--seed` | integer | random | Seed for reproducibility |
+| `--project-id` | string | — | Reuse existing project (skip creation) |
+| `--json` | flag | — | Output as JSON |
+
+### Models
+
+| Model | Internal Name | Description |
+|-------|---------------|-------------|
+| `imagen4` | `NARWHAL` | Imagen 4 — highest quality, default |
+| `nano-banana-2` | `NANOBANANA2` | Nano Banana 2 — faster, lower cost |
+
+### Image-to-Image (Reference)
+
+Use `-i` to provide a reference image. The model will generate variations based on your image + prompt:
 
 ```bash
-# 1. Authenticate (extracts cookies from your Chrome browser)
-gflow auth
+# Generate a variation of an existing character
+gflow generate-image "same character but smiling" -i ./base-mascot.png
 
-# 2. Generate an image
-gflow generate-image "a cat astronaut floating in space"
+# Style transfer
+gflow generate-image "pixel art style" -i ./photo.jpg --aspect-ratio 1:1
+```
+
+### Project Reuse
 
-# 3. Generate a video
-gflow generate-video "a timelapse of a flower blooming"
+By default, each CLI invocation creates a new Flow project. To avoid this overhead, pass `--project-id`:
 
-# 4. List your assets
-gflow list
+```bash
+# First call — note the projectId in JSON output
+gflow generate-image "owl mascot" --json
+# Output: { "images": [...], "projectId": "abc123" }
 
-# 5. Download an asset
-gflow download <asset-id> -o output.png
+# Subsequent calls — reuse the project
+gflow generate-image "same owl but dancing" --project-id abc123 -i owl.png --json
 ```
 
-## Setup: Discovering RPC IDs
+This is especially useful in automation (like Mascot Studio) where many images are generated for the same character.
 
-Google Flow uses the same BatchExecute protocol as NotebookLM, but with different RPC endpoint IDs. You need to discover these by inspecting network traffic:
+## 🎬 Video Generation
 
-1. Open [flow.google](https://flow.google) in Chrome
-2. Open DevTools → Network tab
-3. Filter requests by `batchexecute`
-4. Perform an action (e.g., generate an image)
-5. In the request payload, find the `rpcids` parameter — that's the RPC ID
-6. Update `gflow/api/rpc_ids.py` with the real ID
+### Text-to-Video
 
-Check which IDs are configured:
 ```bash
-gflow rpc-ids
+# Generate and wait for completion
+gflow generate-video "a cat walking through a sunlit garden" --wait
+
+# With options
+gflow generate-video "a spaceship launching" \
+  --aspect-ratio 16:9 \
+  --seed 42 \
+  -o spaceship.mp4 \
+  --json
 ```
 
-Use raw mode to test discovered IDs:
+### Image-to-Video
+
 ```bash
-gflow raw "xYz123" --args '["my prompt", "16:9"]'
+# Use an image as the starting frame
+gflow generate-video "the character starts walking" -i character.png --wait
 ```
 
-## Commands
+### Video Extension
 
-| Command | Description |
-|---------|-------------|
-| `gflow auth` | Authenticate with Google Flow |
-| `gflow auth --status` | Check auth status |
-| `gflow auth --clear` | Clear saved credentials |
-| `gflow generate-image PROMPT` | Generate images (Imagen 4) |
-| `gflow generate-video PROMPT` | Generate videos (Veo 3.1) |
-| `gflow list` | List assets in your library |
-| `gflow get ASSET_ID` | Get asset details |
-| `gflow download ASSET_ID` | Download an asset |
-| `gflow delete ASSET_ID` | Delete an asset |
-| `gflow collections list` | List collections |
-| `gflow collections create NAME` | Create a collection |
-| `gflow collections add COL_ID ASSET_ID` | Add asset to collection |
-| `gflow raw RPC_ID` | Execute raw RPC (discovery mode) |
-| `gflow rpc-ids` | Show configured RPC IDs |
+```bash
+# Extend an existing video
+gflow extend-video "the character turns around and waves" \
+  --media-id <media_id_from_previous_generation> \
+  --wait
+```
 
-All commands support `--json` for machine-readable output (ideal for scripts/agents).
+### Video Options
 
-## Environment Variables
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--aspect-ratio` | `16:9`, `9:16`, `1:1` | `landscape` | Video aspect ratio |
+| `--seed` | integer | random | Seed for reproducibility |
+| `--wait/--no-wait` | flag | `--wait` | Wait for rendering to complete |
+| `--timeout` | seconds | `300` | Max wait time |
+| `-i`, `--image` | path | — | Starting frame image |
+| `-o`, `--output` | path | auto | Output file path |
+| `--json` | flag | — | Output as JSON |
 
-| Variable | Description |
-|----------|-------------|
-| `GFLOW_AUTH_TOKEN` | Auth token (overrides saved credentials) |
-| `GFLOW_COOKIES` | Cookie string (overrides saved credentials) |
-| `GFLOW_CHROME_PATH` | Path to Chrome executable |
-| `GFLOW_DEBUG` | Set to `true` for debug output |
+## 🔧 Utility Commands
 
-## For AI Agents / Scripts
+### Network Sniffer
 
-Every command supports `--json` output:
+Discover what APIs Flow uses by capturing network traffic:
 
 ```bash
-# Generate and get JSON response
-gflow generate-image "a logo" --json | jq '.[0].url'
-
-# List assets as JSON for processing
-gflow list --type image --json | jq '.[].id'
+# Capture for 2 minutes (default)
+gflow sniff
 
-# Pipeline: generate, wait, download
-ASSET_ID=$(gflow generate-video "ocean waves" --json | jq -r '.[0].id')
-gflow download "$ASSET_ID" -o waves.mp4
+# Custom duration and output
+gflow sniff --duration 300 -o my-capture.json
 ```
 
-## How It Works (Same as tmc/nlm)
+### Debug Mode
 
-1. **Browser Auth**: Extracts Google cookies from Chrome/Brave/Edge profiles using `browser_cookie3`, then fetches the XSRF token from the Flow page HTML
-2. **BatchExecute Protocol**: Encodes RPC calls into Google's `batchexecute` wire format — form-encoded POST with nested JSON arrays, SAPISIDHASH authorization header
-3. **Response Decoding**: Parses Google's chunked response format (byte-count prefixed JSON chunks with `wrb.fr` markers and multi-layer JSON encoding)
-4. **Retry Logic**: Exponential backoff for transient errors (429, 500, 502, 503, 504)
+Add `--debug` before any command for verbose logging:
 
-## Project Structure
+```bash
+gflow --debug generate-image "test prompt"
+```
+
+## 🏗️ Architecture
 
 ```
-gflow-py/
-├── pyproject.toml              # Package config & dependencies
-├── README.md
+google-flow-cli/
 ├── gflow/
-│   ├── __init__.py
-│   ├── auth/
-│   │   ├── __init__.py
-│   │   └── browser_auth.py     # Cookie extraction & Selenium login
-│   ├── batchexecute/
-│   │   ├── __init__.py
-│   │   └── client.py           # Google BatchExecute protocol
 │   ├── api/
-│   │   ├── __init__.py
-│   │   ├── client.py           # FlowClient (high-level API)
-│   │   ├── models.py           # Pydantic models (Asset, Collection, etc.)
-│   │   └── rpc_ids.py          # RPC endpoint IDs (fill these in!)
+│   │   ├── client.py      # FlowClient — core API interactions
+│   │   └── models.py       # Pydantic data models
+│   ├── auth/
+│   │   ├── browser_auth.py # Chrome cookie/token management
+│   │   └── recaptcha.py    # reCAPTCHA Enterprise solver
 │   └── cli/
-│       ├── __init__.py
-│       └── main.py             # Click CLI commands
-└── tests/
-    ├── __init__.py
-    └── test_batchexecute.py    # Unit tests
+│       └── main.py         # Click CLI commands
+├── pyproject.toml           # Package config
+└── README.md                # This file
+```
+
+### API Endpoints (Reverse-Engineered)
+
+| Endpoint | Purpose |
+|----------|---------|
+| `labs.google/fx/api/trpc/project.createProject` | Create a Flow project |
+| `aisandbox-pa.googleapis.com/v1/projects/{pid}/flowMedia:batchGenerateImages` | Image generation |
+| `aisandbox-pa.googleapis.com/v1/video:batchAsyncGenerateVideoText` | Video generation |
+| `aisandbox-pa.googleapis.com/v1/video:batchCheckAsyncVideoGenerationStatus` | Video polling |
+| `labs.google/fx/api/auth/session` | Session/auth management |
+
+### Authentication Flow
+
+1. Chrome opens `labs.google/fx` with remote debugging
+2. User logs in with Google account
+3. Cookies are captured from Chrome via CDP
+4. Access token is obtained from `/auth/session`
+5. reCAPTCHA tokens are solved via Chrome's embedded reCAPTCHA
+6. API calls use Bearer token (sandbox) + Cookies (labs)
+
+## ⚠️ Troubleshooting
+
+### `401 Unauthorized`
+```bash
+gflow auth --clear
+gflow auth
+```
+Re-authenticate. This happens when cookies/tokens expire.
+
+### `No CDP WebSocket available`
+Chrome isn't running or crashed. Start it again:
+```bash
+gflow auth
+```
+
+### `reCAPTCHA evaluation failed`
+- Ensure Chrome is on the Flow page (`labs.google/fx`)
+- Wait 30-60 seconds and retry
+- If persistent: `gflow auth --clear && gflow auth`, then manually interact with Flow page
+
+### `LibreSSL warning`
+Harmless warning on macOS. The CLI works fine with LibreSSL.
+
+## 📝 Integration Examples
+
+### Mascot Studio (Vite Proxy)
+
+The Mascot Studio web app uses gflow via a Vite dev server proxy:
+
+```typescript
+// POST /api/gflow/generate
+{
+  "prompt": "cute owl mascot",
+  "model": "imagen4",           // optional
+  "aspectRatio": "1:1",         // optional
+  "num": 4,                     // optional (1-4)
+  "baseImageBase64": "data:..." // optional (reference image)
+}
+```
+
+### Shell Script Batch Generation
+
+```bash
+#!/bin/bash
+PROMPT="cute robot mascot"
+PROJECT_ID=""
+
+# Generate base
+RESULT=$(gflow generate-image "$PROMPT" --num 4 --json)
+PROJECT_ID=$(echo $RESULT | jq -r '.projectId')
+
+# Generate states using same project
+for state in "happy" "sad" "excited" "sleeping"; do
+  gflow generate-image "$PROMPT in $state state" \
+    --project-id $PROJECT_ID \
+    -i base.png \
+    -o "${state}.png"
+done
 ```
 
-## License
+## 📄 License
 
-MIT
+Internal tool — not for public distribution. Uses Google's internal APIs which may change without notice.

package/skills/short-maker/scripts/google-flow-cli/gflow/api/client.py

@@ -49,10 +49,22 @@ SANDBOX_BASE = "https://aisandbox-pa.googleapis.com"
 LABS_BASE = "https://labs.google/fx/api"
 
 # Internal model names (discovered from sniff)
-IMAGE_MODEL = "NARWHAL"  # Imagen 4 internal name
+# Flow UI shows friendly names; API uses internal codenames.
+# NARWHAL = Imagen 4 (default, highest quality)
+# NANOBANANA2 = Nano Banana 2 (faster, lower cost)
+IMAGE_MODEL = "NARWHAL"  # Imagen 4 internal name (default)
 VIDEO_MODEL = "veo_3_1_t2v_fast_ultra"  # Veo 3.1 fast/ultra (text-to-video)
 TOOL_NAME = "PINHOLE"  # Flow's internal tool name
 
+# Image model mapping: friendly name -> API internal name
+IMAGE_MODEL_MAP = {
+    "imagen4": "NARWHAL",
+    "narwhal": "NARWHAL",
+    "nano-banana-2": "NANOBANANA2",
+    "nanobanana2": "NANOBANANA2",
+    "banana": "NANOBANANA2",
+}
+
 # I2V model mapping by aspect ratio (discovered from network sniff)
 I2V_MODEL_MAP = {
     "landscape": "veo_3_1_i2v_s_fast_ultra",
@@ -69,6 +81,7 @@ IMAGE_ASPECT_MAP = {
     "1:1": "IMAGE_ASPECT_RATIO_SQUARE",
     "portrait": "IMAGE_ASPECT_RATIO_PORTRAIT",
     "9:16": "IMAGE_ASPECT_RATIO_PORTRAIT",
+    "3:4": "IMAGE_ASPECT_RATIO_PORTRAIT_THREE_FOUR",
     "landscape": "IMAGE_ASPECT_RATIO_LANDSCAPE",
     "16:9": "IMAGE_ASPECT_RATIO_LANDSCAPE",
     "4:3": "IMAGE_ASPECT_RATIO_LANDSCAPE_FOUR_THREE",
@@ -684,7 +697,7 @@ class FlowClient:
 
     def generate_image(self, req: GenerateImageRequest) -> list[Asset]:
         """
-        Generate images using Imagen 4 (NARWHAL).
+        Generate images using the specified model (default: Imagen 4 / NARWHAL).
 
         POST /v1/projects/{pid}/flowMedia:batchGenerateImages
         """
@@ -695,11 +708,20 @@ class FlowClient:
         aspect = IMAGE_ASPECT_MAP.get(req.aspect_ratio.lower(), "IMAGE_ASPECT_RATIO_LANDSCAPE")
         seed = req.seed if req.seed is not None else random.randint(10000, 99999)
 
+        # Resolve model name
+        model_name = IMAGE_MODEL  # default
+        if req.model:
+            model_name = IMAGE_MODEL_MAP.get(req.model.lower(), req.model.upper())
+
         def _do_generate():
             recaptcha_token = self._get_recaptcha_token()
             client_ctx = self._build_client_context(project_id, recaptcha_token)
             batch_id = str(uuid.uuid4())
 
+            media_id = None
+            if req.image:
+                media_id = self.upload_image(req.image)
+
             payload = {
                 "clientContext": client_ctx,
                 "mediaGenerationContext": {"batchId": batch_id},
@@ -709,7 +731,7 @@ class FlowClient:
             for i in range(req.num_images):
                 img_req = {
                     "clientContext": client_ctx,
-                    "imageModelName": IMAGE_MODEL,
+                    "imageModelName": model_name,
                     "imageAspectRatio": aspect,
                     "structuredPrompt": {
                         "parts": [{"text": req.prompt}],
@@ -717,6 +739,13 @@ class FlowClient:
                     "seed": seed + i,
                     "imageInputs": [],
                 }
+                
+                if media_id:
+                    img_req["imageInputs"].append({
+                        "imageInputType": "IMAGE_INPUT_TYPE_BASE_IMAGE",
+                        "name": media_id
+                    })
+                    
                 payload["requests"].append(img_req)
 
             if self.debug:

package/skills/short-maker/scripts/google-flow-cli/gflow/api/models.py

@@ -36,11 +36,13 @@ class Asset(BaseModel):
 
 
 class GenerateImageRequest(BaseModel):
-    """Request to generate images using Imagen 4."""
+    """Request to generate images using Imagen 4 or other models."""
     prompt: str
-    aspect_ratio: str = "landscape"  # square, portrait, landscape, 4:3
+    aspect_ratio: str = "landscape"  # square, portrait, landscape, 4:3, 3:4
     seed: int | None = None
     num_images: int = 1  # Number of images to generate (1-8)
+    image: str | None = None  # Path to image for reference (image-to-image)
+    model: str | None = None  # Model name: imagen4, nano-banana-2 (default: imagen4)
 
 
 class GenerateVideoRequest(BaseModel):

package/skills/short-maker/scripts/google-flow-cli/gflow/cli/main.py

@@ -140,29 +140,56 @@ def close_browser(ctx):
 @cli.command("generate-image")
 @click.argument("prompt")
 @click.option("--aspect-ratio", default="landscape",
-              type=click.Choice(["square", "portrait", "landscape", "4:3", "1:1", "16:9", "9:16"]),
+              type=click.Choice(["square", "portrait", "landscape", "4:3", "3:4", "1:1", "16:9", "9:16"]),
               help="Image aspect ratio")
 @click.option("--seed", default=None, type=int, help="Random seed for reproducibility")
-@click.option("--num", default=1, type=click.IntRange(1, 8), help="Number of images (1-8)")
+@click.option("--num", default=1, type=click.IntRange(1, 4), help="Number of images (1-4)")
 @click.option("-o", "--output", default=None, help="Output file path (auto-named if omitted)")
+@click.option("-i", "--image", default=None, help="Reference base image path (image-to-image)")
+@click.option("--project-id", default=None, help="Reuse an existing project ID (skip project creation)")
+@click.option("-m", "--model", default=None,
+              type=click.Choice(["imagen4", "nano-banana-2"], case_sensitive=False),
+              help="Image model (default: imagen4)")
 @click.option("--json", "as_json", is_flag=True, help="Output as JSON")
 @click.pass_context
-def generate_image(ctx, prompt, aspect_ratio, seed, num, output, as_json):
-    """Generate images from a text prompt using Imagen 4.
+def generate_image(ctx, prompt, aspect_ratio, seed, num, output, image, project_id, model, as_json):
+    """Generate images from a text prompt.
+
+    \b
+    Models:
+        imagen4        — Imagen 4 (NARWHAL) highest quality (default)
+        nano-banana-2  — Nano Banana 2, faster generation
 
     \b
     Examples:
         gflow generate-image "a cat astronaut floating in space"
-        gflow generate-image "sunset over mountains" --aspect-ratio landscape --num 4
+        gflow generate-image "sunset" --aspect-ratio 1:1 --num 4
         gflow generate-image "logo design" --aspect-ratio square -o logo.png
+        gflow generate-image "cute owl" -m nano-banana-2
+        gflow generate-image "make the character smile" -i base.png
+        gflow generate-image "prompt" --project-id abc123  (reuse project)
     """
     client = _get_client(ctx.obj["debug"])
 
+    # Set project ID if provided (skip project creation)
+    if project_id:
+        client._project_id = project_id
+
+    # Validate image path if provided
+    if image:
+        img_path = Path(image)
+        if not img_path.exists():
+            console.print(f"[red]Error: Image file not found:[/red] {image}")
+            sys.exit(1)
+        image = str(img_path.resolve())  # Use absolute path
+
     req = GenerateImageRequest(
         prompt=prompt,
         aspect_ratio=aspect_ratio,
         seed=seed,
         num_images=num,
+        image=image,
+        model=model,
     )
 
     try:
@@ -206,7 +233,7 @@ def generate_image(ctx, prompt, aspect_ratio, seed, num, output, as_json):
                 enc = d["raw"]["encodedImage"]
                 d["raw"]["encodedImage"] = f"<{len(enc)} chars base64>"
             result.append(d)
-        click.echo(json.dumps({"images": result, "saved_files": saved_files}, indent=2))
+        click.echo(json.dumps({"images": result, "saved_files": saved_files, "projectId": client._project_id}, indent=2))
     else:
         console.print(f"\n[bold]Generated {len(assets)} image(s)[/bold] for: {prompt}")
 

package/skills/short-maker/scripts/google-flow-cli/pyproject.toml

@@ -8,7 +8,7 @@ version = "0.1.0"
 description = "A command-line interface to Google Flow (AI image & video generation)"
 readme = "README.md"
 license = {text = "MIT"}
-requires-python = ">=3.10"
+requires-python = ">=3.9"
 dependencies = [
     "requests>=2.31",
     "click>=8.1",