[feat] Add LingBot-World v2 causal-fast streaming support

CLAUDE.md

@@ -6,7 +6,7 @@ TeleFuser is a high-performance framework for efficient multimodal generation mo
 
 **Tech Stack:** Python 3.10-3.13, PyTorch 2.6+, CUDA 12.8+, FastAPI, Ray
 
-**Supported Models:** WanVideo (Wan2.1/2.2), Qwen-Image, Z-Image, FlashVSR, HunyuanVideo, Flux2 Klein, LTX Video, LiveAct, LongCat-Video
+**Supported Models:** WanVideo (Wan2.1/2.2), Qwen-Image, Z-Image, FlashVSR, HunyuanVideo, Flux2 Klein, LTX Video, LiveAct, LongCat-Video, LingBot-World
 
 ## Commands
 
@@ -41,6 +41,8 @@ telefuser/
 │   ├── ltx_video/    # LTX Video: I2V + Audio
 │   ├── liveact/      # LiveAct: S2V (speech-to-video)
 │   ├── longcat_video/ # LongCat-Video: T2V, I2V
+│   ├── lingbot_world_fast/  # LingBot shared causal-fast engine
+│   ├── lingbot_world_v2/    # LingBot-World v2 causal-fast facade
 │   └── common/       # Shared pipeline utilities
 ├── models/           # Model architectures: DiT, VAE, text encoders
 ├── ops/              # Custom operations: attention, FFN, normalization
@@ -66,6 +68,11 @@ telefuser/
 └── client/           # Python SDK
 ```
 
+### LingBot Streaming State
+
+- Long-running LingBot sessions generate noise and VAE condition latents per chunk; do not retain duration-sized chunk lists.
+- Incremental VAE encoder and decoder feature caches must be session-owned so concurrent sessions remain isolated.
+
 ### Layer Architecture Principles For Models
 
 TeleFuser's model follows a strict layered architecture for operations:

README.md

@@ -17,6 +17,8 @@ TeleFuser is a high-performance runtime for world model inference and multimodal
 
 ## News 📰
 
+- ✨ **2026-07-15**: Added [**LingBot-World v2**](https://github.com/Robbyant/lingbot-world-v2) support for offline generation, interactive WebRTC streaming, and multi-GPU inference.
+
 - ✨ **2026-07-06**: Added external **CacheSeek** latent cache integration for service-mode cross-request reuse. Cache hits can skip the first N denoising steps; the Wan2.2 cache-enabled service example snapshots `[5, 10, 15, 20, 25]` by default. See [docs/en/latent_cache.md](docs/en/latent_cache.md).
 
 ## Why TeleFuser
@@ -79,7 +81,9 @@ video = pipe(
 
 ### 2. Real-Time World Model Demo
 
-TeleFuser includes a bidirectional WebRTC demo for `LingBot-World-Fast`.
+TeleFuser includes a bidirectional WebRTC demo for `LingBot-World v2`.
+LingBot-World v2 uses camera control and its v2 PPL defaults; its streaming example caps a session at two minutes.
+
 
 For a laptop browser connected through VS Code Remote SSH, coturn is the only additional system package required;
 no extra Python package is needed. On Debian or Ubuntu, install it with:
@@ -98,15 +102,13 @@ CUDA_VISIBLE_DEVICES=0,1,2,3 \
 TELEFUSER_TURN_SERVER='turn:127.0.0.1:3478?transport=tcp' \
 TELEFUSER_TURN_USERNAME=telefuser \
 TELEFUSER_TURN_CREDENTIAL=telefuser-turn \
-telefuser stream-serve examples/lingbot/stream_lingbot_world_fast.py \
+telefuser stream-serve examples/lingbot/stream_lingbot_world_v2.py \
   --gpu-num 4 -p 8088 --host 0.0.0.0 --skip-validation
 
 python examples/stream_server/webrtc_bidirectional_demo.py \
   --server-url http://127.0.0.1:8088 \
   --port 8091 \
   --image-path examples/data/lingbot_world_fast/image.jpg \
-  --intrinsics-path examples/data/lingbot_world_fast/intrinsics.npy \
-  --frame-num 321 --chunk-size 3 --sample-shift 10.0 --fps 16 \
   --turn-url 'turn:localhost:3478?transport=tcp' \
   --turn-username telefuser --turn-credential telefuser-turn \
   --force-turn-relay --ice-gather-timeout-ms 30000 --no-open
@@ -126,7 +128,7 @@ ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
 ```
 
 Then open `http://localhost:8091`. The TURN command and credentials above are development examples. See the
-[stream server guide](docs/en/stream_server.md#lingbot-world-fast-streaming) and the
+[stream server guide](docs/en/stream_server.md) and the
 [LingBot example README](examples/lingbot/README.md) for coturn startup and the tested four-H100 setup.
 
 If the browser runs on the same physical machine as TeleFuser, no SSH tunnel or TURN server is needed. Unset all
@@ -178,7 +180,7 @@ telefuser/
 
 | Pipeline | Task | Notes |
 |----------|------|-------|
-| `LingBot-World-Fast` | Bidirectional world-model streaming | Interactive WebRTC control loop via [examples/lingbot/stream_lingbot_world_fast.py](examples/lingbot/stream_lingbot_world_fast.py) |
+| `LingBot-World v2` | Bidirectional world-model streaming | Interactive WebRTC control loop via [examples/lingbot/stream_lingbot_world_v2.py](examples/lingbot/stream_lingbot_world_v2.py) |
 | `LiveAct` | S2V | Speech-driven talking head generation via [examples/liveact/liveact_s2v_h100.py](examples/liveact/liveact_s2v_h100.py) |
 | `FlashVSR` | VSR | Streaming video super-resolution via [examples/flashvsr/README.md](examples/flashvsr/README.md) |
 
@@ -219,7 +221,7 @@ See [examples/README.md](examples/README.md) for the example runner and baseline
 - `AdaTaylorCache` is only calibrated for selected model families.
 - `torch.compile` support is still experimental in parts of the stack.
 - Some optimized paths require specific GPU architectures and CUDA versions.
-- World-model examples such as `LingBot-World-Fast` require external checkpoints and environment setup.
+- World-model examples such as `LingBot-World v2` require external checkpoints and environment setup.
 - Multi-machine deployment exists in the architecture but may require project-specific integration and validation.
 
 ## Development

README_zh.md

@@ -17,6 +17,8 @@ TeleFuser 是一个面向世界模型推理与多模态生成的高性能运行
 
 ## News 📰
 
+- ✨ **2026-07-15**：新增 [**LingBot-World v2**](https://github.com/Robbyant/lingbot-world-v2) 支持，支持离线生成、交互式 WebRTC 流和多卡推理。
+
 - ✨ **2026-07-06**：新增外部 **CacheSeek** latent cache 集成，支持服务模式下跨请求复用；命中后可跳过前 N 步去噪。Wan2.2 服务示例默认快照 `[5, 10, 15, 20, 25]`。配置和安装方式见 [docs/zh/latent_cache.md](docs/zh/latent_cache.md)。
 
 ## 为什么是 TeleFuser
@@ -79,7 +81,9 @@ video = pipe(
 
 ### 2. 实时世界模型 Demo
 
-TeleFuser 当前提供了 `LingBot-World-Fast` 的双向 WebRTC Demo。
+TeleFuser 当前提供了 `LingBot-World v2` 的双向 WebRTC Demo。
+LingBot-World v2 使用相机控制和 v2 PPL 默认值；其流式示例将单个会话上限设为两分钟。
+
 
 通过 VS Code Remote SSH 从笔记本浏览器访问时，coturn 是唯一需要额外安装的系统软件，不需要增加
 Python 包。在 Debian 或 Ubuntu 上执行：
@@ -98,15 +102,13 @@ CUDA_VISIBLE_DEVICES=0,1,2,3 \
 TELEFUSER_TURN_SERVER='turn:127.0.0.1:3478?transport=tcp' \
 TELEFUSER_TURN_USERNAME=telefuser \
 TELEFUSER_TURN_CREDENTIAL=telefuser-turn \
-telefuser stream-serve examples/lingbot/stream_lingbot_world_fast.py \
+telefuser stream-serve examples/lingbot/stream_lingbot_world_v2.py \
   --gpu-num 4 -p 8088 --host 0.0.0.0 --skip-validation
 
 python examples/stream_server/webrtc_bidirectional_demo.py \
   --server-url http://127.0.0.1:8088 \
   --port 8091 \
   --image-path examples/data/lingbot_world_fast/image.jpg \
-  --intrinsics-path examples/data/lingbot_world_fast/intrinsics.npy \
-  --frame-num 321 --chunk-size 3 --sample-shift 10.0 --fps 16 \
   --turn-url 'turn:localhost:3478?transport=tcp' \
   --turn-username telefuser --turn-credential telefuser-turn \
   --force-turn-relay --ice-gather-timeout-ms 30000 --no-open
@@ -126,7 +128,7 @@ ssh -N -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 \
 ```
 
 然后打开 `http://localhost:8091`。上面的 TURN 账号密码仅作为开发配置示例。coturn 启动方式、生产环境
-注意事项及四张 H100 的实测配置见 [流服务文档](docs/zh/stream_server.md#lingbot-world-fast-流式生成)
+注意事项及四张 H100 的实测配置见 [流服务文档](docs/zh/stream_server.md)
 和 [LingBot example README](examples/lingbot/README.md)。
 
 如果浏览器和 TeleFuser 服务运行在同一台物理机器上，则不需要 SSH 隧道或 TURN 服务。清除所有
@@ -179,7 +181,7 @@ telefuser/
 
 | Pipeline | 任务 | 说明 |
 |----------|------|------|
-| `LingBot-World-Fast` | 双向世界模型流式推理 | 交互式 WebRTC 控制闭环，见 [examples/lingbot/stream_lingbot_world_fast.py](examples/lingbot/stream_lingbot_world_fast.py) |
+| `LingBot-World v2` | 双向世界模型流式推理 | 交互式 WebRTC 控制闭环，见 [examples/lingbot/stream_lingbot_world_v2.py](examples/lingbot/stream_lingbot_world_v2.py) |
 | `LiveAct` | S2V | 语音驱动数字人视频生成，见 [examples/liveact/liveact_s2v_h100.py](examples/liveact/liveact_s2v_h100.py) |
 | `FlashVSR` | VSR | 流式视频超分，见 [examples/flashvsr/README.md](examples/flashvsr/README.md) |
 
@@ -220,7 +222,7 @@ telefuser/
 - `AdaTaylorCache` 目前只对部分模型家族提供了校准参数。
 - `torch.compile` 在部分路径上仍处于实验阶段。
 - 一些优化能力依赖特定 GPU 架构和 CUDA 环境。
-- `LingBot-World-Fast` 这类世界模型示例依赖外部权重和额外环境配置。
+- `LingBot-World v2` 这类世界模型示例依赖外部权重和额外环境配置。
 - 多机部署在架构上已有支持，但实际落地通常还需要项目级集成与验证。
 
 ## 开发

examples/lingbot/README.md

@@ -1,18 +1,18 @@
-# LingBot-World-Fast Examples
+# LingBot-World Examples
 
-Offline image-to-video and interactive WebRTC streaming generation with LingBot-World-Fast. This page describes
-the H100 offline example, the LingBot stream service, and the browser camera controller.
+Offline image-to-video and interactive WebRTC streaming generation for LingBot-World-Fast (v1) and LingBot-World
+v2. Both variants use the shared causal-fast streaming engine; their checkpoint layout and PPL defaults differ.
 
 ## Model Directory
 
-The offline example requires the Wan2.2 I2V base model and the LingBot-World-Fast model. The recommended directory
-layout is:
+Both offline examples require the Wan2.2 I2V base model. v1 and v2 use separate LingBot checkpoint directories:
 
 ```text
 ${TF_MODEL_ZOO_PATH}/
 ├── Wan2.2-I2V-A14B/
 └── lingbot/
-    └── lingbot-world-fast/
+    ├── lingbot-world-fast/
+    └── lingbot-world-v2-14b-causal-fast/
 ```
 
 Set the model root before running the example:
@@ -52,6 +52,20 @@ Default configuration:
 - Default control directory: `examples/data/lingbot_world_fast/`
 - Default output: `work_dirs/lingbot_world_fast_i2v_<gpu_num>gpu.mp4`
 
+### lingbot_world_v2_image_to_video_h100.py
+
+Offline camera-controlled v2 generation. The default is 77 frames at 16 FPS: 20 latent frames, exactly five
+complete chunks of four. With complete chunk streaming, 81 output frames cannot be represented by `chunk_size=4`.
+The v2 checkpoint only supports camera control and uses its PPL-configured Torch SDPA, local attention, sink size,
+and timesteps.
+
+```bash
+python examples/lingbot/lingbot_world_v2_image_to_video_h100.py \
+    --gpu_num 4 \
+    --model_root "${TF_MODEL_ZOO_PATH}/Wan2.2-I2V-A14B" \
+    --v2_model_root "${TF_MODEL_ZOO_PATH}/lingbot/lingbot-world-v2-14b-causal-fast"
+```
+
 ## Usage
 
 ### Four H100 GPUs
@@ -88,7 +102,6 @@ python examples/lingbot/lingbot_world_fast_image_to_video_h100.py \
     --action_path /path/to/camera_control \
     --prompt "A cinematic scene with smooth camera motion" \
     --resolution 720p \
-    --frame_num 81 \
     --fps 16 \
     --seed 42 \
     --output work_dirs/lingbot_world_fast_custom.mp4
@@ -117,7 +130,6 @@ python examples/lingbot/lingbot_world_fast_image_to_video_h100.py \
 | `--action_path` | Bundled control directory | Directory containing `poses.npy` and `intrinsics.npy` |
 | `--prompt` | Bundled English prompt | Positive guidance prompt |
 | `--resolution` | `480p` | Output resolution; available values are `480p` and `720p` |
-| `--frame_num` | `81` | Number of output video frames |
 | `--fps` | `16` | Output video frame rate |
 | `--seed` | `42` | Random seed |
 | `--output` | `work_dirs/lingbot_world_fast_i2v_<gpu_num>gpu.mp4` | Output MP4 path |
@@ -130,8 +142,8 @@ python examples/lingbot/lingbot_world_fast_image_to_video_h100.py --help
 
 ## Notes
 
-- `frame_num` must satisfy the pipeline's complete latent-chunk constraint. The default 81 frames correspond to
-  21 latent frames, which are split into seven complete chunks.
+- Offline frame counts are fixed in each example's `PPL_CONFIG`: v1 uses 81 frames (seven complete chunks of
+  three latent frames) and v2 uses 77 frames (five complete chunks of four latent frames).
 - `--gpu_num` must not exceed the number of GPUs visible to the process. For example, set
   `CUDA_VISIBLE_DEVICES=0,1,2,3` to select four devices.
 - The example explicitly closes its parallel workers on exit. If the process is forcibly terminated, check for

examples/lingbot/lingbot_world_fast_image_to_video_h100.py

@@ -47,24 +47,28 @@
 RESOLUTION_AREAS = {"480p": 480 * 832, "720p": 720 * 1280}
 
 PPL_CONFIG = dict(
+    parallelism=1,
     control_mode="cam",
     resolution="480p",
     frame_num=81,
     chunk_size=3,
+    frame_policy="truncate",
     sample_shift=10.0,
     seed=42,
     target_fps=16,
     attn_impl=AttnImplType.SAGE_ATTN_2_8_8_SM90,
     enable_fsdp=False,
     local_attn_size=-1,
     sink_size=0,
+    timestep_indices=(0, 179, 358, 679),
     max_attention_size=None,
+    vae_torch_dtype=torch.float32,
     torch_dtype=torch.bfloat16,
 )
 
 
 def get_pipeline(
-    parallelism: int = 1,
+    parallelism: int = PPL_CONFIG["parallelism"],
     model_root: str | None = None,
     fast_model_root: str | None = None,
 ) -> LingBotWorldFastPipeline:
@@ -82,13 +86,14 @@ def get_pipeline(
         LingBotWorldFastPipelineConfig(
             checkpoint_dir=model_root or default_model_root,
             fast_checkpoint_path=fast_model_root or default_fast_model_root,
-            vae_config=ModelRuntimeConfig(device_type="cuda", device_id=0, torch_dtype=dtype),
+            vae_config=ModelRuntimeConfig(device_type="cuda", device_id=0, torch_dtype=PPL_CONFIG["vae_torch_dtype"]),
             text_encoding_config=ModelRuntimeConfig(device_type="cuda", device_id=0, torch_dtype=dtype),
             dit_torch_dtype=dtype,
             control_type=PPL_CONFIG["control_mode"],
             max_area=RESOLUTION_AREAS[PPL_CONFIG["resolution"]],
             local_attn_size=PPL_CONFIG["local_attn_size"],
             sink_size=PPL_CONFIG["sink_size"],
+            timestep_indices=PPL_CONFIG["timestep_indices"],
             attention_config=AttentionConfig.dense_attention(PPL_CONFIG["attn_impl"]),
             parallel_config=ParallelConfig(
                 device_ids=list(range(parallelism)) if parallelism > 1 else None,
@@ -107,14 +112,12 @@ def run(
     seed: int = PPL_CONFIG["seed"],
     resolution: str = PPL_CONFIG["resolution"],
     action_path: str = DEFAULT_ACTION_PATH,
-    frame_num: int | None = None,
     fps: int | None = None,
 ) -> list[Image.Image]:
     """Generate a complete offline video through the pipeline core API."""
     if resolution not in RESOLUTION_AREAS:
         raise ValueError(f"Unsupported resolution: {resolution}")
     pipeline.config.max_area = RESOLUTION_AREAS[resolution]
-    frame_num = PPL_CONFIG["frame_num"] if frame_num is None else frame_num
     fps = PPL_CONFIG["target_fps"] if fps is None else fps
 
     session_config = LingBotWorldFastSessionConfig(
@@ -123,7 +126,8 @@ def run(
         control_mode=PPL_CONFIG["control_mode"],
         fps=fps,
         chunk_size=PPL_CONFIG["chunk_size"],
-        frame_num=frame_num,
+        frame_policy=PPL_CONFIG["frame_policy"],
+        frame_num=PPL_CONFIG["frame_num"],
         sample_shift=PPL_CONFIG["sample_shift"],
         seed=seed,
         max_attention_size=PPL_CONFIG["max_attention_size"],
@@ -157,7 +161,7 @@ def run(
 @click.command()
 @click.option(
     "--gpu_num",
-    default=1,
+    default=PPL_CONFIG["parallelism"],
     type=int,
     help="Number of GPUs used for Ulysses sequence parallelism",
 )
@@ -166,7 +170,6 @@ def run(
 @click.option("--prompt", default=DEFAULT_PROMPT, help="Positive guidance prompt")
 @click.option("--seed", default=PPL_CONFIG["seed"], type=int)
 @click.option("--resolution", default=PPL_CONFIG["resolution"], type=click.Choice(list(RESOLUTION_AREAS)))
-@click.option("--frame_num", default=PPL_CONFIG["frame_num"], type=int, help="Number of output frames")
 @click.option("--fps", default=PPL_CONFIG["target_fps"], type=int, help="Output video frame rate")
 @click.option("--model_root", default=None, type=click.Path(exists=True, file_okay=False))
 @click.option(
@@ -182,7 +185,6 @@ def main(
     prompt: str,
     seed: int,
     resolution: str,
-    frame_num: int,
     fps: int,
     model_root: str,
     fast_model_root: str,
@@ -201,7 +203,6 @@ def main(
             seed=seed,
             resolution=resolution,
             action_path=action_path,
-            frame_num=frame_num,
             fps=fps,
         )
         elapsed = time.perf_counter() - start