Add Helios 14B streaming T2V integration

README.md

@@ -99,6 +99,7 @@ runner slugs, multi-GPU commands, and (where available) profiling benchmarks.
 | [Causal Wan2.2](https://nvidia.github.io/flashdreams/main/models/causal_wan22.html) | FastVideo Causal Wan 2.2 14B MoE T2V |
 | [FlashVSR](https://nvidia.github.io/flashdreams/main/models/flashvsr.html) | Streaming video super-resolution |
 | [Cosmos-Predict2.5](https://nvidia.github.io/flashdreams/main/models/cosmos_predict2.html) | Bidirectional T2V / I2V |
+| [Helios](https://nvidia.github.io/flashdreams/main/models/helios.html) | Real-time streaming T2V (14B) |
 
 See [the model gallery](https://nvidia.github.io/flashdreams/main/models/index.html) and
 [the new method guide](https://nvidia.github.io/flashdreams/main/developer_guides/new_integration.html)

docs/source/api/integrations.rst

@@ -58,6 +58,7 @@ Reference integration folders
 - `fastvideo_causal_wan22 <https://github.com/NVIDIA/flashdreams/tree/main/integrations/fastvideo_causal_wan22>`_
 - `flashvsr <https://github.com/NVIDIA/flashdreams/tree/main/integrations/flashvsr>`_
 - `cosmos_predict2 <https://github.com/NVIDIA/flashdreams/tree/main/integrations/cosmos_predict2>`_
+- `helios <https://github.com/NVIDIA/flashdreams/tree/main/integrations/helios>`_
 
 NVIDIA OmniDreams
 -----------------

docs/source/index.rst

@@ -232,6 +232,13 @@ invocation, the checkpoint source, and the per-implementation knobs.
 
       Autoregressive text-to-video based on Wan 2.2 from FastVideo.
 
+   .. grid-item-card:: Helios
+      :class-card: fd-feature
+      :link: models/helios
+      :link-type: doc
+
+      Real-time 14B streaming text-to-video (33-frame chunks).
+
    .. grid-item-card:: LingBot-World
       :class-card: fd-feature
       :link: models/lingbot_world

docs/source/models/helios.rst

@@ -0,0 +1,100 @@
+.. SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-License-Identifier: Apache-2.0
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+Helios
+===================================
+
+.. raw:: html
+
+   <div class="model-link-row">
+     <a class="model-link-button" href="https://github.com/PKU-YuanGroup/Helios" target="_blank" rel="noopener noreferrer">Official code</a>
+     <a class="model-link-button" href="https://huggingface.co/BestWishYsh/Helios-Distilled" target="_blank" rel="noopener noreferrer">Helios-Distilled</a>
+     <a class="model-link-button" href="https://huggingface.co/BestWishYsh/Helios-Base" target="_blank" rel="noopener noreferrer">Helios-Base</a>
+   </div>
+
+`Helios <https://github.com/PKU-YuanGroup/Helios>`_ is a 14B real-time streaming
+text-to-video model. This integration wraps ``HeliosPyramidPipeline`` from
+``diffusers`` and exposes Helios' native **33-frame chunks** through the
+FlashDreams streaming ``generate()`` interface.
+
+Requirements
+------------
+
+- **Minimum VRAM**: ~80 GB (14B transformer + VAE; tested on H100 80GB).
+- **PyTorch**: >= 2.9 (CUDA 13.x recommended; see :doc:`/quickstart/installation`).
+- **diffusers**: ``HeliosPyramidPipeline`` requires a recent ``diffusers`` build
+  (install from source if the PyPI release on your platform does not yet export it):
+
+  .. code-block:: bash
+
+     pip install git+https://github.com/huggingface/diffusers.git
+
+Installation
+------------
+
+.. code-block:: bash
+
+   # from the repo root
+   uv sync --project integrations/helios
+
+Running the method
+------------------
+
+Launch one of the registered runner slugs via ``flashdreams-run``:
+
+.. code-block:: bash
+
+   export HF_TOKEN=<your-hf-token>
+
+   uv run --project integrations/helios \
+       flashdreams-run \
+       helios-distilled-t2v-14b \
+       --prompt "A coastal road at dusk, waves breaking on rocky cliffs, cinematic wide shot" \
+       --pixel-height 384 --pixel-width 640 \
+       --total-blocks 3
+
+We provide the following variants:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 45 55
+
+   * - Method
+     - Description
+   * - ``helios-distilled-t2v-14b``
+     - ``BestWishYsh/Helios-Distilled`` — fastest inference (pyramid ``[2,2,2]``, no CFG).
+   * - ``helios-base-t2v-14b``
+     - ``BestWishYsh/Helios-Base`` — highest quality (pyramid ``[20,20,20]``, CFG 5.0).
+   * - ``helios-distilled-t2v-14b-2gpu``
+     - Distilled checkpoint with Ulysses context parallelism (``torchrun``, 2+ GPUs).
+
+Multi-GPU (2× H100)
+-------------------
+
+.. code-block:: bash
+
+   torchrun --nproc_per_node=2 --no-python \
+       flashdreams-run helios-distilled-t2v-14b-2gpu \
+       --total-blocks 8
+
+Each ``generate()`` call produces one 33-frame chunk and yields decoded pixels
+immediately, matching Helios' native streaming cadence.
+
+Tests
+-----
+
+.. code-block:: bash
+
+   uv run pytest integrations/helios/tests/test_smoke.py -v

docs/source/models/index.rst

@@ -26,6 +26,7 @@ Models
    causal_wan22
    cosmos_predict2
    flashvsr
+   helios
    lingbot_world
    wan21
 
@@ -106,6 +107,13 @@ uses, and the settings you can tune.
 
       Autoregressive text-to-video based on Wan 2.2 from FastVideo.
 
+   .. grid-item-card:: Helios
+      :class-card: fd-feature
+      :link: /models/helios
+      :link-type: doc
+
+      Real-time 14B streaming text-to-video (33-frame chunks).
+
    .. grid-item-card:: LingBot-World
       :class-card: fd-feature
       :link: /models/lingbot_world

integrations/helios/README.md

@@ -0,0 +1,53 @@
+# Helios × FlashDreams
+
+First-party FlashDreams integration for [Helios](https://github.com/PKU-YuanGroup/Helios) 14B real-time streaming video generation (closes [flashdreams#276](https://github.com/NVIDIA/flashdreams/issues/276)).
+
+## Runner slugs
+
+| Slug | Checkpoint | Notes |
+|------|------------|-------|
+| `helios-distilled-t2v-14b` | `BestWishYsh/Helios-Distilled` | Fastest — pyramid `[2,2,2]`, no CFG |
+| `helios-base-t2v-14b` | `BestWishYsh/Helios-Base` | Highest quality — pyramid `[20,20,20]`, CFG 5.0 |
+| `helios-distilled-t2v-14b-2gpu` | `BestWishYsh/Helios-Distilled` | Ulysses context parallelism (`torchrun`) |
+
+Helios generates in **33-frame chunks** natively. Each FlashDreams `generate()` call produces one chunk and yields decoded pixels immediately.
+
+## Install
+
+```bash
+# from the repo root
+export HF_TOKEN=<your-hf-token>
+
+# HeliosPyramidPipeline requires a recent diffusers build
+pip install git+https://github.com/huggingface/diffusers.git
+
+uv sync --project integrations/helios
+```
+
+## Run
+
+```bash
+uv run --project integrations/helios \
+    flashdreams-run helios-distilled-t2v-14b \
+    --prompt "A coastal road at dusk, waves breaking on rocky cliffs, cinematic wide shot" \
+    --total-blocks 3 \
+    --pixel-height 384 --pixel-width 640
+```
+
+Multi-GPU (2× H100):
+
+```bash
+torchrun --nproc_per_node=2 --no-python flashdreams-run helios-distilled-t2v-14b-2gpu \
+  --total-blocks 8
+```
+
+## Tests
+
+```bash
+uv run pytest integrations/helios/tests/test_smoke.py -v
+
+# GPU benchmark (requires CUDA + model weights)
+python integrations/helios/tests/benchmark/run_benchmark.py --mode all
+```
+
+See the [Helios model page](https://nvidia.github.io/flashdreams/main/models/helios.html) for full setup notes.

integrations/helios/config/helios-base-t2v-14b.yaml

@@ -0,0 +1,15 @@
+# Helios-Base 14B T2V — highest quality (pyramid [20,20,20])
+runner: helios-base-t2v-14b
+pipeline:
+  _target_: helios.pipeline.HeliosStreamingPipeline
+checkpoint: BestWishYsh/Helios-Base
+generation:
+  total_blocks: 8
+  width: 640
+  height: 384
+  fps: 24
+  pyramid_steps: [20, 20, 20]
+  guidance_scale: 5.0
+  amplify_first_chunk: true
+  compile: false
+  flash_attention: true

integrations/helios/config/helios-distilled-t2v-14b-2gpu.yaml

@@ -0,0 +1,17 @@
+# Helios-Distilled 14B T2V — Ulysses context parallelism (torchrun --nproc_per_node=2)
+runner: helios-distilled-t2v-14b-2gpu
+pipeline:
+  _target_: helios.pipeline.HeliosStreamingPipeline
+checkpoint: BestWishYsh/Helios-Distilled
+generation:
+  total_blocks: 8
+  width: 640
+  height: 384
+  fps: 24
+  pyramid_steps: [2, 2, 2]
+  guidance_scale: 1.0
+  amplify_first_chunk: true
+  compile: false
+  flash_attention: true
+  enable_parallelism: true
+  cp_backend: ulysses

integrations/helios/config/helios-distilled-t2v-14b.yaml

@@ -0,0 +1,15 @@
+# Helios-Distilled 14B T2V — fastest inference (pyramid [2,2,2])
+runner: helios-distilled-t2v-14b
+pipeline:
+  _target_: helios.pipeline.HeliosStreamingPipeline
+checkpoint: BestWishYsh/Helios-Distilled
+generation:
+  total_blocks: 8
+  width: 640
+  height: 384
+  fps: 24
+  pyramid_steps: [2, 2, 2]
+  guidance_scale: 1.0
+  amplify_first_chunk: true
+  compile: false
+  flash_attention: true

integrations/helios/helios/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""FlashDreams Helios streaming integration."""
+
+from helios.pipeline import HELIOS_CHUNK_FRAMES, HeliosStreamingPipeline
+
+__all__ = ["HELIOS_CHUNK_FRAMES", "HeliosStreamingPipeline"]

integrations/helios/helios/cache.py

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import torch
+from torch import Tensor
+
+from flashdreams.infra.pipeline import StreamInferencePipelineCache
+from helios.encoder import HeliosConditionings
+
+
+@dataclass(kw_only=True)
+class HeliosPipelineCache(StreamInferencePipelineCache):
+    """State shared across AR steps."""
+
+    cond: Optional[HeliosConditionings] = None
+    decoded_chunks: list[Tensor] = field(default_factory=list)
+    history_frames: Optional[Tensor] = None
+    pending_history: Optional[Tensor] = None
+
+    transformer_cache: Any = field(default_factory=dict)
+    encoder_cache: Any = None
+    decoder_cache: Any = None

integrations/helios/helios/compiler.py

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""torch.compile and FlashAttention helpers for Helios."""
+
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+def enable_flash_attention() -> None:
+    """Enable FlashAttention via cuDNN SDPA backend."""
+    torch.backends.cuda.enable_flash_sdp(True)
+    torch.backends.cuda.enable_mem_efficient_sdp(True)
+    torch.backends.cuda.enable_math_sdp(False)
+    print("[Helios compiler] Flash attention (cuDNN) enabled")
+
+
+def compile_transformer(transformer: nn.Module) -> nn.Module:
+    """Compile the Helios DiT for repeated AR chunk calls."""
+    compiled = torch.compile(
+        transformer,
+        mode="default",
+        fullgraph=False,
+        dynamic=True,
+    )
+    print("[Helios compiler] torch.compile applied to DiT transformer (dynamic=True)")
+    return compiled