# 🍌 Google Flow Automation Suite (Nano Banana 2 & Omni Flash)

<div align="center">

<p align="center">
  <img src="assets/banner.webp" alt="Google Flow Automation Suite Banner" width="100%" style="border-radius: 10px; margin-bottom: 16px;">
</p>

[![CI](https://github.com/omid-io/google-flow-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/omid-io/google-flow-suite/actions)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://python.org)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110%2B-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![FastMCP](https://img.shields.io/badge/FastMCP-Server-8A2BE2?style=for-the-badge)](https://github.com/jlowin/fastmcp)
[![Chrome MV3](https://img.shields.io/badge/Chrome-MV3%20Extension-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white)](https://developer.chrome.com/docs/extensions/mv3/)
[![Playwright](https://img.shields.io/badge/Playwright-CDP%20Driver-2EAD33?style=for-the-badge&logo=playwright&logoColor=white)](https://playwright.dev)
[![Tests](https://img.shields.io/badge/Tests-462%20Passing-success?style=for-the-badge&logo=pytest&logoColor=white)](https://pytest.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)

### The Production-Grade Media Automation Platform & Developer Suite for Google Flow
High-speed Chrome CDP session attachment, headless MV3 Direct API proxying, REST API webhooks, mathematical Shimmer Fix validation, SQLite asset catalog, and 50 golden prompt presets for **Nano Banana 2** image generation & **Omni Flash / Veo 3.1** video generation.

[✨ Key Features](#-key-features) • [🏗️ Architecture](#️-architecture) • [🚀 Quick Start](#-quick-start) • [📟 CLI](#-command-line-interface-cli) • [🌐 REST API & Webhooks](#-rest-api--webhooks-fastapi) • [🎨 Golden Presets](#-50-golden-presets-library) • [🐍 Python SDK](#-python-sdk) • [🤖 FastMCP](#-fastmcp-server-for-ai-agents) • [🧩 Chrome Extension](#-chrome-mv3-extension-setup) • [🇮🇷 راهنمای جامع فارسی](#-راهنمای-جامع-فارسی-iranian-developer-guide)

</div>

---

## ✨ Key Features

- **⚡ Unified Dual-Engine Architecture:**
  - **Engine A (Direct API Bridge):** Chrome MV3 background proxy solving `window.grecaptcha.enterprise` in-DOM and intercepting Bearer tokens for high-throughput headless batching (`aisandbox-pa.googleapis.com`).
  - **Engine B (Zero-Friction CDP):** Attaches directly to your active, logged-in browser session via Playwright without closing Chrome or re-authenticating.
- **🌐 FastAPI REST API & Webhook Server (`flow-suite serve`):**
  - Instant HTTP bridge for **n8n**, **Telegram bots**, and external webhooks with interactive Swagger docs at `/docs`.
- **🗄️ SQLite Asset Catalog & History Tracker (`flow-suite history`):**
  - Automatically records generated assets, prompts, models, and metadata into a local `flow_catalog.sqlite3` database.
- **🎨 50 Golden Prompt Presets (`flow-suite presets`):**
  - Curated, production-tested prompt formulas across 5 domains (Software Architecture, Instagram Dynamic Reels, Luxury Salon Aesthetics, 3D Isometric UI, and Typographic Posters).
- **🛡️ The Shimmer Fix (Contrast StdDev $\sigma \ge 15.0$):**
  - 4-stage mathematical validator (Resolution Gate $\ge 1000\text{px}$, File Size $\ge 100\text{KB}$, Grayscale Standard Deviation $\sigma \ge 15.0$, Dynamic Range $\Delta V \ge 100$) preventing premature download of blurry placeholder cards.
- **🎬 Omni Flash & Veo 3.1 High-Impact Video:**
  - Full support for Text-to-Video (`t2v`), Image-to-Video (`i2v` frame chaining), 6-DOF camera motion vocabulary (`pan`, `tilt`, `zoom`, `orbit`), and reference entity tracking (`reference_media_id`).
- **🔒 Credit Safety Lock:**
  - Pre-flight guard preventing accidental consumption of expensive video credits during image requests.
- **⌨️ Slate.js Synthetic Typing:**
  - Sequential keystroke simulation with micro-delays to reliably activate the React-controlled Create button (`aria-disabled="false"`).
- **🧹 Canvas Auto-Cleanup:**
  - Automatic media URL diffing and deletion of generated cards to prevent workspace clutter and asset collision.

---

## 🏗️ Architecture

```mermaid
flowchart TD
    subgraph Interfaces["💻 Developer Interfaces"]
        CLI["📟 CLI Tool<br/><b>flow-suite</b>"]
        REST["🌐 REST API / Webhooks<br/><b>FastAPI (Port 8767)</b>"]
        SDK["🐍 Python SDK<br/><b>FlowClient / AsyncFlowClient</b>"]
        MCP["🤖 FastMCP Server<br/><b>flow_generate_image / video</b>"]
    end

    subgraph Core["⚡ Core Orchestrator"]
        Router["🎯 Unified Routing & Engine Fallback"]
        Catalog["🗄️ SQLite Asset Catalog<br/><b>flow_catalog.sqlite3</b>"]
        Presets["🎨 50 Golden Presets<br/><b>examples/golden_prompts.json</b>"]
    end

    subgraph Engines["🚀 Dual-Engine Execution Layer"]
        subgraph EngineA["Engine A: Direct API Bridge"]
            MV3["🧩 MV3 Chrome Extension<br/>(reCAPTCHA & Bearer Sniffer)"]
            Bridge["🔌 Local JSON-RPC Bridge<br/>(ws://127.0.0.1:8766)"]
            DirectAPI["🌐 aisandbox-pa.googleapis.com<br/>(Direct Batch API)"]
        end

        subgraph EngineB["Engine B: CDP / Browser Driver"]
            CDP["🎮 Playwright CDP Driver<br/>(Attach to Port 9222 / 2360)"]
            Slate["⌨️ Slate.js Synthetic Typer<br/>(Keystroke Simulator)"]
            InContext["📥 In-Context Cookie Fetch<br/>(Preserves Session State)"]
        end
    end

    subgraph Safety["🛡️ Reliability & Safety Guard"]
        Shimmer["🔬 The Shimmer Fix<br/>(Contrast StdDev σ ≥ 15.0 & W ≥ 1000px)"]
        CreditLock["🔒 Credit Safety Lock<br/>(Anti-Burn Video Guard)"]
        CanvasClean["🧹 Canvas State Tracker<br/>(Media Diff & Auto-Cleanup)"]
    end

    subgraph Pipelines["🎬 Media Pipeline & Post-Processing"]
        ImagePipe["🍌 Nano Banana 2<br/>(16:9 / 4:3 Image Pipeline)"]
        VideoPipe["⚡ Omni Flash / Veo 3.1<br/>(6-DOF Camera & i2v Chaining)"]
        PostProc["✨ Progressive JPEG & MP4<br/>(Metadata & Provenance Embedder)"]
    end

    Interfaces --> Router
    Router --> Catalog
    Router --> Presets
    Router --> EngineA
    Router --> EngineB
    MV3 --> Bridge --> DirectAPI
    CDP --> Slate --> InContext
    DirectAPI --> Safety
    InContext --> Safety
    Safety --> Pipelines
    Pipelines --> Output[("📦 Final Verified Assets")]

    classDef interface fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#fff;
    classDef core fill:#0f172a,stroke:#a855f7,stroke-width:2px,color:#fff;
    classDef engine fill:#1e1e2e,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef safety fill:#181825,stroke:#22c55e,stroke-width:2px,color:#fff;
    classDef pipeline fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fff;

    class CLI,REST,SDK,MCP interface;
    class Router,Catalog,Presets core;
    class MV3,Bridge,DirectAPI,CDP,Slate,InContext engine;
    class Shimmer,CreditLock,CanvasClean safety;
    class ImagePipe,VideoPipe,PostProc pipeline;
```

---

## 🚀 Quick Start

### 1. Installation

```bash
# Clone repository
git clone https://github.com/omid-io/google-flow-suite.git
cd google-flow-suite

# Create virtual environment
python -m venv .venv

# On Windows (PowerShell):
.\.venv\Scripts\Activate.ps1

# On Linux/macOS:
# source .venv/bin/activate

# Install with all enterprise dependencies
pip install -e ".[all]"
```

### 2. Verify Installation

```bash
flow-suite --version
flow-suite diagnostics
```

---

## 📟 Command Line Interface (CLI)

### Generate Images (Nano Banana 2)

```bash
# 16:9 Landscape Banner with Cinematic Preset
flow-suite generate "A futuristic developer desk with neon cyan fiber optics" --aspect-ratio 16:9 --style cinematic --output banner.jpg

# 4:3 Classical Composition
flow-suite generate "Luxury perfume bottle on Italian marble with morning sunlight" --aspect-ratio 4:3 --output perfume.jpg
```

### Generate High-Impact Videos (Omni Flash / Veo 3.1)

```bash
# Text-to-Video with Camera Zoom
flow-suite video "FPV drone racing through neon cyberpunk skyscrapers at night" --camera-motion zoom_in --model omni-flash --output drone.mp4

# Image-to-Video (Chaining from previously generated image)
flow-suite video "Animate water waves and golden reflections" --camera-motion pan_right --reference-media-id media_img_01_a9f8 --output animated.mp4
```

### Generation History & Presets

```bash
# View recent generation history from local SQLite catalog
flow-suite history --limit 10

# List golden prompt presets
flow-suite presets

# Filter presets by category (software_engineering, instagram_reels, commercial_luxury_products, isometric_3d_ui, typographic_marketing)
flow-suite presets --category instagram_reels
```

### Start REST API Server

```bash
# Launch FastAPI server on port 8767 for n8n & Telegram webhooks
flow-suite serve --port 8767
```

---

## 🌐 REST API & Webhooks (FastAPI)

Start the local server with `flow-suite serve` and access interactive Swagger documentation at `http://127.0.0.1:8767/docs`:

### Endpoints:
- `POST /v1/images/generate`: Generate 16:9 / 4:3 images with Nano Banana 2.
- `POST /v1/videos/generate`: Render high-impact dynamic videos with Omni Flash / Veo 3.1.
- `GET /v1/status/{task_id}`: Poll asynchronous rendering status.
- `GET /v1/history`: Retrieve paginated asset history from SQLite catalog.
- `POST /v1/webhooks/events`: Receive external worker callbacks.
- `GET /health`: Service health check and author metadata.

```bash
# Example curl request to generate an image
curl -X POST "http://127.0.0.1:8767/v1/images/generate"      -H "Content-Type: application/json"      -d '{"prompt": "Isometric quantum core router labeled MCP glowing with cyan lasers", "aspect_ratio": "16:9"}'
```

---

## 🎨 50 Golden Presets Library

The suite includes 50 production-grade prompts in [`examples/golden_prompts.json`](examples/golden_prompts.json) across 5 categories:

1. **Software Engineering & Cloud Architecture (16:9):** MCP routers, Kubernetes mesh, clean code desks, agent swarms.
2. **Instagram Dynamic Reels & Shorts (9:16 Omni Flash):** FPV drone rush, hypercar drift, liquid gold slow-motion, space nebulas.
3. **Commercial Luxury Products & Cosmetics (16:9 Studio):** VIP facial suites, keratin silk hair, 24k gold serums, royal bridal hair.
4. **3D Isometric Futuristic UI & Quantum Systems:** Supercomputer racks, glassy fintech dashboards, blockchain nodes.
5. **Typographic Marketing Posters:** Bold in-image headline typography in Persian and English with quotes.

---

## 🐍 Python SDK

### Synchronous Client (`FlowClient`)

```python
from google_flow_suite import FlowClient

with FlowClient() as client:
    # 1. Generate High-Res Image
    img = client.generate_image(
        prompt="Modern luxury salon interior with dark slate and warm gold accents",
        aspect_ratio="16:9",
        style_preset="cinematic"
    )
    print(f"Image Created: {img.url}")

    # 2. Generate Omni Flash Video
    vid = client.generate_video(
        prompt="Slow motion water droplet falling with crystal ripples",
        camera_motion="zoom_in",
        model="omni-flash"
    )
    print(f"Video Created: {vid.url}")
```

### Asynchronous Client (`AsyncFlowClient`)

```python
import asyncio
from google_flow_suite import AsyncFlowClient

async def main():
    async with AsyncFlowClient() as client:
        result = await client.generate_image(
            prompt="Isometric server rack glowing with quantum light",
            aspect_ratio="16:9"
        )
        print(f"Asset ID: {result.media_id}")

asyncio.run(main())
```

---

## 🤖 FastMCP Server for AI Agents

Connect Google Flow directly into **Antigravity**, **Claude Desktop**, and **Cursor** using FastMCP:

### Configuration (`claude_desktop_config.json` or `mcp_config.json`)

```json
{
  "mcpServers": {
    "google-flow-suite": {
      "command": "python",
      "args": ["-m", "google_flow_suite.mcp.server"]
    }
  }
}
```

---

## 🧩 Chrome MV3 Extension Setup

The repository includes a ready-to-load Manifest V3 Chrome extension located in the [`extension/`](extension) directory:

1. Open Google Chrome and navigate to:
   ```text
   chrome://extensions
   ```
2. In the top-right corner, toggle **Developer mode** to **ON**.
3. Click the **Load unpacked** button in the top-left corner.
4. Select the `extension` folder inside this repository (`google-flow-suite/extension`).
5. Open Google Flow (`https://labs.google/fx/tools/flow`).
6. The extension will automatically solve `window.grecaptcha.enterprise` challenges and communicate with your local Python environment via WebSocket on `ws://127.0.0.1:8766`.

---

## 🧪 Comprehensive Test Suite (462/462 Passed)

The suite is exhaustively verified across **462 unit, mock, integration, and adversarial stress tests**:

```bash
pytest -v
```

| Test Tier | Focus Area | Test Count | Status |
| :--- | :--- | :--- | :--- |
| **Tier 1: Units** | Config, Models, Prompt Compiler, Shimmer Math | 96 tests | ✅ 100% Passed |
| **Tier 2: Engines** | CDP Driver Mock, Credit Guard, Direct API Client | 16 tests | ✅ 100% Passed |
| **Tier 3: Interfaces** | CLI, FastMCP Server, FastAPI REST Server, Catalog DB, Presets, Python SDK | 28 tests | ✅ 100% Passed |
| **Tier 4: E2E Pipelines** | Image, Video, Post-processing Workflows | 8 tests | ✅ 100% Passed |
| **Tier 5: Adversarial** | Deep Stress, Lifecycle, Chaos Shimmer, Resilience | 314 tests | ✅ 100% Passed |

---

## 🇮🇷 راهنمای جامع فارسی (Iranian Developer Guide)

پروژه **Google Flow Automation Suite v0.2.0** یک پلتفرم استاندارد صنعتی و جامع برای اتوماسیون کامل سرویس **Google Flow** است. این ابزار به توسعه‌دهندگان، تولیدکنندگان محتوا و متخصصان هوش مصنوعی این امکان را می‌دهد که بدون نیاز به کلیک‌های دستی در مرورگر، از قدرتمندترین مدل‌های گوگل یعنی **Nano Banana 2** (تولید تصویر با کیفیت خیره‌کننده) و **⚡ Omni Flash / Veo 3.1** (تولید ویدیوهای سینمایی پرتحرک) در کدهای پایتون، خط فرمان (CLI)، سرور وب REST API، پایپ‌لاین‌های n8n، یا از طریق دستیارهای هوش مصنوعی (مانند Claude و Antigravity) استفاده کنند.

---

### 🌟 امکانات و قابلیت‌های کلیدی:

1. **🌐 وب‌سرور REST API و وب‌هوک (`flow-suite serve`):** اتصال مستقیم به **n8n**، ربات‌های تلگرام و کلاینت‌های شبکه با داکیومنت تعاملی Swagger در `http://127.0.0.1:8767/docs`.
2. **🗄️ کاتالوگ دیتابیس لوکال SQLite (`flow-suite history`):** ذخیره خودکار تمام پرامپت‌ها، تصاویر و ویدیوهای رندرشده در دیتابیس `flow_catalog.sqlite3`.
3. **🎨 بانک ۵۰ پرامپت طلایی و لایبرری پریست‌ها (`flow-suite presets`):** ۵۰ فرمول تست‌شده در ۵ دسته‌بندی (معماری نرم‌افزار، ریلزهای داینامیک اینستاگرام، عکاسی استودیویی محصولات لوکس، موکاپ‌های سه‌بعدی، پوسترهای متنی فارسی و انگلیسی).
4. **حل قطعی باگ ابروبادی (The Shimmer Fix):** بررسی انحراف معیار کنتراست ($\sigma \ge 15.0$) و ابعاد، مانع از ذخیره فایل‌های تار شده و دقیقاً خروجی شفاف نهایی را استخراج می‌کند.
5. **مدل پیش‌فرض ویدیو ⚡ Omni Flash:** تنظیم شده برای تولید ویدیوهای سرعتی و داینامیک با پشتیبانی کامل از ابعاد **۱۶:۹ افقی (یوتیوب و وب‌سایت)** و **۹:۱۶ عمودی (ریلز و استوری اینستاگرام)**.
6. **قفل ایمنی کردیت (Credit Safety Lock):** جلوگیری از مصرف ناخواسته کردیت‌های گران‌قیمت ویدیو هنگام درخواست‌های تولید تصویر.
7. **🚀 لانچر ۱-کلیک ویندوز (`run_chrome_debug.bat`):** اجرای فوری کروم در حالت دیباگ بدون نیاز به تایپ دستور در ترمینال.

---

### 🧩 راهنمای گام‌به‌گام نصب افزونه اختصاصی کروم:

1. مرورگر **Google Chrome** را باز کنید و آدرس `chrome://extensions` را وارد نمایید.
2. در گوشه بالا سمت راست، گزینه **Developer mode** را روشن (**ON**) کنید.
3. در گوشه بالا سمت چپ، روی دکمه **Load unpacked** کلیک کنید.
4. پوشه `extension` داخل مخزن این پروژه (`google-flow-suite/extension`) را انتخاب کنید.
5. وارد صفحه گوگل فلو شوید (`https://labs.google/fx/tools/flow`). افزونه با نشان سبز فعال شده و به پایتون متصل می‌گردد.

---

### 🚀 دستورات پرکاربرد خط فرمان:

```bash
# ۱. تولید عکس ۱۶:۹ با مدل Nano Banana 2
flow-suite generate "طراحی اتاق کار برنامه‌نویسی مدرن با نورپردازی نئون فیروزه‌ای" --aspect-ratio 16:9 --output cover.jpg

# ۲. تولید ویدیو با حرکت زوم دوربین با Omni Flash
flow-suite video "پرواز پرسرعت پهپاد از میان آسمان‌خراش‌های نورانی در شب بارانی" --camera-motion zoom_in --output drone.mp4

# ۳. مشاهده تاریخچه کارهای تولیدشده در دیتابیس SQLite
flow-suite history --limit 10

# ۴. مشاهده و جستجو در لیست ۵۰ پرامپت طلایی
flow-suite presets --category instagram_reels

# ۵. اجرای وب‌سرور محلی برای اتصال به n8n و تلگرام
flow-suite serve --port 8767
```

---

## 📄 License

Distributed under the **MIT License**. See `LICENSE` for details.

Crafted with ❤️ by **[Omid Zaferi (@omid-io)](https://github.com/omid-io)**