vrex-flow-engine 0.2.0__py3-none-any.whl

flow_engine/cli/dashboard.py

@@ -0,0 +1,125 @@
+"""Live status dashboard (rich) for the flow-engine supervisor.
+
+Read-only view rendered from `UiState` every refresh: engine + tunnel health,
+the irreplaceable 'extension connected' signal, and a merged log tail. Ctrl-C in
+the supervisor tears it down cleanly.
+"""
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Deque, Optional, Tuple
+
+from rich.columns import Columns
+from rich.console import Group
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .config import DEFAULT_PUBLIC_BASE_URL
+
+# (source, text) log entries — source is the process name ("engine"/"tunnel").
+LogEntry = Tuple[str, str]
+
+
+@dataclass
+class UiState:
+    port: int = 8101
+    public_base_url: str = DEFAULT_PUBLIC_BASE_URL
+    with_tunnel: bool = True
+    uptime_s: float = 0.0
+    # engine
+    engine_alive: bool = False
+    engine_pid: Optional[int] = None
+    engine_restarts: int = 0
+    health: Optional[dict] = None
+    # tunnel
+    tunnel_alive: bool = False
+    tunnel_pid: Optional[int] = None
+    tunnel_restarts: int = 0
+    tunnel_connected: bool = False
+    logs: Deque[LogEntry] = field(default_factory=deque)
+
+
+def _fmt_uptime(secs: float) -> str:
+    s = int(secs)
+    h, s = divmod(s, 3600)
+    m, s = divmod(s, 60)
+    return f"{h}h{m:02d}m{s:02d}s" if h else f"{m}m{s:02d}s"
+
+
+def _dot(ok: bool, warn: bool = False) -> Text:
+    if warn:
+        return Text("●", style="yellow")
+    return Text("●", style="green" if ok else "red")
+
+
+def _engine_panel(st: UiState) -> Panel:
+    h = st.health or {}
+    ext_connected = bool(h.get("extension_connected"))
+    t = Table.grid(padding=(0, 1))
+    t.add_column(justify="right", style="dim")
+    t.add_column()
+    status = Text.assemble(_dot(st.engine_alive), " ", ("UP" if st.engine_alive else "DOWN"))
+    t.add_row("status", status)
+    t.add_row("health", Text("responding", style="green") if st.health else Text("no response", style="red"))
+    t.add_row("port", str(st.port))
+    t.add_row("pid", str(st.engine_pid or "—"))
+    t.add_row(
+        "extension",
+        Text.assemble(_dot(ext_connected, warn=not ext_connected), " ",
+                      "connected" if ext_connected else "OPEN A FLOW TAB"),
+    )
+    t.add_row("instances", str(h.get("instances", "—")))
+    if st.engine_restarts:
+        t.add_row("restarts", Text(str(st.engine_restarts), style="yellow"))
+    return Panel(t, title="[bold]engine[/]", border_style="green" if st.engine_alive else "red")
+
+
+def _tunnel_panel(st: UiState) -> Panel:
+    if not st.with_tunnel:
+        return Panel(Text("disabled (--no-tunnel)", style="dim"), title="[bold]tunnel[/]", border_style="dim")
+    connected = st.tunnel_connected and st.tunnel_alive
+    t = Table.grid(padding=(0, 1))
+    t.add_column(justify="right", style="dim")
+    t.add_column()
+    status = Text.assemble(_dot(connected, warn=st.tunnel_alive and not connected), " ",
+                           "connected" if connected else ("connecting…" if st.tunnel_alive else "DOWN"))
+    t.add_row("status", status)
+    host = st.public_base_url.replace("https://", "").replace("http://", "")
+    t.add_row("public", Text(host, style="cyan"))
+    t.add_row("→", f"127.0.0.1:{st.port}")
+    t.add_row("pid", str(st.tunnel_pid or "—"))
+    if st.tunnel_restarts:
+        t.add_row("restarts", Text(str(st.tunnel_restarts), style="yellow"))
+    return Panel(t, title="[bold]tunnel[/]", border_style="green" if connected else "yellow")
+
+
+def _logs_panel(st: UiState, limit: int = 14) -> Panel:
+    body = Text()
+    entries = list(st.logs)[-limit:] if st.logs else []
+    if not entries:
+        body.append("waiting for output…", style="dim")
+    for source, line in entries:
+        tag_style = "cyan" if source == "engine" else "magenta"
+        body.append(f"{source:>6} ", style=tag_style)
+        body.append(line[:200] + "\n", style="default")
+    return Panel(body, title="[bold]logs[/] [dim](engine + tunnel)[/]", border_style="blue")
+
+
+def render(st: UiState):
+    """Build the full dashboard renderable for one refresh."""
+    overall_up = st.engine_alive and (not st.with_tunnel or (st.tunnel_alive and st.tunnel_connected))
+    header = Panel(
+        Text.assemble(
+            ("🎬 Vrex Flow Engine", "bold"),
+            "   ",
+            _dot(overall_up, warn=st.engine_alive and not overall_up),
+            (" running" if overall_up else " starting", "dim"),
+            ("   uptime ", "dim"), (_fmt_uptime(st.uptime_s), "bold"),
+        ),
+        border_style="bold blue",
+    )
+    status_row = Columns([_engine_panel(st), _tunnel_panel(st)], equal=True, expand=True)
+    footer = Text("Ctrl-C to stop  ·  logs at ~/.vrex-flow/logs", style="dim", justify="center")
+    return Group(header, status_row, _logs_panel(st), footer)

flow_engine/cli/health.py

@@ -0,0 +1,40 @@
+"""Engine + tunnel health signals for the dashboard.
+
+- Engine: GET /api/health on loopback → {ok, extension_connected, instances}.
+- Tunnel: cloudflared's own logs are the source of truth; `tunnel_state_from_line`
+  classifies a log line into connected / error / None so the supervisor can track
+  whether the tunnel has registered a connection to Cloudflare's edge.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+
+def probe_engine(port: int, timeout: float = 2.0) -> Optional[dict]:
+    """Return the /api/health JSON, or None if the engine isn't answering yet."""
+    try:
+        resp = httpx.get(f"http://127.0.0.1:{port}/api/health", timeout=timeout)
+        if resp.status_code == 200:
+            return resp.json()
+    except Exception:
+        return None
+    return None
+
+
+def tunnel_state_from_line(line: str) -> Optional[str]:
+    """Map a cloudflared log line to 'connected' | 'error' | None (no change).
+
+    cloudflared logs 'Registered tunnel connection' once an edge connection is up,
+    and 'Unregistered tunnel connection' / 'ERR' when it drops. We treat a
+    registration as connected and an explicit error/unregister as a drop.
+
+    Order matters: 'unregistered tunnel connection' CONTAINS 'registered tunnel
+    connection', so the drop/error cases must be tested before the connect case."""
+    low = line.lower()
+    if "unregistered tunnel connection" in low or "failed to" in low or "err " in low or "error=" in low:
+        return "error"
+    if "registered tunnel connection" in low:
+        return "connected"
+    return None

flow_engine/cli/processes.py

@@ -0,0 +1,109 @@
+"""ManagedProcess — a supervised child process with captured, tee'd logs.
+
+The supervisor runs two of these: the uvicorn engine and the cloudflared tunnel.
+Each spawns with a background thread pumping merged stdout/stderr into (a) its own
+rotating-append log file and (b) an `on_line(name, text)` sink the dashboard tails.
+Restart/backoff policy lives in the supervisor loop, not here — this class only
+owns spawn, log capture, liveness, and graceful stop.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Callable, Optional, Sequence
+
+OnLine = Callable[[str, str], None]
+
+
+class ManagedProcess:
+    def __init__(
+        self,
+        name: str,
+        argv: Sequence[str],
+        *,
+        env: Optional[dict] = None,
+        log_file: Optional[Path] = None,
+        on_line: Optional[OnLine] = None,
+        display: Optional[str] = None,
+    ) -> None:
+        self.name = name
+        self.argv = list(argv)
+        # `display` is a secret-masked argv for the UI (e.g. cloudflared --token ***).
+        self.display = display or " ".join(self.argv)
+        self._env = {**os.environ, **(env or {})}
+        self._log_file = log_file
+        self._on_line = on_line
+
+        self._proc: Optional[subprocess.Popen] = None
+        self._pump: Optional[threading.Thread] = None
+        self.started_at: Optional[float] = None
+        self.restarts = 0
+        self.last_exit: Optional[int] = None
+
+    # ── lifecycle ────────────────────────────────────────────────────────────
+    def start(self) -> None:
+        """Spawn the child (merged stderr→stdout, line-buffered) + pump thread."""
+        if self._log_file:
+            self._log_file.parent.mkdir(parents=True, exist_ok=True)
+        self._proc = subprocess.Popen(
+            self.argv,
+            env=self._env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+        self.started_at = time.monotonic()
+        self._pump = threading.Thread(target=self._read_output, name=f"{self.name}-pump", daemon=True)
+        self._pump.start()
+
+    def _read_output(self) -> None:
+        assert self._proc and self._proc.stdout
+        log_fh = open(self._log_file, "a", buffering=1) if self._log_file else None
+        try:
+            for line in self._proc.stdout:
+                text = line.rstrip("\n")
+                if log_fh:
+                    log_fh.write(text + "\n")
+                if self._on_line:
+                    self._on_line(self.name, text)
+        finally:
+            if log_fh:
+                log_fh.close()
+
+    @property
+    def alive(self) -> bool:
+        return self._proc is not None and self._proc.poll() is None
+
+    def poll(self) -> Optional[int]:
+        """Return the exit code if the process has died (and record it), else None."""
+        if self._proc is None:
+            return None
+        code = self._proc.poll()
+        if code is not None and self.last_exit != code:
+            self.last_exit = code
+        return code
+
+    @property
+    def pid(self) -> Optional[int]:
+        return self._proc.pid if self._proc else None
+
+    @property
+    def uptime_s(self) -> float:
+        return (time.monotonic() - self.started_at) if self.started_at and self.alive else 0.0
+
+    def stop(self, grace: float = 8.0) -> None:
+        """SIGTERM, wait up to `grace`, then SIGKILL. Idempotent."""
+        if not self._proc or self._proc.poll() is not None:
+            return
+        try:
+            self._proc.send_signal(signal.SIGTERM)
+            self._proc.wait(timeout=grace)
+        except subprocess.TimeoutExpired:
+            self._proc.kill()
+        except ProcessLookupError:
+            pass

flow_engine/cli/supervisor.py

@@ -0,0 +1,184 @@
+"""Supervisor — spawn + babysit the engine and the cloudflared tunnel, and drive
+the live dashboard.
+
+Process tree: this launcher (parent) → uvicorn engine (`python -m flow_engine.main`)
++ cloudflared tunnel, each a child ManagedProcess. The engine's flow/wavespeed
+config is its own concern; the supervisor only injects the API key + ports and
+watches liveness. Dead children restart with capped exponential backoff; Ctrl-C
+or SIGTERM stops both gracefully.
+"""
+from __future__ import annotations
+
+import shutil
+import signal
+import socket
+import sys
+import threading
+import time
+from collections import deque
+from typing import Optional
+
+from rich.console import Console
+
+from . import dashboard, health
+from .config import LOGS_DIR, FlowConfig, mask
+from .processes import ManagedProcess
+
+console = Console()
+
+STABLE_UPTIME_S = 60.0   # a child alive this long → reset its backoff counter
+BASE_BACKOFF_S = 1.0
+MAX_BACKOFF_S = 30.0
+HEALTH_EVERY_S = 2.0
+
+
+def preflight(cfg: FlowConfig, with_tunnel: bool) -> bool:
+    """Verify prerequisites the launcher can check. Returns False to abort."""
+    ok = True
+    if not cfg.has_engine_key:
+        console.print("[red]✗[/] no engine API key — run [bold]flow-engine setup[/]")
+        ok = False
+    if with_tunnel and not shutil.which("cloudflared"):
+        console.print(
+            "[red]✗[/] cloudflared not found. Install it:\n"
+            "    macOS:  [bold]brew install cloudflared[/]\n"
+            "    other:  https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/"
+        )
+        ok = False
+    if with_tunnel and not cfg.has_tunnel_token:
+        console.print("[red]✗[/] no tunnel token — run [bold]flow-engine setup[/] (or pass --no-tunnel)")
+        ok = False
+    if _port_in_use(cfg.http_port):
+        console.print(f"[yellow]![/] port {cfg.http_port} already in use — the engine may fail to bind")
+    return ok
+
+
+def _port_in_use(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+class Supervisor:
+    def __init__(self, cfg: FlowConfig, with_tunnel: bool = True) -> None:
+        self.cfg = cfg
+        self.with_tunnel = with_tunnel
+        self._stop = threading.Event()
+        self._logs: deque = deque(maxlen=500)
+        self._tunnel_connected = False
+        self._restart_at: dict[str, Optional[float]] = {}
+        self._started_at = time.monotonic()
+
+    def _on_line(self, source: str, text: str) -> None:
+        """Pump-thread callback: buffer the line + update tunnel connection state."""
+        self._logs.append((source, text))
+        if source == "tunnel":
+            state = health.tunnel_state_from_line(text)
+            if state == "connected":
+                self._tunnel_connected = True
+            elif state == "error":
+                self._tunnel_connected = False
+
+    def _build_engine(self) -> ManagedProcess:
+        env = {
+            "FLOW_ENGINE_API_KEY": self.cfg.engine_api_key,
+            "FLOWPROXY_HTTP_PORT": str(self.cfg.http_port),
+            "FLOWPROXY_PUBLIC_BASE_URL": self.cfg.public_base_url,
+        }
+        return ManagedProcess(
+            "engine",
+            [sys.executable, "-m", "flow_engine.main"],
+            env=env,
+            log_file=LOGS_DIR / "engine.log",
+            on_line=self._on_line,
+            display=f"{sys.executable} -m flow_engine.main",
+        )
+
+    def _build_tunnel(self) -> ManagedProcess:
+        token = self.cfg.tunnel_token
+        argv = ["cloudflared", "--no-autoupdate", "tunnel", "run", "--token", token]
+        return ManagedProcess(
+            "tunnel",
+            argv,
+            log_file=LOGS_DIR / "tunnel.log",
+            on_line=self._on_line,
+            display=f"cloudflared --no-autoupdate tunnel run --token {mask(token)}",
+        )
+
+    def _supervise(self, proc: ManagedProcess) -> None:
+        """Restart a dead child with capped exponential backoff."""
+        proc.poll()  # record exit code if it just died
+        if proc.alive:
+            if proc.uptime_s > STABLE_UPTIME_S and proc.restarts:
+                proc.restarts = 0
+            self._restart_at[proc.name] = None
+            return
+        due = self._restart_at.get(proc.name)
+        if due is None:
+            proc.restarts += 1
+            delay = min(MAX_BACKOFF_S, BASE_BACKOFF_S * (2 ** (proc.restarts - 1)))
+            self._restart_at[proc.name] = time.monotonic() + delay
+            self._logs.append(("system", f"{proc.name} exited (code {proc.last_exit}); restart in {int(delay)}s"))
+        elif time.monotonic() >= due:
+            self._restart_at[proc.name] = None
+            proc.start()
+            self._logs.append(("system", f"{proc.name} restarted (attempt {proc.restarts})"))
+
+    def run(self) -> int:
+        LOGS_DIR.mkdir(parents=True, exist_ok=True)
+        engine = self._build_engine()
+        tunnel = self._build_tunnel() if self.with_tunnel else None
+
+        signal.signal(signal.SIGTERM, lambda *_: self._stop.set())
+
+        console.print(f"[dim]starting engine on :{self.cfg.http_port}"
+                      + (f" · tunnel → {self.cfg.public_base_url}" if self.with_tunnel else " · tunnel disabled")
+                      + "[/]")
+        engine.start()
+        if tunnel:
+            tunnel.start()
+
+        last_probe = 0.0
+        cached_health: Optional[dict] = None
+        from rich.live import Live
+
+        try:
+            with Live(console=console, refresh_per_second=8, screen=True) as live:
+                while not self._stop.is_set():
+                    now = time.monotonic()
+                    if now - last_probe >= HEALTH_EVERY_S:
+                        cached_health = health.probe_engine(self.cfg.http_port)
+                        last_probe = now
+                    self._supervise(engine)
+                    if tunnel:
+                        self._supervise(tunnel)
+                    live.update(dashboard.render(self._state(engine, tunnel, cached_health)))
+                    time.sleep(0.25)
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self._shutdown(engine, tunnel)
+        return 0
+
+    def _state(self, engine, tunnel, cached_health) -> "dashboard.UiState":
+        return dashboard.UiState(
+            port=self.cfg.http_port,
+            public_base_url=self.cfg.public_base_url,
+            with_tunnel=self.with_tunnel,
+            uptime_s=time.monotonic() - self._started_at,
+            engine_alive=engine.alive,
+            engine_pid=engine.pid,
+            engine_restarts=engine.restarts,
+            health=cached_health,
+            tunnel_alive=bool(tunnel and tunnel.alive),
+            tunnel_pid=tunnel.pid if tunnel else None,
+            tunnel_restarts=tunnel.restarts if tunnel else 0,
+            tunnel_connected=self._tunnel_connected,
+            logs=self._logs,
+        )
+
+    def _shutdown(self, engine, tunnel) -> None:
+        console.print("\n[dim]stopping…[/]")
+        if tunnel:
+            tunnel.stop()
+        engine.stop()
+        console.print("[green]✓[/] engine + tunnel stopped")

flow_engine/config.py

@@ -0,0 +1,43 @@
+"""Runtime configuration for flow_engine.
+
+Ports default to the SAME values flowboard's agent uses (HTTP 8101, WS 9223)
+so the existing extension build connects with zero changes. Because of that,
+flow_engine and the flowboard agent cannot both run on the defaults at once —
+override FLOWPROXY_HTTP_PORT / FLOWPROXY_EXT_WS_PORT (and rebuild the
+extension's hardcoded URLs in extension/background.js) if you need both.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+STORAGE_DIR = Path(os.getenv("FLOWPROXY_STORAGE", ROOT / "storage"))
+
+HTTP_PORT = int(os.getenv("FLOWPROXY_HTTP_PORT", "8101"))
+WS_HOST = os.getenv("FLOWPROXY_WS_HOST", "127.0.0.1")
+EXTENSION_WS_PORT = int(os.getenv("FLOWPROXY_EXT_WS_PORT", "9223"))
+
+# Public base used to build absolute media URLs returned to OpenAI clients
+# (response_format="url"). Point this at wherever flow_engine is reachable.
+PUBLIC_BASE_URL = os.getenv("FLOWPROXY_PUBLIC_BASE_URL", f"http://127.0.0.1:{HTTP_PORT}")
+
+# Bearer key gating the /v1/* and /api/* endpoints. Prefer the new env var name;
+# fall back to the legacy FLOWPROXY_API_KEY for backwards compatibility.
+# Enforcement (non-empty assertion) happens at server startup in main.py,
+# NOT here, so that `pip install -e .` and module imports don't crash.
+API_KEY = (os.getenv("FLOW_ENGINE_API_KEY") or os.getenv("FLOWPROXY_API_KEY", "")).strip()
+
+# Maximum concurrent in-flight Flow API calls per pool instance. Additional
+# callers queue (asyncio.Semaphore semantics — no 503, just back-pressure).
+POOL_MAX_CONCURRENCY = int(os.getenv("FLOW_POOL_CONCURRENCY", "4"))
+
+# Title used when flow_engine auto-creates its default Flow project.
+DEFAULT_PROJECT_TITLE = os.getenv("FLOWPROXY_PROJECT_TITLE", "flow_engine")
+
+# Model catalog (flow.projectInitialData) is a heavy call — cache it on disk
+# and only refresh once a day. Override the TTL (seconds) or force via
+# /v1/models?refresh=1.
+CATALOG_TTL_S = int(os.getenv("FLOWPROXY_CATALOG_TTL", str(24 * 60 * 60)))
+
+STORAGE_DIR.mkdir(parents=True, exist_ok=True)

flow_engine/ingest.py

@@ -0,0 +1,172 @@
+"""Resolve user-supplied reference media into Flow media ids.
+
+The generation endpoints (i2i / i2v / r2v) accept reference inputs that are
+EITHER an already-uploaded Flow media id OR raw media the caller wants us to
+upload on their behalf — a ``data:`` URL, an ``http(s)`` URL, or a bare base64
+string. This module classifies each input and, when it's raw, uploads it
+(images via ``uploadImage``, videos via the resumable upload-video flow) so the
+caller ends up with a clean list of media ids ready to dispatch.
+
+Already-uploaded ids pass through untouched, so a client can mix pre-uploaded
+references with fresh raw ones in the same request.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import logging
+from typing import Optional
+from urllib.parse import unquote, urlparse
+
+import httpx
+from fastapi import HTTPException
+
+from flow_engine import media as media_service
+from flow_engine.bridge.flow_sdk import FlowSDK
+
+logger = logging.getLogger(__name__)
+
+# Cap on bytes pulled from a user-supplied URL — defence against a caller
+# pointing us at an enormous file. 64 MiB comfortably covers an 8s 1080p clip.
+_MAX_FETCH_BYTES = 64 * 1024 * 1024
+
+_EXT_BY_MIME = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/webp": ".webp",
+    "image/gif": ".gif",
+    "video/mp4": ".mp4",
+    "video/webm": ".webm",
+    "video/quicktime": ".mov",
+}
+
+
+async def resolve_image_inputs(
+    sdk: FlowSDK, project_id: str, inputs: Optional[list[str]]
+) -> list[str]:
+    """Turn a list of image references into Flow media ids, uploading any raw
+    ones. Returns ``[]`` for a falsy/empty input."""
+    return await _resolve(sdk, project_id, inputs, want="image")
+
+
+async def resolve_video_inputs(
+    sdk: FlowSDK, project_id: str, inputs: Optional[list[str]]
+) -> list[str]:
+    """Turn a list of video references into Flow media ids, uploading any raw
+    ones. Returns ``[]`` for a falsy/empty input."""
+    return await _resolve(sdk, project_id, inputs, want="video")
+
+
+async def _resolve(
+    sdk: FlowSDK, project_id: str, inputs: Optional[list[str]], *, want: str
+) -> list[str]:
+    out: list[str] = []
+    for raw in inputs or []:
+        if not isinstance(raw, str) or not raw.strip():
+            continue
+        item = raw.strip()
+        # Already a Flow media id? Pass it through. A UUID-shaped id is hex +
+        # dashes; data:/http: URLs and base64 payloads never match, so this is
+        # an unambiguous discriminator.
+        candidate = media_service.normalize_media_id(item)
+        if media_service.is_valid_media_id(candidate) and not item.startswith(
+            ("data:", "http://", "https://")
+        ):
+            out.append(candidate)
+            continue
+        b64, mime, name = await _load_raw(item, want=want)
+        out.append(await _upload(sdk, project_id, b64, mime, name, want=want))
+    return out
+
+
+async def _upload(
+    sdk: FlowSDK,
+    project_id: str,
+    image_base64: str,
+    mime: str,
+    file_name: str,
+    *,
+    want: str,
+) -> str:
+    if want == "video":
+        result = await sdk.upload_video(
+            video_base64=image_base64,
+            mime_type=mime,
+            project_id=project_id,
+            file_name=file_name,
+        )
+    else:
+        result = await sdk.upload_image(
+            image_base64=image_base64,
+            mime_type=mime,
+            project_id=project_id,
+            file_name=file_name,
+        )
+    media_id = result.get("media_id")
+    if result.get("error") or not isinstance(media_id, str) or not media_id:
+        detail = str(result.get("error") or "no media_id returned")[:200]
+        raise HTTPException(status_code=502, detail=f"reference upload failed: {detail}")
+    return media_id
+
+
+async def _load_raw(item: str, *, want: str) -> tuple[str, str, str]:
+    """Return ``(base64_no_prefix, mime, file_name)`` for a raw reference."""
+    default_mime = "image/png" if want == "image" else "video/mp4"
+    if item.startswith("data:"):
+        header, sep, payload = item.partition(",")
+        if not sep or not payload:
+            raise HTTPException(status_code=400, detail="malformed data URL reference")
+        mime = header[len("data:") :].split(";", 1)[0].strip() or default_mime
+        _validate_b64(payload)
+        return payload, mime, _default_name(mime, want)
+    if item.startswith(("http://", "https://")):
+        return await _fetch_url(item, want=want)
+    # Bare base64 (no envelope) — assume the default mime for the mode.
+    _validate_b64(item)
+    return item, default_mime, _default_name(default_mime, want)
+
+
+async def _fetch_url(url: str, *, want: str) -> tuple[str, str, str]:
+    try:
+        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+            resp = await client.get(url)
+    except httpx.HTTPError as exc:
+        raise HTTPException(status_code=502, detail=f"could not fetch reference url: {exc}")
+    if resp.status_code != 200:
+        raise HTTPException(
+            status_code=502, detail=f"reference url returned HTTP {resp.status_code}"
+        )
+    content = resp.content
+    if len(content) > _MAX_FETCH_BYTES:
+        raise HTTPException(status_code=413, detail="reference media exceeds size limit")
+    mime = resp.headers.get("content-type", "").split(";")[0].strip().lower()
+    prefix = "image/" if want == "image" else "video/"
+    if not mime.startswith(prefix):
+        raise HTTPException(
+            status_code=415,
+            detail=f"reference url is not {want} media (content-type {mime or 'unknown'})",
+        )
+    b64 = base64.b64encode(content).decode("ascii")
+    return b64, mime, _name_from_url(url, mime, want)
+
+
+def _validate_b64(payload: str) -> None:
+    """Reject obviously-malformed base64 up front so the upstream upload call
+    fails fast with a clear 400 instead of a confusing Flow error."""
+    try:
+        base64.b64decode(payload, validate=True)
+    except (binascii.Error, ValueError):
+        raise HTTPException(status_code=400, detail="reference is not valid base64")
+
+
+def _default_name(mime: str, want: str) -> str:
+    ext = _EXT_BY_MIME.get(mime, ".mp4" if want == "video" else ".png")
+    return f"upload{ext}"
+
+
+def _name_from_url(url: str, mime: str, want: str) -> str:
+    path = urlparse(url).path
+    tail = unquote(path.rsplit("/", 1)[-1]) if path else ""
+    if tail and "." in tail:
+        return tail
+    return _default_name(mime, want)