vrex-flow-engine 0.2.0__tar.gz

vrex_flow_engine-0.2.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: vrex-flow-engine
+Version: 0.2.0
+Summary: Launcher + supervisor and OpenAI-compatible image/video generation service (Vrex Flow Engine).
+Author: Vrex
+License: Proprietary
+Project-URL: Homepage, https://getvrex.com
+Keywords: vrex,flow-engine,cli,supervisor,image-generation,video-generation
+Classifier: Programming Language :: Python :: 3
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: posthog>=3.8
+Requires-Dist: rich>=13.7
+
+# vrex-flow-engine
+
+One-command launcher + supervisor for the **Vrex Flow Engine** — a self-hosted
+service that exposes OpenAI-compatible image/video generation endpoints.
+
+`vrex-flow-engine start` stores your engine key + Cloudflare tunnel token,
+launches the engine and the tunnel as supervised child processes (with
+crash-restart), and renders a live status dashboard.
+
+## Quickstart
+
+```bash
+uvx vrex-flow-engine start
+```
+
+First run prompts for the engine API key and the Cloudflare tunnel token (saved
+to `~/.vrex-flow/config.json`, chmod 600), then brings up the engine + tunnel.
+Ctrl-C stops both cleanly.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only. |
+| `vrex-flow-engine setup` | Store the engine key + tunnel token. |
+| `vrex-flow-engine doctor` | Check prerequisites and probe a running engine. |
+| `vrex-flow-engine serve` | Run just the engine in the foreground. |
+
+The short alias `flow-engine` is installed for the same commands.
+
+## Requirements
+
+- Python 3.10+
+- [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
+  (for the tunnel; `--no-tunnel` skips it)
+- Access to a Vrex Flow Engine deployment.
+
+Internal Vrex tooling.

vrex_flow_engine-0.2.0/PYPI_README.md

@@ -0,0 +1,38 @@
+# vrex-flow-engine
+
+One-command launcher + supervisor for the **Vrex Flow Engine** — a self-hosted
+service that exposes OpenAI-compatible image/video generation endpoints.
+
+`vrex-flow-engine start` stores your engine key + Cloudflare tunnel token,
+launches the engine and the tunnel as supervised child processes (with
+crash-restart), and renders a live status dashboard.
+
+## Quickstart
+
+```bash
+uvx vrex-flow-engine start
+```
+
+First run prompts for the engine API key and the Cloudflare tunnel token (saved
+to `~/.vrex-flow/config.json`, chmod 600), then brings up the engine + tunnel.
+Ctrl-C stops both cleanly.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vrex-flow-engine start` | Run engine + tunnel with a live dashboard. `--no-tunnel` runs the engine only. |
+| `vrex-flow-engine setup` | Store the engine key + tunnel token. |
+| `vrex-flow-engine doctor` | Check prerequisites and probe a running engine. |
+| `vrex-flow-engine serve` | Run just the engine in the foreground. |
+
+The short alias `flow-engine` is installed for the same commands.
+
+## Requirements
+
+- Python 3.10+
+- [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
+  (for the tunnel; `--no-tunnel` skips it)
+- Access to a Vrex Flow Engine deployment.
+
+Internal Vrex tooling.

vrex_flow_engine-0.2.0/README.md

@@ -0,0 +1,259 @@
+# flow-engine
+
+Host a **Google Flow browser-extension instance** and expose **OpenAI-compatible
+image/video generation endpoints** backed by Google Flow (labs.google).
+
+flow-engine drives a Chrome extension that borrows your authenticated Flow
+session (token + cookies + reCAPTCHA solving) and proxies Flow's private
+`aisandbox-pa.googleapis.com` calls, mapping the results onto familiar OpenAI
+request/response shapes. Python package `flow-engine`, import module
+`flow_engine`, console command `flow-engine` (subcommands: `start`, `serve`,
+`setup`, `doctor`).
+
+```
+OpenAI client ──HTTP :8101──> flow-engine ──WS :9223──> Chrome extension ──fetch──> Google Flow
+                               (this repo)               (extension/, in your browser)
+```
+
+In production the HTTP surface is published at `https://flow.getvrex.com`
+(a `cloudflared` tunnel → `127.0.0.1:8101`); the Next.js app reaches it via
+`FLOW_ENGINE_URL`. See "Expose to production" below.
+
+## Endpoints
+
+- `POST /v1/images/generations` — synchronous image (Nano Banana 2).
+- `POST /v1/videos/generations` + `GET /v1/videos/{id}` — async video job + poll (Veo 3.1 lite).
+- `GET /v1/videos/{id}/debug` — raw `{dispatch, last_poll}` Google payloads for a job (troubleshooting).
+- `POST /v1/flow/uploads` — image **or video** bytes → Flow media id (routes by mime).
+- `GET /v1/models` — model catalog (cached on disk, refresh with `?refresh=1`).
+- `GET /media/{id}` — cached generated bytes at a stable URL.
+- `GET /api/health` — liveness + extension-connected status (ungated).
+
+`/v1/*` and `/api/pool/status` require `Authorization: Bearer <FLOW_ENGINE_API_KEY>`.
+`/api/health` and `/media/{id}` are ungated.
+
+## Requirements
+
+- Python 3.10+
+- Google Chrome signed in to **labs.google** with a Flow tab open, and the
+  extension in `extension/` loaded (chrome://extensions → Load unpacked).
+- A Flow account (Pro or Ultra — the paygate tier is read from your session).
+- `cloudflared` (only for exposing to production).
+
+> The extension's `background.js` hardcodes `ws://127.0.0.1:9223` and
+> `http://127.0.0.1:8101/api/ext/callback`, so flow-engine defaults to those
+> ports. It therefore **cannot run alongside the legacy flowboard agent on
+> defaults** — change both the env vars and the extension URLs to run both.
+
+## Quickstart — one command
+
+`flow-engine start` is a supervisor: it stores your secrets, launches the engine
+**and** the Cloudflare tunnel as child processes, restarts either on crash, and
+renders a live status dashboard. Run it with [uv](https://docs.astral.sh/uv/)
+(the Python equivalent of `npx` — no manual venv):
+
+```bash
+# from the monorepo (until published to PyPI):
+uvx --from 'git+ssh://git@github.com/getvrex/multimodal.git#subdirectory=flow-engine' flow-engine start
+
+# once published: uvx flow-engine start
+```
+
+First run prompts for the **engine API key** (must match the value the Next.js
+app sends — `FLOW_ENGINE_API_KEY` on Vrex Multimodal / `.env.prd`) and the
+**Cloudflare tunnel token** (dashboard → Zero Trust → Networks → Tunnels → your
+tunnel → "run a connector"). Both are saved to `~/.vrex-flow/config.json` (0600)
+so later runs need no input. Then it brings up the engine + tunnel and shows:
+
+```
+🎬 Vrex Flow Engine   ● running   uptime 3m02s
+┌ engine ──────────────┐ ┌ tunnel ───────────────┐
+│ status     ● UP       │ │ status  ● connected    │
+│ extension  ● connected│ │ public  flow.getvrex.com│
+│ instances  1          │ │ →       127.0.0.1:8101  │
+└──────────────────────┘ └───────────────────────┘
+```
+
+The one thing the CLI can't automate: open a `labs.google/fx/tools/flow` tab in
+Chrome with the `extension/` loaded and signed into a Flow Pro/Ultra account.
+Until you do, the dashboard shows `extension ● OPEN A FLOW TAB`. Ctrl-C stops
+both processes cleanly.
+
+### CLI commands
+
+| Command | What it does |
+|---|---|
+| `flow-engine start` | Supervise engine + tunnel + live dashboard (the one-liner). `--no-tunnel` runs the engine only; `--non-interactive` fails instead of prompting. |
+| `flow-engine setup` | (Re)store the engine key + tunnel token in `~/.vrex-flow/config.json`. |
+| `flow-engine doctor` | Check prerequisites (python, cloudflared, config) and probe a running engine. |
+| `flow-engine serve` | Run just the engine in the foreground (for systemd / your own supervisor). |
+
+Secrets can also come from env (`FLOW_ENGINE_API_KEY`, `CLOUDFLARE_TUNNEL_TOKEN`)
+or flags (`--engine-key`, `--tunnel-token`) — flags > env > stored config.
+
+## Run manually (without the CLI)
+
+The engine reads config from the environment directly — **no `.env` auto-load**.
+`FLOW_ENGINE_API_KEY` is **required**; the server refuses to boot without it.
+
+```bash
+cd flow-engine
+python -m venv .venv && source .venv/bin/activate
+pip install -e .
+export FLOW_ENGINE_API_KEY=<shared-secret>     # must match the caller's key
+flow-engine serve                              # serves :8101 (HTTP) + :9223 (WS)
+# equivalent: python -m flow_engine.main
+```
+
+Load `extension/` in Chrome, open a `labs.google/fx/tools/flow` tab, then check:
+
+```bash
+curl localhost:8101/api/health
+# {"ok":true,"extension_connected":true,"instances":1}
+```
+
+`extension_connected:false` means no Flow tab/extension is bridged yet — open
+the tab and reload the extension.
+
+## Expose to production (Cloudflare Tunnel)
+
+The public origin `https://flow.getvrex.com` is a `cloudflared` tunnel to the
+local `:8101`. **`flow-engine start` runs this tunnel for you** (via the stored
+token), so normally you don't touch `cloudflared` directly. To run it standalone
+— e.g. the `serve` path — start the tunnel as a separate process on the same
+machine:
+
+```bash
+cloudflared tunnel run --token <your-tunnel-token>   # flow.getvrex.com → 127.0.0.1:8101
+# or, with a named-tunnel config file:
+cloudflared tunnel run --config cloudflared.yml
+```
+
+If `https://flow.getvrex.com` returns **HTTP 530 / `error code: 1033`**, the
+tunnel is down (Cloudflare has no active connection to the origin) — restart it
+(or `flow-engine start`). A `502`/`1016` instead means the tunnel is up but the
+engine on `:8101` is not — restart the engine.
+
+## Examples
+
+Image (`model` must be `NANO_BANANA_2`, or omit to force it):
+
+```bash
+curl localhost:8101/v1/images/generations \
+  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
+  -H 'content-type: application/json' -d '{
+  "prompt": "a studio portrait, soft light", "n": 2,
+  "size": "1024x1024", "model": "NANO_BANANA_2"
+}'
+# {"created":..., "data":[{"url":"http://127.0.0.1:8101/media/<uuid>"}, ...]}
+```
+
+Video (`model` must be `veo_3_1_lite_low_priority`). Text-to-video:
+
+```bash
+JOB=$(curl -s localhost:8101/v1/videos/generations \
+  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
+  -H 'content-type: application/json' -d '{
+    "prompt": "slow dolly in over a city at dusk",
+    "model": "veo_3_1_lite_low_priority", "seconds": 8, "size": "1280x720"
+  }' | jq -r .id)
+curl -s localhost:8101/v1/videos/$JOB \
+  -H "authorization: Bearer $FLOW_ENGINE_API_KEY"   # poll until status == "completed"
+```
+
+Image-to-video — pass the start frame inline; flow-engine uploads it for you:
+
+```bash
+curl localhost:8101/v1/videos/generations \
+  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
+  -H 'content-type: application/json' -d "{
+    \"prompt\": \"the subject turns to camera\", \"model\": \"veo_3_1_lite_low_priority\",
+    \"start_images\": [\"$(base64 < frame.png)\"], \"size\": \"1280x720\"
+  }"
+```
+
+`start_images` / `ref_images` accept a data URL, an `http(s)` URL, or bare
+base64. Already have a Flow media id (e.g. from `/v1/flow/uploads`)? Pass it in
+`start_media_ids` / `ref_media_ids` instead — the two forms merge. Uploading a
+reference **video** (for v2v/edit/extend) works the same way via
+`/v1/flow/uploads -F file=@clip.mp4`, which returns a `"kind":"video"` media id.
+
+Extend or edit a clip you already generated — pass back the `media_id` you got
+and flow-engine resolves the rest (scene / workflow / frame count) from what it
+remembered this run:
+
+```bash
+# extend (continue a Veo clip — only Veo-generated videos can be extended)
+curl localhost:8101/v1/videos/generations \
+  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
+  -H 'content-type: application/json' -d '{
+  "prompt": "a dog joins in", "mode": "extend",
+  "model": "veo_3_1_lite_low_priority", "source_media_id": "<prev media_id>"
+}'
+
+# edit (video-to-video rewrite)
+curl localhost:8101/v1/videos/generations \
+  -H "authorization: Bearer $FLOW_ENGINE_API_KEY" \
+  -H 'content-type: application/json' -d '{
+  "prompt": "add a green ball", "mode": "edit",
+  "model": "veo_3_1_lite_low_priority", "source_media_id": "<prev media_id>",
+  "source_seconds": 8
+}'
+```
+
+For a source flow-engine didn't generate this run (e.g. after a restart), pass
+`workflow_id` explicitly (extend resolves the scene from it; edit uses it
+directly) — plus `source_seconds` for edit so the frame range matches. The
+generation-context registry is in-memory, so it resets when the server restarts.
+
+## Configuration
+
+These configure the **engine** process (read from its environment). The
+`flow-engine start` launcher injects `FLOW_ENGINE_API_KEY` + ports for you from
+`~/.vrex-flow/config.json`; set these directly only for the manual `serve` path.
+All optional except the API key. Port/host/storage vars keep the `FLOWPROXY_`
+prefix for extension compatibility; the API key and pool size use the
+`FLOW_ENGINE_` / `FLOW_POOL_` names.
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `FLOW_ENGINE_API_KEY` | — (**required**) | Bearer key gating `/v1/*`. Legacy `FLOWPROXY_API_KEY` still accepted. |
+| `FLOWPROXY_HTTP_PORT` | `8101` | HTTP surface (OpenAI endpoints + `/media` + callback). |
+| `FLOWPROXY_WS_HOST` | `127.0.0.1` | Extension WS bind — **must be loopback** (unauthenticated by design). |
+| `FLOWPROXY_EXT_WS_PORT` | `9223` | Extension WebSocket port. |
+| `FLOWPROXY_PUBLIC_BASE_URL` | `http://127.0.0.1:8101` | Base used to build absolute `/media` URLs returned to clients. |
+| `FLOW_POOL_CONCURRENCY` | `4` | Max concurrent in-flight Flow calls per instance (back-pressure, no 503). |
+| `FLOWPROXY_STORAGE` | `./storage` | Local byte cache dir. |
+| `FLOWPROXY_CATALOG_TTL` | `86400` | Model-catalog cache TTL (seconds). |
+| `VIDEO_POLL_MAX_CYCLES` / `VIDEO_POLL_INTERVAL_S` | `72` / `10` | Video poll budget (default 12 min). |
+
+## Layout
+
+```
+extension/            Chrome MV3 bridge (open a labs.google/fx/tools/flow tab)
+flow_engine/
+  bridge/             WS server + flow_client + flow_sdk (Flow API port)
+  media.py            DB-free media cache (registry + on-disk bytes)
+  jobs.py             in-memory job store + async video poller
+  session.py          readiness gate + default project + pool seam
+  catalog.py          model catalog (flow.projectInitialData), disk-cached
+  openai/             /v1/images, /v1/videos, /v1/flow/uploads, /v1/models
+  main.py             FastAPI app, /api/ext/callback, /media/{id}, lifespan
+  cli/                launcher: app (argparse), supervisor, dashboard,
+                      processes, health, config (~/.vrex-flow)
+```
+
+## Notes & caveats
+
+- **Single account.** One extension instance = one Google account = one tier.
+  Multi-tenant needs a browser-instance pool routed by API key — the
+  `session.get_bridge(api_key)` indirection is where that goes.
+- **Live Flow tab required.** Every dispatch solves an enterprise reCAPTCHA in
+  an open Flow tab; hosting needs a headful/virtual-display Chrome kept warm.
+- **Signed URLs expire.** flow-engine caches bytes locally and serves stable
+  `/media/{id}` URLs; workflow-mode video arrives as inline base64 MP4.
+- **Localhost WS is unauthenticated** by design — never bind it to a network
+  interface. Gate the HTTP `/v1/*` surface with `FLOW_ENGINE_API_KEY` when exposed.
+- **No `.env` auto-load.** The process reads `os.environ` directly — export vars
+  in the shell (or a wrapper/launchd unit), don't rely on a `.env` file.
+```

vrex_flow_engine-0.2.0/flow_engine/__init__.py

@@ -0,0 +1,4 @@
+"""flow_engine — host a Flowboard browser-extension instance and expose
+OpenAI-compatible image/video generation endpoints over Google Flow."""
+
+__version__ = "0.0.1"

vrex_flow_engine-0.2.0/flow_engine/bridge/__init__.py

@@ -0,0 +1,6 @@
+"""The extension bridge: WS server + Flow client + Flow SDK.
+
+These three modules are lifted near-verbatim from flowboard's agent. They are
+intentionally free of any database / board dependency so they drop straight
+into a standalone proxy. The only edits vs. the originals are the import paths.
+"""