Upload studio/backends/hf_space.py with huggingface_hub

studio/backends/hf_space.py

@@ -1,21 +1,4 @@
-"""HF Spaces backend adapter (free ZeroGPU A100 via `gradio_client`).
-
-Local CLI client that calls a deployed Hugging Face Space hosting the studio's
-inference pipeline. The Space provides the GPU; the local machine needs only
-`gradio_client` + a HF token. No torch, no diffusers, no model downloads locally.
-
-Token resolution order (most-specific wins):
-  1. explicit `hf_token=` param
-  2. `HF_TOKEN` env var
-  3. `huggingface_hub.HfFolder.get_token()` (reads ~/.cache/huggingface/token)
-
-The deployed Space is expected to expose a Gradio function (default api_name
-`/infer`) with the signature:
-    (image_pil, preset_name, num_frames, num_inference_steps, guidance_scale,
-     prompt, negative_prompt, seed) -> video_filepath
-
-Pair this with the host-mode `app.py` at the repo root for end-to-end ownership.
-"""
+"""HF Spaces backend adapter — extended with LTX-Video I2V endpoint."""
 from __future__ import annotations
 from dataclasses import dataclass
 import os
@@ -65,7 +48,6 @@ class HFSpaceAdapter:
     def bind_motion_exemplar(
         self, cursor: PixelCursor, exemplar: Sequence[str]
     ) -> PixelCursor:
-        """Same preset semantics as AnimateDiff; the Space carries the same MotionLoRA map."""
         if len(exemplar) != 1:
             raise ValueError(
                 "hf_space.bind_motion_exemplar expects exactly one preset name."
@@ -108,10 +90,6 @@ class HFSpaceAdapter:
                 else "NONE"
             ),
             "gradio_client_installed": _gradio_client_available(),
-            "note": (
-                "Anonymous calls work but quota is tight; an HF token raises the limit. "
-                "ZeroGPU cold-start ~10-30s; subsequent calls ~5-15s warm."
-            ),
         }
 
     def write_motion(self, cursor: PixelCursor, motion_spec: dict | None = None) -> FrameStack:
@@ -152,26 +130,63 @@ class HFSpaceAdapter:
         return _video_path_to_framestack(video_path, preset)
 
 
-def _video_path_to_framestack(video_path: str | Path, preset: str) -> FrameStack:
+def generate_headlocked_via_space(
+    image_path: str,
+    *,
+    space_id: str,
+    prompt: str,
+    negative_prompt: str = (
+        "head movement, swaying, bobbing, nodding, camera shake, "
+        "zoom, pan, jump cut, cartoon, deformed, blurry"
+    ),
+    height: int = 576,
+    width: int = 320,
+    num_frames: int = 121,
+    num_inference_steps: int = 25,
+    guidance_scale: float = 3.0,
+    seed: int = 42,
+    hf_token: Optional[str] = None,
+    api_name: str = "/infer_ltx_i2v",
+) -> str:
+    """Call the Space's LTX I2V endpoint and return the path to the generated mp4.
+
+    Designed for hologram head-locked clip generation. Default params:
+      - 576×320 portrait (9:16-ish, both div-32, confirmed working on A10G)
+      - 121 frames = 5.04s @ 24fps (8*15+1)
+      - guidance_scale=3.0 (LTX-Video optimal range is 2-4)
+
+    The Space enforces div-32 and 8k+1 constraints internally — caller values
+    are rounded up, not rejected.
+
+    Example:
+        path = generate_headlocked_via_space(
+            "/path/to/chancellor-li-hq-smoothLIGHT-2144x3840.jpg",
+            space_id="AlterProgramming/venture-studio",
+            prompt="East-Asian man, 30s, dark navy suit ... head absolutely still ...",
+        )
+        # path is a local mp4 file → copy to v2-compatible/ and run motion_grammar
+    """
     try:
-        import imageio.v3 as iio
+        from gradio_client import Client, handle_file
     except ImportError as e:
-        raise ImportError(
-            "Loading the Space's video response requires imageio. Install with:\n"
-            "  pip install -e '.[hf]'"
-        ) from e
-    frames = iio.imread(str(video_path))
-    if frames.ndim != 4:
-        raise ValueError(f"unexpected video shape from Space: {frames.shape}")
-    return _new_framestack(frames.astype(np.uint8), fps=8, name=f"hf_space:{preset}")
+        raise ImportError(INSTALL_HINT) from e
 
+    token = _resolve_hf_token(hf_token)
+    client = Client(space_id, token=token)
 
-def _gradio_client_available() -> bool:
-    try:
-        import gradio_client  # noqa: F401
-        return True
-    except ImportError:
-        return False
+    result = client.predict(
+        handle_file(image_path),
+        prompt,
+        negative_prompt,
+        float(height),
+        float(width),
+        float(num_frames),
+        float(num_inference_steps),
+        float(guidance_scale),
+        float(seed),
+        api_name=api_name,
+    )
+    return result if isinstance(result, str) else result[0]
 
 
 def generate_sprite_via_space(
@@ -188,18 +203,7 @@ def generate_sprite_via_space(
     hf_token: Optional[str] = None,
     api_name: str = "/infer_txt2img",
 ) -> PILImage.Image:
-    """Call the Space's txt2img endpoint and return the generated sprite.
-
-    This is a free-standing helper (not bound to the cursor/motion abstraction).
-    A sprite is a fresh artifact, not a transform — wrapping it in a PixelCursor
-    would add ceremony without benefit.
-
-    Prompt should include the PixelArtRedmond trigger words "pixel art, PixArFK"
-    to engage the loaded LoRA. lora_weight scales LoRA strength (0.0 disables,
-    1.5 is the upper end; default 0.9).
-
-    Raises ImportError if gradio_client is missing locally.
-    """
+    """Call the Space's txt2img endpoint and return the generated sprite."""
     try:
         from gradio_client import Client
     except ImportError as e:
@@ -219,3 +223,25 @@ def generate_sprite_via_space(
         api_name=api_name,
     )
     return PILImage.open(png_path).convert("RGB")
+
+
+def _video_path_to_framestack(video_path: str | Path, preset: str) -> FrameStack:
+    try:
+        import imageio.v3 as iio
+    except ImportError as e:
+        raise ImportError(
+            "Loading the Space's video response requires imageio. Install with:\n"
+            "  pip install -e '.[hf]'"
+        ) from e
+    frames = iio.imread(str(video_path))
+    if frames.ndim != 4:
+        raise ValueError(f"unexpected video shape from Space: {frames.shape}")
+    return _new_framestack(frames.astype(np.uint8), fps=8, name=f"hf_space:{preset}")
+
+
+def _gradio_client_available() -> bool:
+    try:
+        import gradio_client  # noqa: F401
+        return True
+    except ImportError:
+        return False