#!/usr/bin/env python """Run a plan of calls against the private LTX-2.5 Studio Space under a hard daily GPU budget. # DRY RUN (the default): resolve, validate and price every call; contacts nothing python scripts/space_matrix.py --plan scripts/space_plan.example.json \\ --assets-dir ~/assets --quota-ledger ~/space-ledger.jsonl # the same plan, executed; when it stops at the ceiling (exit 3), the same command with # --resume on the next UTC day runs what is left (calls with an outcome in --out are skipped) python scripts/space_matrix.py --plan plan.json --assets-dir ~/assets \\ --quota-ledger ~/space-ledger.jsonl --out ~/space-runs/matrix --live [--resume] # one call from flags; the historical 11-mode loop is --plan default python scripts/space_matrix.py --mode text_to_video --width 704 --height 480 --num-frames 49 # read-only, one GET each, no GPU time python scripts/space_matrix.py status python scripts/space_matrix.py info python scripts/space_matrix.py logs --out run.log Exit codes: 0 plan complete · 2 illegal plan or contract mismatch (nothing spent) · 3 stopped at the ceiling · 4 the platform refused on quota · 5 a call failed (with --keep-going the rest of the plan still runs, and the exit is still 5). Cost figures are BOUNDS. There is no readable ZeroGPU quota endpoint, so billed seconds cannot be measured, only bounded: the conservative figure is the wall clock from the moment the Space starts the event to its completion, times the size multiplier. The ceiling check before each call adds that call's full reservation (``zerogpu.estimate_duration``, times the multiplier) to today's conservative total. The token is read when a command needs it (``HF_TOKEN``, else the Hub's cached token file), is sent only as the ``Authorization`` header to the Space and the Hub API, and is redacted from every line, file and error this script writes. """ from __future__ import annotations import argparse import hashlib import html import json import os import re import shutil import sys import time import traceback import urllib.error import urllib.parse import urllib.request import uuid from contextlib import contextmanager from dataclasses import dataclass, field, replace from dataclasses import fields as dataclass_fields from datetime import UTC, datetime, timedelta from pathlib import Path from typing import Any REPO = Path(__file__).resolve().parent.parent # `tests/` for `verify_streams`, the registry-driven stream checker. for _path in (REPO, REPO / "tests"): if str(_path) not in sys.path: sys.path.insert(0, str(_path)) import verify_streams # noqa: E402 from ltx25_studio import constraints, modes, outputs, zerogpu # noqa: E402 from ltx25_studio.ui import fields # noqa: E402 __all__ = [ "API_FIELD_KEYS", "DEFAULT_MODE_ORDER", "DEFAULT_QUOTA_CEILING_SECONDS", "ENDPOINT", "EXIT_CALL_FAILED", "EXIT_CEILING", "EXIT_ILLEGAL", "EXIT_OK", "EXIT_QUOTA", "GATE_ACCEPTED", "GATE_DEFERRED", "LORA_ENDPOINT", "OUTPUT_SLOTS", "UNBILLED_CATEGORIES", "Call", "Ledger", "PlanError", "QuotaLedgerUnreadable", "Secret", "app_gate", "as_the_space", "classify", "count_onsets", "default_plan", "generate_contract_problems", "load_plan", "main", "measure_audio", "measure_video", "platform_refusal", "quota_multiplier", "quota_refusal", "read_token", "redact", "reservation_seconds", "resume_split", "returned_files", "schedule_days", "utc_day", "verify_call", ] # --------------------------------------------------------------------------- # the Space and its published signature # --------------------------------------------------------------------------- DEFAULT_SPACE_ID = "techfreakworm/LTX2.5-Studio" DEFAULT_HUB_URL = "https://huggingface.co" ENDPOINT = "/on_generate" LORA_ENDPOINT = "/on_validate_lora" LORA_WEIGHT_ENDPOINT = "/on_lora_weight" API_PREFIX = "/gradio_api" #: ``/on_generate``'s file outputs, in order; the report follows them (``[Video, Audio, Markdown]``). OUTPUT_SLOTS = ("video", "audio") #: ``/on_generate``'s parameters after ``mode_id``: the field spec minus ``gr.State``, which #: Gradio does not publish. Read again from ``fields.FIELDS`` at call time (see :func:`api_fields`) #: so a field appended after import is still sent. API_FIELD_KEYS: tuple[str, ...] = tuple(f.key for f in fields.FIELDS if f.kind != "state") #: Field kind -> the component name Gradio publishes. Only ``text`` differs from its kind. _COMPONENT_FOR_KIND = {"text": "textbox"} # --------------------------------------------------------------------------- # budget # --------------------------------------------------------------------------- DAILY_QUOTA_SECONDS = 2400.0 DEFAULT_QUOTA_CEILING_SECONDS = 1920.0 #: The Space's ``LTX25_ZEROGPU_SIZE``; ``zerogpu.quota_multiplier`` turns it into the quota factor. DEFAULT_ZEROGPU_SIZE = "xlarge" DEFAULT_CALL_TIMEOUT_SECONDS = 1800.0 DEFAULT_READ_TIMEOUT_SECONDS = 120.0 EXIT_OK = 0 EXIT_ILLEGAL = 2 EXIT_CEILING = 3 EXIT_QUOTA = 4 EXIT_CALL_FAILED = 5 #: How the ZeroGPU platform words its refusals (``spaces`` ``zero/client.py``, 0.50-0.52): each #: error's title and the message under it. The app's failure card quotes only the MESSAGE; a #: title reaches the API only when an error escapes the handler. Checked in this order. _PLATFORM_REFUSALS: tuple[tuple[str, re.Pattern], ...] = ( # the PRO/free/IP quota, the runs limit, the Space-wide limit, pending credits ("quota", re.compile( r"ZeroGPU quota exceeded" r"|exceeded your [\w ]*?ZeroGPU quota" r"|exceeded your ZeroGPU runs limit" r"|exceeded [\w ]*GPU quota" r"|reached its GPU limit" r"|ZeroGPU pending credits exceeded" r"|too many ZeroGPU credits allocated", re.IGNORECASE, )), # the reservation is more than one call may ask for; nothing ran ("limit", re.compile( r"ZeroGPU illegal duration|requested GPU duration \([\d.]+s\) is larger than the maximum allowed", re.IGNORECASE, )), # no GPU was free in time; nothing ran ("queue", re.compile(r"ZeroGPU queue timeout|No GPU was available", re.IGNORECASE)), ) #: Failure categories by their string values (``ltx25_studio.errors``). These two mean the #: platform refused before a GPU was used: recorded with zero billed seconds. UNBILLED_CATEGORIES = ("limit", "queue") # --------------------------------------------------------------------------- # content thresholds (measurements, reported with their thresholds; never stop a plan) # --------------------------------------------------------------------------- MIN_PIXEL_STD = 1.0 MIN_DISTINCT_FRAMES = 2 #: mean |Δ| over the frames' own spatial std; frozen probes measured <= 0.000523, the stillest #: real post-fix render 0.004948. MIN_RELATIVE_FRAME_DELTA = 0.001 LOW_MEAN_FRAME_DELTA = 0.5 #: The pinned vocoder's rate; ``expect.sample_rate`` overrides it per call. PINNED_VOCODER_SAMPLING_RATE = 48000 # --------------------------------------------------------------------------- # the historical default plan (--plan default) # --------------------------------------------------------------------------- CHEAPEST_SIZE = modes.MIN_RESOLUTION CHEAPEST_FRAMES = 9 SEED = 1234 PROMPT = ( "A red sports car driving fast along a winding coastal road at sunset, " "waves breaking on rocks below, cinematic camera following alongside" ) #: Producers first: text_to_video makes the video (and, by frame, the image) the conditioned #: modes chain from; text_to_audio makes the audio. Each chain is explicit in the plan. DEFAULT_MODE_ORDER: tuple[str, ...] = ( "text_to_video", "text_to_audio", "text_to_audio_video", "image_to_video", "image_text_to_video", "image_to_audio_video", "image_text_to_audio_video", "video_to_video", "video_to_audio", "audio_to_audio", "audio_to_video", ) MEDIA_KINDS = ("image", "video", "audio") _CALL_KEYS = frozenset({"label", "mode", "loras", "expect", "note"}) _EXPECT_KEYS = { "width": int, "height": int, "frames": int, "has_audio": bool, "has_video": bool, "sample_rate": int, "frame_rate": float, } _LABEL = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$") _HUB_ID = re.compile(r"^[A-Za-z0-9][\w.-]*/[\w.-]+(/[\w./-]+)?$") # --------------------------------------------------------------------------- # clocks (module-level so tests can drive them) # --------------------------------------------------------------------------- def _utcnow() -> datetime: return datetime.now(UTC) def _monotonic() -> float: return time.monotonic() def utc_day(now: datetime | None = None) -> str: return (now or _utcnow()).strftime("%Y-%m-%d") def next_utc_midnight(now: datetime | None = None) -> datetime: moment = now or _utcnow() return datetime(moment.year, moment.month, moment.day, tzinfo=UTC) + timedelta(days=1) # --------------------------------------------------------------------------- # the token # --------------------------------------------------------------------------- _SECRETS: list[str] = [] REDACTED = "" class Secret: """The token. Never printed, pickled or formatted; :meth:`reveal` is read by the transport.""" __slots__ = ("_value",) def __init__(self, value: str): self._value = value if value and value not in _SECRETS: _SECRETS.append(value) def reveal(self) -> str: return self._value def __repr__(self) -> str: return f"Secret({REDACTED})" __str__ = __repr__ def __reduce__(self): raise TypeError("a Secret is not picklable") def token_path() -> Path: if os.environ.get("HF_TOKEN_PATH"): return Path(os.environ["HF_TOKEN_PATH"]).expanduser() home = os.environ.get("HF_HOME") or "~/.cache/huggingface" return Path(home).expanduser() / "token" def read_token() -> Secret | None: """``HF_TOKEN``, else the cached token file. Read at call time, never at import.""" value = (os.environ.get("HF_TOKEN") or "").strip() if not value: try: value = token_path().read_text().strip() except OSError: value = "" return Secret(value) if value else None def redact(text: Any) -> str: out = "" if text is None else str(text) for secret in _SECRETS: out = out.replace(secret, REDACTED) return out def _redacted_json(payload: Any) -> str: return redact(json.dumps(payload, indent=2, sort_keys=False, default=str)) + "\n" # --------------------------------------------------------------------------- # errors # --------------------------------------------------------------------------- class PlanError(ValueError): """The plan cannot run as written. Nothing was sent.""" class ContractMismatch(RuntimeError): """The live Space's published signature is not what the local field spec builds.""" class QuotaLedgerUnreadable(RuntimeError): """The ledger exists and is not a ledger. Refused rather than read as zero.""" class HttpError(RuntimeError): def __init__(self, code: int, url: str, body: str): self.code = code super().__init__(redact(f"HTTP {code} from {_strip_query(url)}: {body[:500]}")) class TransportError(RuntimeError): pass class CallTimeout(RuntimeError): pass def _strip_query(url: str) -> str: return url.split("?", 1)[0] # --------------------------------------------------------------------------- # HTTP # --------------------------------------------------------------------------- def _origin(url: str) -> str: parts = urllib.parse.urlsplit(url) return f"{parts.scheme}://{parts.netloc}".lower() class Http: """urllib with the token attached only to trusted origins and never carried across a redirect.""" def __init__(self, secret: Secret | None, trusted: tuple[str, ...] = ()): self._secret = secret self._trusted = {_origin(u) for u in trusted} self._opener = urllib.request.build_opener() def trust(self, url: str) -> None: self._trusted.add(_origin(url)) def open(self, method: str, url: str, *, data: bytes | None = None, headers=None, timeout: float = 60.0): request = urllib.request.Request(url, data=data, method=method, headers=dict(headers or {})) if self._secret is not None and _origin(url) in self._trusted: # Unredirected: urllib drops it on any redirect, to any host. request.add_unredirected_header("Authorization", f"Bearer {self._secret.reveal()}") try: return self._opener.open(request, timeout=timeout) except urllib.error.HTTPError as exc: try: body = exc.read(2000).decode("utf-8", "replace") except Exception: # noqa: BLE001 body = "" raise HttpError(exc.code, url, body) from None except (urllib.error.URLError, OSError) as exc: raise TransportError(redact(f"{type(exc).__name__} reaching {_strip_query(url)}: {exc}")) from None def get_json(self, url: str, *, timeout: float = 60.0) -> Any: with self.open("GET", url, headers={"Accept": "application/json"}, timeout=timeout) as response: return json.loads(response.read().decode("utf-8")) def post_json(self, url: str, payload: Any, *, timeout: float = 60.0) -> Any: body = json.dumps(payload).encode() headers = {"Content-Type": "application/json", "Accept": "application/json"} with self.open("POST", url, data=body, headers=headers, timeout=timeout) as response: return json.loads(response.read().decode("utf-8")) def iter_sse(response): """``data:`` payloads of an event stream, one parsed JSON value per event.""" buffer: list[str] = [] while True: raw = response.readline() if not raw: if buffer: yield json.loads("\n".join(buffer)) return line = raw.decode("utf-8", "replace").rstrip("\r\n") if not line: if buffer: text = "\n".join(buffer) buffer = [] yield json.loads(text) continue if line.startswith("data:"): buffer.append(line[5:].lstrip()) def space_host(space_id: str) -> str: """``owner/Name.x`` -> ``https://owner-name-x.hf.space``, the Space's own subdomain.""" slug = re.sub(r"[^a-z0-9]+", "-", space_id.lower()).strip("-") return f"https://{slug}.hf.space" class SpaceApp: """The Gradio app's HTTP surface: config, info, upload, queue, files.""" def __init__(self, base_url: str, http: Http, *, api_prefix: str = API_PREFIX): self.base = base_url.rstrip("/") self.http = http self.prefix = "/" + api_prefix.strip("/") if api_prefix else "" http.trust(self.base) def url(self, path: str) -> str: return f"{self.base}{self.prefix}{path}" def config(self) -> dict: return self.http.get_json(f"{self.base}/config") def info(self) -> dict: return self.http.get_json(self.url("/info")) def upload(self, local: Path) -> dict: boundary = uuid.uuid4().hex content = Path(local).read_bytes() name = Path(local).name body = ( f"--{boundary}\r\nContent-Disposition: form-data; name=\"files\"; filename=\"{name}\"\r\n" f"Content-Type: application/octet-stream\r\n\r\n" ).encode() + content + f"\r\n--{boundary}--\r\n".encode() headers = {"Content-Type": f"multipart/form-data; boundary={boundary}", "Accept": "application/json"} with self.http.open("POST", self.url("/upload"), data=body, headers=headers, timeout=600) as response: paths = json.loads(response.read().decode("utf-8")) return {"path": paths[0], "orig_name": name, "meta": {"_type": "gradio.FileData"}} def join(self, fn_index: int, data: list, session_hash: str) -> str: payload = { "data": data, "event_data": None, "fn_index": fn_index, "trigger_id": None, "session_hash": session_hash, } return str(self.http.post_json(self.url("/queue/join"), payload)["event_id"]) def stream(self, session_hash: str, *, read_timeout: float): query = urllib.parse.urlencode({"session_hash": session_hash}) return self.http.open( "GET", self.url(f"/queue/data?{query}"), headers={"Accept": "text/event-stream"}, timeout=read_timeout ) def download(self, server_path: str, dest: Path) -> Path: url = self.url("/file=" + urllib.parse.quote(server_path, safe="/:")) dest.parent.mkdir(parents=True, exist_ok=True) with self.http.open("GET", url, timeout=600) as response, dest.open("wb") as handle: shutil.copyfileobj(response, handle) return dest class Hub: """The Hub API's read-only Space endpoints.""" def __init__(self, hub_url: str, http: Http): self.base = hub_url.rstrip("/") self.http = http http.trust(self.base) def space(self, space_id: str) -> dict: return self.http.get_json(f"{self.base}/api/spaces/{space_id}") def logs(self, space_id: str, *, kind: str, max_seconds: float) -> list[str]: lines: list[str] = [] deadline = _monotonic() + max_seconds url = f"{self.base}/api/spaces/{space_id}/logs/{kind}" try: with self.http.open("GET", url, headers={"Accept": "text/event-stream"}, timeout=min(max_seconds, 10.0)) as response: for event in iter_sse(response): if isinstance(event, dict): lines.append(f"{event.get('timestamp', '')} {event.get('data', '')}".strip()) else: lines.append(str(event)) if _monotonic() >= deadline: break except TimeoutError: pass except TransportError as exc: if "timed out" not in str(exc): raise return lines # --------------------------------------------------------------------------- # the plan # --------------------------------------------------------------------------- def api_fields() -> tuple: """Non-state fields, from the spec as it stands now.""" return tuple(f for f in fields.FIELDS if f.kind != "state") def _field(key: str): return next((f for f in fields.FIELDS if f.key == key), None) def _accepts(spec, kind: str) -> bool: predicate = getattr(modes, "accepts", None) return bool(predicate(spec, kind)) if predicate else kind in spec.inputs def _requires(spec, kind: str) -> bool: predicate = getattr(modes, "requires", None) return bool(predicate(spec, kind)) if predicate else kind in spec.inputs def _skip_stage_2(spec) -> bool: return bool(getattr(spec, "skip_stage_2", False)) def _varies_clip(spec) -> bool: """The clip is a variation source (mode 04): its length is the run's length.""" return getattr(spec, "video_conditioning", None) == "variation" def _varies_audio(spec) -> bool: return getattr(spec, "audio_conditioning", None) == "variation" @dataclass(frozen=True) class MediaInput: kind: str path: Path | None = None from_call: str | None = None #: image chains only: a frame index, ``"middle"`` or ``"last"``. frame: int | str | None = None @property def chained(self) -> bool: return self.from_call is not None def describe(self) -> dict: if self.chained: out = {"chained": True, "from_call": self.from_call} if self.kind == "image": out["frame"] = self.frame return out size = self.path.stat().st_size if self.path and self.path.exists() else None return {"chained": False, "path": str(self.path), "bytes": size} #: ``lora.staging.DEFAULT_WEIGHT``: the strength ``/on_validate_lora`` stages an adapter at. #: Read lazily (the LoRA package imports the Hub client); 1.0 where it cannot be read. _STAGED_WEIGHT: list[float] = [] def staged_lora_weight() -> float: if not _STAGED_WEIGHT: try: from ltx25_studio.lora import staging _STAGED_WEIGHT.append(float(staging.DEFAULT_WEIGHT)) except Exception: # noqa: BLE001 _STAGED_WEIGHT.append(1.0) return _STAGED_WEIGHT[0] @dataclass(frozen=True) class LoraInput: source: str weight: float = 1.0 local: Path | None = None @property def needs_weight_route(self) -> bool: """A strength other than the one ``/on_validate_lora`` stages at.""" return self.weight != staged_lora_weight() @property def label(self) -> str: return self.local.name if self.local else self.source def describe(self) -> dict: return { "source": self.source, "route": "upload" if self.local else "hub", "local": str(self.local) if self.local else None, "weight": self.weight, } #: ``Call.gate``: the app's own gate accepted the call as the Space would run it, or the call #: takes an input an earlier call produces, so the gate runs when that file exists. GATE_ACCEPTED = "accepted" GATE_DEFERRED = "deferred" @dataclass(frozen=True) class Call: label: str mode: str values: dict media: dict loras: tuple = () expect: dict = field(default_factory=dict) note: str = "" #: :data:`GATE_ACCEPTED`, :data:`GATE_DEFERRED`, or "" before the gate was asked. gate: str = "" #: From ``generate.prepare_request``: the frame count the app will run (None: the model #: chooses) and the notes it will carry ("length set from your audio ..."). app_frames: int | None = None app_notes: tuple = () #: ``(key, sent, what the app runs)`` for every field the app's scoping changes. app_changes: tuple = () #: The variation level the app snaps ``noise_scale`` to (modes 04 and 10), else None. app_level: float | None = None @property def spec(self): return modes.get_mode(self.mode) def value(self, key: str) -> Any: if key in self.values: return self.values[key] spec = _field(key) return None if spec is None else spec.default def runs(self, key: str) -> Any: """The value the app runs with: after its scoping when the gate ran, else as sent.""" for name, _sent, ran in self.app_changes: if name == key: return ran return self.value(key) @property def chained(self) -> tuple[str, ...]: return tuple(kind for kind, item in self.media.items() if item.chained) @property def min_resolution(self) -> bool: return bool(getattr(self.spec, "min_resolution", False)) @property def render_size(self) -> tuple[int, int]: if self.min_resolution: return (modes.MIN_RESOLUTION, modes.MIN_RESOLUTION) return (int(self.value("width")), int(self.value("height"))) @property def stage_2(self) -> bool: return bool(self.value("enable_stage_2")) and not _skip_stage_2(self.spec) @property def exports(self) -> tuple[str, ...]: return tuple(self.spec.exports) def expected_geometry(self) -> tuple[int, int] | None: if "video" not in self.exports: return None width, height = self.render_size if self.stage_2: width, height = 2 * width, 2 * height return (int(self.expect.get("width", width)), int(self.expect.get("height", height))) def expected_frames(self) -> int | None: if "frames" in self.expect: return int(self.expect["frames"]) if "video" not in self.exports: return None if self.app_frames is not None: return self.app_frames if self.value("auto_duration") or _varies_clip(self.spec): # The model, the audio or the clip sets the length: known once the gate has run. return None return int(self.value("num_frames")) def _check_value(spec, value, problems: list[str], where: str) -> Any: """``value`` as it is sent; a choice may be named by its label ("Sharper (standard decoder)").""" kind = spec.kind if kind == "text" and not isinstance(value, str): problems.append(f"{where}: {spec.key} must be text") elif kind == "checkbox" and not isinstance(value, bool): problems.append(f"{where}: {spec.key} must be true or false") elif kind in ("number", "slider"): if isinstance(value, bool) or not isinstance(value, (int, float)): problems.append(f"{where}: {spec.key} must be a number") return value low, high = spec.options.get("minimum"), spec.options.get("maximum") if low is not None and value < low or high is not None and value > high: problems.append(f"{where}: {spec.key}={value} is outside {low}..{high}") elif kind in ("dropdown", "radio"): choices = spec.options.get("choices") if choices: pairs = [tuple(c) if isinstance(c, (list, tuple)) else (c, c) for c in choices] by_label = {label: sent for label, sent in pairs} allowed = [sent for _label, sent in pairs] if value not in allowed and value in by_label: return by_label[value] if value not in allowed: shown = ", ".join(f"{sent!r} ({label})" if label != sent else repr(sent) for label, sent in pairs) problems.append(f"{where}: {spec.key}={value!r} is not one of {shown}") elif kind == "dataframe" and not isinstance(value, list): problems.append(f"{where}: {spec.key} must be a list of rows") return value def _resolve_path(raw: str, base: Path) -> Path: path = Path(raw).expanduser() return path if path.is_absolute() else (base / path) def _parse_call(raw: dict, *, index: int, base: Path, earlier: dict, problems: list[str]) -> Call | None: before = len(problems) where = f"call {index + 1}" if not isinstance(raw, dict): problems.append(f"{where}: must be an object") return None label = raw.get("label") if not isinstance(label, str) or not _LABEL.match(label): problems.append(f"{where}: 'label' must match {_LABEL.pattern} (it names the evidence folder)") return None where = f"call {label!r}" if label in earlier: problems.append(f"{where}: the label is used twice") return None try: spec = modes.get_mode(str(raw.get("mode"))) except Exception as exc: # noqa: BLE001 problems.append(f"{where}: {exc}") return None values: dict = {} media: dict = {} loras: list[LoraInput] = [] expect: dict = {} for key, value in raw.items(): if key in ("label", "mode", "note"): continue if key == "expect": if not isinstance(value, dict): problems.append(f"{where}: 'expect' must be an object") continue for name, wanted in value.items(): kind = _EXPECT_KEYS.get(name) if kind is None: problems.append(f"{where}: expect.{name} is not one of {sorted(_EXPECT_KEYS)}") elif kind is bool and not isinstance(wanted, bool): problems.append(f"{where}: expect.{name} must be true or false") elif kind is not bool and (isinstance(wanted, bool) or not isinstance(wanted, (int, float))): problems.append(f"{where}: expect.{name} must be a number") else: expect[name] = wanted continue if key == "loras": if not isinstance(value, list): problems.append(f"{where}: 'loras' must be a list of {{source, weight}}") continue for entry in value: lora = _parse_lora(entry, base=base, where=where, problems=problems) if lora is not None: loras.append(lora) continue spec_field = _field(key) if spec_field is None: known = ", ".join(f.key for f in api_fields()) problems.append( f"{where}: {key!r} is not a field of this app's {ENDPOINT} (fields: {known}; " f"call keys: {', '.join(sorted(_CALL_KEYS))})" ) continue if spec_field.kind == "state": problems.append(f"{where}: {key!r} is staged through {LORA_ENDPOINT}; use the call's 'loras' list") continue if spec_field.kind in MEDIA_KINDS: item = _parse_media(spec_field.kind, value, base=base, where=where, earlier=earlier, problems=problems) if item is not None: media[spec_field.kind] = item continue values[key] = _check_value(spec_field, value, problems, where) call = Call(label=label, mode=spec.id, values=values, media=media, loras=tuple(loras), expect=expect, note=str(raw.get("note", ""))) for kind in MEDIA_KINDS: if kind in media and not _accepts(spec, kind): problems.append(f"{where}: {spec.id} takes no {kind}") if kind not in media and _requires(spec, kind): problems.append( f"{where}: {spec.id} needs a {kind}: give a file under --assets-dir, or " f'{{"from_call": ""}} to use an earlier call\'s output' ) if str(values.get("prompt", "") or "").strip() and not _accepts(spec, "text"): problems.append(f"{where}: {spec.id} takes no prompt; remove 'prompt'") try: width, height = call.render_size constraints.validate_dimensions(width, height) constraints.validate_dimension_limit(width, name="width") constraints.validate_dimension_limit(height, name="height") except Exception as exc: # noqa: BLE001 problems.append(f"{where}: {exc}") try: if not call.value("auto_duration"): constraints.validate_num_frames(int(call.value("num_frames"))) constraints.validate_num_frames_limit(int(call.value("num_frames"))) else: if float(call.value("min_seconds")) >= float(call.value("max_seconds")): problems.append(f"{where}: max_seconds must be greater than min_seconds") constraints.validate_seconds_limit(float(call.value("max_seconds"))) except Exception as exc: # noqa: BLE001 problems.append(f"{where}: {exc}") if len(problems) > before: return call if call.chained: # The app's gate opens its inputs; a file an earlier call produces does not exist yet. # It runs on that file, before anything is sent, once the producer has run. return replace(call, gate=GATE_DEFERRED) try: return gated(call, {kind: item.path for kind, item in media.items()}) except PlanError as exc: problems.append(f"{where}: {exc}") except Exception as exc: # noqa: BLE001 -- the app's own words problems.append(f"{where}: the app would refuse this call before reserving a GPU: {exc}") return call @dataclass(frozen=True) class Gate: """What ``generate.prepare_request`` said about one call.""" frames: int | None notes: tuple[str, ...] changes: tuple level: float | None class _Platform: """Stands for the ``spaces`` package the Space imports: ``zerogpu.is_zerogpu`` says yes.""" is_stub = False @contextmanager def as_the_space(): """``device.current()`` answers as on the Space (ZeroGPU, CUDA) while the app's gate runs. The gate refuses some requests by device (stage 2, and the diffusion decoder off CUDA); left alone it would apply THIS machine's ``LTX25_DEVICE`` to a call that runs on the Space. """ from ltx25_studio import config, device resolve = getattr(device, "resolve", None) if resolve is None or not hasattr(device, "current"): yield None return try: settings = replace(config.load_config(), device="auto") resolution = resolve(spaces_module=_Platform(), runtime_config=settings) except Exception as exc: # noqa: BLE001 -- a local setting, not the Space's raise PlanError( f"the app's gate cannot be run as the Space runs it, because this machine's LTX25_* " f"settings do not load: {exc}" ) from None original = device.current device.current = lambda: resolution try: yield resolution finally: device.current = original def _space_input(kind: str, path) -> Any: """A media file as the Space's handler receives it: images as PIL (``gr.Image(type="pil")``), video and audio as file paths.""" if kind != "image": return str(path) from PIL import Image try: with Image.open(path) as image: return image.convert("RGB") except Exception as exc: # noqa: BLE001 raise PlanError( f"image {Path(path).name} could not be read as a picture ({type(exc).__name__}); the " f"Space's image input would refuse it" ) from None def _app_request(call: Call, media: dict): """The ``GenerationRequest`` the Space's handler would build from this call's fields.""" from ltx25_studio import generate known = {f.name for f in dataclass_fields(generate.GenerationRequest)} width, height = call.render_size kwargs: dict = {"mode": call.mode} for spec in api_fields(): if spec.key not in known: continue if spec.kind in MEDIA_KINDS: path = media.get(spec.kind) kwargs[spec.key] = None if path is None else _space_input(spec.kind, path) elif spec.key in ("width", "height"): kwargs[spec.key] = width if spec.key == "width" else height elif spec.kind == "dataframe": kwargs[spec.key] = tuple(call.value(spec.key) or ()) else: kwargs[spec.key] = call.value(spec.key) return generate.GenerationRequest(**kwargs) def _variation_level(spec, scoped) -> float | None: """The level a variation mode runs at, as the mode's own ``build_kwargs`` decides it (the nearest supported level to ``noise_scale``, or the mode's default); None for other modes.""" if not (_varies_clip(spec) or _varies_audio(spec)): return None kwargs = spec.build_kwargs(scoped) clip = kwargs.get("video_variation") level = getattr(clip, "level", None) if clip is not None else kwargs.get("audio_noise_level") return None if level is None else float(level) def app_gate(call: Call, media: dict) -> Gate: """``generate.prepare_request``, the checks the app runs before it reserves a GPU, run as the Space runs them (:func:`as_the_space`), on the files themselves. Raises what the Space would refuse the call with. """ from ltx25_studio import generate request = _app_request(call, media) with as_the_space(): scoped, spec, notes = generate.prepare_request(request) changes = [] for key in (f.key for f in api_fields() if f.kind not in MEDIA_KINDS): if not hasattr(request, key): continue sent, ran = getattr(request, key), getattr(scoped, key) if sent != ran: changes.append((key, sent, ran)) return Gate( frames=None if scoped.auto_duration else int(scoped.num_frames), notes=tuple(str(note) for note in notes), changes=tuple(changes), level=_variation_level(spec, scoped), ) def gated(call: Call, media: dict) -> Call: """``call`` with what the app's gate said; raises its refusal.""" gate = app_gate(call, media) return replace(call, gate=GATE_ACCEPTED, app_frames=gate.frames, app_notes=gate.notes, app_changes=gate.changes, app_level=gate.level) def _parse_media(kind, value, *, base, where, earlier, problems) -> MediaInput | None: if isinstance(value, str): path = _resolve_path(value, base) if not path.is_file(): problems.append(f"{where}: {kind} file {path} does not exist") return None return MediaInput(kind=kind, path=path) if isinstance(value, dict) and "from_call" in value: source = value["from_call"] extra = set(value) - {"from_call", "frame"} if extra: problems.append(f"{where}: {kind}: unknown key(s) {sorted(extra)}") producer = earlier.get(source) if producer is None: problems.append(f"{where}: {kind} from_call {source!r} is not an earlier call in this plan") return None track = "audio" if kind == "audio" else "video" if track not in producer.exports: problems.append(f"{where}: {kind} from_call {source!r}: {producer.mode} exports no {track}") return None frame = value.get("frame", "middle") if kind == "image" else None if kind == "image" and not (isinstance(frame, int) and not isinstance(frame, bool) and frame >= 0 or frame in ("middle", "last")): problems.append(f"{where}: image frame must be an index >= 0, 'middle' or 'last'") return None if kind != "image" and "frame" in value: problems.append(f"{where}: 'frame' applies to an image chain only") return MediaInput(kind=kind, from_call=source, frame=frame) problems.append(f"{where}: {kind} must be a file path or {{\"from_call\": \"