strands-diffusers 0.1.0__tar.gz

strands_diffusers-0.1.0/.github/workflows/auto-release.yml

@@ -0,0 +1,90 @@
+name: Auto Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  auto-release:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0          # full history + tags for setuptools-scm
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install build tooling
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Extract version from tag
+      id: get_version
+      run: |
+        VERSION=${GITHUB_REF#refs/tags/v}
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Version: $VERSION"
+
+    - name: Build package (version derived from git tag via setuptools-scm)
+      run: python -m build
+
+    - name: Verify built version matches tag
+      run: |
+        ls -l dist/
+        if ! ls dist/ | grep -q "${{ steps.get_version.outputs.version }}"; then
+          echo "::error::Built artifact does not match tag version ${{ steps.get_version.outputs.version }}"
+          ls dist/
+          exit 1
+        fi
+
+    - name: Publish to PyPI
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+      run: twine upload dist/*
+
+    - name: Create GitHub Release
+      uses: softprops/action-gh-release@v2
+      with:
+        tag_name: ${{ github.ref_name }}
+        name: strands-diffusers v${{ steps.get_version.outputs.version }}
+        body: |
+          ## 🎨 strands-diffusers v${{ steps.get_version.outputs.version }}
+
+          The universal entrypoint to HuggingFace `diffusers` for Strands agents —
+          100% pipeline & modality coverage, zero hardcoding.
+
+          ### 📦 Installation
+          ```bash
+          pip install strands-diffusers==${{ steps.get_version.outputs.version }}
+          # extras: pip install "strands-diffusers[video,audio]"
+          ```
+
+          ### 🔄 Upgrade
+          ```bash
+          pip install --upgrade strands-diffusers
+          ```
+
+          **Full Changelog**: https://github.com/cagataycali/strands-diffusers/releases
+        draft: false
+        prerelease: false
+
+    - name: Summary
+      run: |
+        echo "## 🎉 Release Summary" >> $GITHUB_STEP_SUMMARY
+        echo "" >> $GITHUB_STEP_SUMMARY
+        echo "- **Version:** v${{ steps.get_version.outputs.version }}" >> $GITHUB_STEP_SUMMARY
+        echo "- **PyPI:** https://pypi.org/project/strands-diffusers/${{ steps.get_version.outputs.version }}/" >> $GITHUB_STEP_SUMMARY
+        echo "- **GitHub Release:** https://github.com/cagataycali/strands-diffusers/releases/tag/v${{ steps.get_version.outputs.version }}" >> $GITHUB_STEP_SUMMARY

strands_diffusers-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # full history+tags so setuptools-scm can derive version
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[video,audio,dev]"
+      - name: Unit tests (no GPU, no model downloads)
+        run: pytest tests/ -q
+      - name: Smoke E2E (tiny fixtures)
+        env:
+          TOKENIZERS_PARALLELISM: "false"
+        run: python examples/smoke.py

strands_diffusers-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.pyc
+*.egg-info/
+build/
+dist/
+.venv/
+*.mp4
+*.png
+*.jpg
+*.wav
+*.json.tmp
+assets/
+.coverage
+system_prompt.prompt
+__pycache__/
+*.pyc
+.pytest_cache/
+strands_diffusers/_version.py
+build/
+.pytest_cache/
+__pycache__/

strands_diffusers-0.1.0/PKG-INFO

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: strands-diffusers
+Version: 0.1.0
+Summary: The universal entrypoint to HuggingFace diffusers for Strands agents — 100% pipeline & modality coverage, zero hardcoding. Special focus on Physical-AI world-foundation models (Cosmos) with robot action outputs.
+Author-email: Cagatay Cali <cagataycali@icloud.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cagataycali/strands-diffusers
+Project-URL: Repository, https://github.com/cagataycali/strands-diffusers
+Project-URL: Issues, https://github.com/cagataycali/strands-diffusers/issues
+Keywords: strands,diffusers,huggingface,ai,agents,diffusion,video,image,vla,wfm,world-foundation-model,cosmos,robotics,physical-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: strands-agents
+Requires-Dist: diffusers>=0.30
+Requires-Dist: transformers>=4.40
+Requires-Dist: torch
+Requires-Dist: pillow
+Requires-Dist: numpy
+Requires-Dist: accelerate
+Provides-Extra: video
+Requires-Dist: imageio[ffmpeg]; extra == "video"
+Requires-Dist: opencv-python; extra == "video"
+Requires-Dist: av; extra == "video"
+Provides-Extra: audio
+Requires-Dist: soundfile; extra == "audio"
+Requires-Dist: librosa; extra == "audio"
+Provides-Extra: cosmos
+Requires-Dist: cosmos_guardrail; extra == "cosmos"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: all
+Requires-Dist: strands-diffusers[audio,dev,video]; extra == "all"
+
+# 🎨 strands-diffusers
+
+**The universal entrypoint to HuggingFace `diffusers` for Strands agents — 100%
+pipeline & modality coverage, zero hardcoding.**
+
+Just like [`use_aws`](https://github.com/strands-agents) wraps boto3,
+[`use_lerobot`](https://github.com/cagataycali) wraps lerobot, and
+[`use_transformers`](https://github.com/cagataycali/strands-transformers) wraps the
+transformers task taxonomy, **`use_diffusers`** wraps the *entire* diffusers
+library behind a single tool. Discover, don't hardcode: the registry is built at
+runtime from `diffusers._import_structure`, so when diffusers ships a new pipeline
+(say, a fresh Cosmos world-foundation model), strands-diffusers supports it
+**automatically — no code change required**.
+
+```
+text / image / video / robot-state  IN
+image / video / audio / ACTIONS      OUT   — natively.
+```
+
+## 🌍 Physical-AI focus: world-foundation models with action outputs
+
+The headline use-case is **NVIDIA Cosmos** and other world-foundation models
+(WFMs). A Cosmos 3 *action-policy* rollout doesn't just generate a plausible
+future video — it predicts the **robot action chunk** that produces it. A single
+`use_diffusers(action="run", ...)` call returns BOTH:
+
+- a playable world **video** (`.mp4`)
+- the predicted **action** chunk in model-normalized action space (`.json`,
+  shape `[num_chunks, T, action_dim]`)
+- (optionally) synchronized **sound** (`.wav`)
+
+— all surfaced as artifact paths, ready to hand to a robot controller or the user.
+
+> **Verified end-to-end** on NVIDIA Thor (diffusers `0.39.0.dev0`, `nvidia/Cosmos3-Nano`,
+> bf16/cuda): one `use_diffusers(action="run", pipeline="Cosmos3OmniPipeline", ...)`
+> call produced a world video `(17, 480, 640, 3)` **and** a robot action chunk
+> `(1, 16, 10)` = `(num_chunks, T, action_dim)`, normalized to `[-1, 1]`.
+> See [`examples/cosmos_action_policy.py`](examples/cosmos_action_policy.py) and
+> [`examples/SETUP_COSMOS.md`](examples/SETUP_COSMOS.md).
+
+## Install
+
+```bash
+pip install -e .
+# optional extras:
+pip install -e ".[video,audio]"   # mp4 export, wav I/O
+```
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_diffusers import use_diffusers
+
+agent = Agent(tools=[use_diffusers])
+agent("Generate an image of a robot arm in a kitchen")
+agent("Run a Cosmos action-policy rollout on robot.mp4 and give me the actions")
+```
+
+Or drive it directly:
+
+```python
+from strands_diffusers import use_diffusers
+
+# text → image
+use_diffusers(
+    action="run",
+    pipeline="StableDiffusionPipeline",
+    model="stabilityai/stable-diffusion-2-1",
+    parameters={"prompt": "a robot arm in a kitchen", "num_inference_steps": 25},
+)
+```
+
+## Two layers
+
+### 1. `run` — high-level pipeline runner
+
+Loads a pipeline class via `from_pretrained` and calls it. Inputs are coerced
+(paths / URLs / base64 → PIL / video); outputs (image / video / audio / action)
+are auto-saved and returned by path.
+
+```python
+use_diffusers(action="run", pipeline="WanPipeline", model="...",
+              parameters={"prompt": "...", "num_frames": 81}, fps=16)
+```
+
+### 2. `call` — low-level dynamic dispatch
+
+Resolve & call *any* diffusers class / function / method — schedulers, VAEs,
+`CosmosActionCondition`, `utils.export_to_video`, or a cached pipeline's method.
+`cached:key` references resolve to live objects; the `"**"` key unpacks a cached
+mapping into kwargs (the `pipe(**inputs)` pattern).
+
+```python
+# Build a Cosmos action condition, cache it, then run an action-policy rollout.
+use_diffusers(action="call", target="CosmosActionCondition",
+              parameters={"mode": "policy", "chunk_size": 16,
+                          "domain_name": "bridge_orig_lerobot",
+                          "resolution_tier": 480, "video": "robot.mp4",
+                          "view_point": "ego_view"},
+              cache_key="act_cond")
+
+use_diffusers(action="run", pipeline="Cosmos3OmniPipeline", model="nvidia/Cosmos3-Nano",
+              parameters={"prompt": "Put the pot to the left of the purple item.",
+                          "action": "cached:act_cond", "fps": 5,
+                          "num_inference_steps": 30, "guidance_scale": 1.0,
+                          "use_system_prompt": False},
+              dtype="bfloat16", device="cuda")
+# → artifacts: cosmos_world.mp4  +  action chunk .json  ([1, 16, action_dim])
+```
+
+## Discovery (the agent never guesses)
+
+| action | what it returns |
+|---|---|
+| `pipelines` | all 300+ pipeline classes + derived modality |
+| `models` | every model class (VAEs, transformers, controlnets) |
+| `schedulers` | every scheduler class |
+| `tasks` | diffusers' `AutoPipeline` task → `{family: class}` maps |
+| `modalities` | pipelines grouped by modality (image / video / world / audio / **3d** mesh) |
+| `wfm` | world-foundation / action-capable pipelines (Cosmos, Wan, Hunyuan) |
+| `pipeline_info` | modality + `__call__` signature for one pipeline class |
+| `inspect` | signature + docstring of any target |
+| `visualize` | render a robot ACTION chunk → time-series + 3D trajectory + animation (mp4/gif) |
+| `cache` / `clear_cache` | manage loaded pipelines (free GPU memory) |
+
+## Architecture
+
+```
+strands_diffusers/
+├── core/
+│   ├── registry.py   # zero-hardcode taxonomy from diffusers._import_structure
+│   ├── engine.py     # load/cache pipelines, auto device+dtype
+│   └── io.py         # coerce inputs; serialize video/image/audio/ACTION outputs
+└── tools/
+    └── use_diffusers.py   # the single @tool: run + call + discovery
+```
+
+## Testing
+
+```bash
+pip install -e ".[video,audio,dev]"
+pytest tests/ -q          # 26 unit tests — no GPU, no model downloads
+python examples/smoke.py  # E2E gate on tiny HF fixtures
+```
+
+`tests/` covers the registry classifier (golden modalities + a guard that no
+video/WFM pipeline is ever mislabeled as a still image), and the multimodal I/O
+serializers — image, video (incl. `list[ndarray]`), **stereo audio** (channels-
+first *and* channels-last), the robot **action** chunk, and **3D mesh** output
+(ShapE → `.ply`/`.obj`/`.npz`). CI runs both on py3.10 + py3.12.
+
+## License
+
+MIT

strands_diffusers-0.1.0/README.md

@@ -0,0 +1,155 @@
+# 🎨 strands-diffusers
+
+**The universal entrypoint to HuggingFace `diffusers` for Strands agents — 100%
+pipeline & modality coverage, zero hardcoding.**
+
+Just like [`use_aws`](https://github.com/strands-agents) wraps boto3,
+[`use_lerobot`](https://github.com/cagataycali) wraps lerobot, and
+[`use_transformers`](https://github.com/cagataycali/strands-transformers) wraps the
+transformers task taxonomy, **`use_diffusers`** wraps the *entire* diffusers
+library behind a single tool. Discover, don't hardcode: the registry is built at
+runtime from `diffusers._import_structure`, so when diffusers ships a new pipeline
+(say, a fresh Cosmos world-foundation model), strands-diffusers supports it
+**automatically — no code change required**.
+
+```
+text / image / video / robot-state  IN
+image / video / audio / ACTIONS      OUT   — natively.
+```
+
+## 🌍 Physical-AI focus: world-foundation models with action outputs
+
+The headline use-case is **NVIDIA Cosmos** and other world-foundation models
+(WFMs). A Cosmos 3 *action-policy* rollout doesn't just generate a plausible
+future video — it predicts the **robot action chunk** that produces it. A single
+`use_diffusers(action="run", ...)` call returns BOTH:
+
+- a playable world **video** (`.mp4`)
+- the predicted **action** chunk in model-normalized action space (`.json`,
+  shape `[num_chunks, T, action_dim]`)
+- (optionally) synchronized **sound** (`.wav`)
+
+— all surfaced as artifact paths, ready to hand to a robot controller or the user.
+
+> **Verified end-to-end** on NVIDIA Thor (diffusers `0.39.0.dev0`, `nvidia/Cosmos3-Nano`,
+> bf16/cuda): one `use_diffusers(action="run", pipeline="Cosmos3OmniPipeline", ...)`
+> call produced a world video `(17, 480, 640, 3)` **and** a robot action chunk
+> `(1, 16, 10)` = `(num_chunks, T, action_dim)`, normalized to `[-1, 1]`.
+> See [`examples/cosmos_action_policy.py`](examples/cosmos_action_policy.py) and
+> [`examples/SETUP_COSMOS.md`](examples/SETUP_COSMOS.md).
+
+## Install
+
+```bash
+pip install -e .
+# optional extras:
+pip install -e ".[video,audio]"   # mp4 export, wav I/O
+```
+
+## Quick start
+
+```python
+from strands import Agent
+from strands_diffusers import use_diffusers
+
+agent = Agent(tools=[use_diffusers])
+agent("Generate an image of a robot arm in a kitchen")
+agent("Run a Cosmos action-policy rollout on robot.mp4 and give me the actions")
+```
+
+Or drive it directly:
+
+```python
+from strands_diffusers import use_diffusers
+
+# text → image
+use_diffusers(
+    action="run",
+    pipeline="StableDiffusionPipeline",
+    model="stabilityai/stable-diffusion-2-1",
+    parameters={"prompt": "a robot arm in a kitchen", "num_inference_steps": 25},
+)
+```
+
+## Two layers
+
+### 1. `run` — high-level pipeline runner
+
+Loads a pipeline class via `from_pretrained` and calls it. Inputs are coerced
+(paths / URLs / base64 → PIL / video); outputs (image / video / audio / action)
+are auto-saved and returned by path.
+
+```python
+use_diffusers(action="run", pipeline="WanPipeline", model="...",
+              parameters={"prompt": "...", "num_frames": 81}, fps=16)
+```
+
+### 2. `call` — low-level dynamic dispatch
+
+Resolve & call *any* diffusers class / function / method — schedulers, VAEs,
+`CosmosActionCondition`, `utils.export_to_video`, or a cached pipeline's method.
+`cached:key` references resolve to live objects; the `"**"` key unpacks a cached
+mapping into kwargs (the `pipe(**inputs)` pattern).
+
+```python
+# Build a Cosmos action condition, cache it, then run an action-policy rollout.
+use_diffusers(action="call", target="CosmosActionCondition",
+              parameters={"mode": "policy", "chunk_size": 16,
+                          "domain_name": "bridge_orig_lerobot",
+                          "resolution_tier": 480, "video": "robot.mp4",
+                          "view_point": "ego_view"},
+              cache_key="act_cond")
+
+use_diffusers(action="run", pipeline="Cosmos3OmniPipeline", model="nvidia/Cosmos3-Nano",
+              parameters={"prompt": "Put the pot to the left of the purple item.",
+                          "action": "cached:act_cond", "fps": 5,
+                          "num_inference_steps": 30, "guidance_scale": 1.0,
+                          "use_system_prompt": False},
+              dtype="bfloat16", device="cuda")
+# → artifacts: cosmos_world.mp4  +  action chunk .json  ([1, 16, action_dim])
+```
+
+## Discovery (the agent never guesses)
+
+| action | what it returns |
+|---|---|
+| `pipelines` | all 300+ pipeline classes + derived modality |
+| `models` | every model class (VAEs, transformers, controlnets) |
+| `schedulers` | every scheduler class |
+| `tasks` | diffusers' `AutoPipeline` task → `{family: class}` maps |
+| `modalities` | pipelines grouped by modality (image / video / world / audio / **3d** mesh) |
+| `wfm` | world-foundation / action-capable pipelines (Cosmos, Wan, Hunyuan) |
+| `pipeline_info` | modality + `__call__` signature for one pipeline class |
+| `inspect` | signature + docstring of any target |
+| `visualize` | render a robot ACTION chunk → time-series + 3D trajectory + animation (mp4/gif) |
+| `cache` / `clear_cache` | manage loaded pipelines (free GPU memory) |
+
+## Architecture
+
+```
+strands_diffusers/
+├── core/
+│   ├── registry.py   # zero-hardcode taxonomy from diffusers._import_structure
+│   ├── engine.py     # load/cache pipelines, auto device+dtype
+│   └── io.py         # coerce inputs; serialize video/image/audio/ACTION outputs
+└── tools/
+    └── use_diffusers.py   # the single @tool: run + call + discovery
+```
+
+## Testing
+
+```bash
+pip install -e ".[video,audio,dev]"
+pytest tests/ -q          # 26 unit tests — no GPU, no model downloads
+python examples/smoke.py  # E2E gate on tiny HF fixtures
+```
+
+`tests/` covers the registry classifier (golden modalities + a guard that no
+video/WFM pipeline is ever mislabeled as a still image), and the multimodal I/O
+serializers — image, video (incl. `list[ndarray]`), **stereo audio** (channels-
+first *and* channels-last), the robot **action** chunk, and **3D mesh** output
+(ShapE → `.ply`/`.obj`/`.npz`). CI runs both on py3.10 + py3.12.
+
+## License
+
+MIT

strands_diffusers-0.1.0/examples/README.md

@@ -0,0 +1,52 @@
+# strands-diffusers examples
+
+All examples import the real `use_diffusers` tool and run **real diffusion
+inference** (no mocks). The image/video examples use tiny HF test fixtures so they
+run fast on any machine — swap `model` for a full checkpoint to get real quality.
+
+| example | what it shows | path used | model |
+|---|---|---|---|
+| `text_to_image.py` | text → image, image→png artifact | `run` | tiny-stable-diffusion-pipe |
+| `text_to_video.py` | text → video, video→mp4 artifact | `run` | tiny-random-ltx-video |
+| `cosmos_action_policy.py` | **WFM action-policy: video + robot ACTION out** | `call` + `run` | nvidia/Cosmos3-Nano |
+| `smoke.py` | fast E2E gate (discovery + img + video + action serializer) | all | tiny fixtures |
+
+## run vs call
+
+- **`run`** — high-level. Give it a `pipeline` class name + `model` repo +
+  `parameters`. It loads (and caches) the pipeline, coerces inputs, runs it, and
+  serializes every output (image/video/audio/**action**) to an artifact path.
+
+- **`call`** — low-level dynamic dispatch. Resolve & call *any* diffusers class,
+  function, or method: schedulers, VAEs, `CosmosActionCondition`,
+  `utils.export_to_video`, or a cached pipeline's method. Use `cache_key` to stash
+  a constructed object and `cached:key` (or `{"**": "cached:key"}`) to feed it
+  back into a later call. This is how the Cosmos example builds an action
+  condition and threads it into the pipeline run.
+
+## The action payload (why this library exists)
+
+World-foundation models like NVIDIA Cosmos 3 emit a `Cosmos3OmniPipelineOutput`
+with `video`, optional `sound`, and **`action`** (a `list[torch.Tensor]`, each a
+normalized action chunk `[T, action_dim]`). `core/io.py` serializes:
+
+- `video`  → `.mp4`  (via `diffusers.utils.export_to_video`, imageio fallback, gif last resort)
+- `sound`  → `.wav`  (soundfile or stdlib `wave`)
+- `action` → `.json` (full nested list + `chunk_shape` / `num_chunks` metadata)
+
+So one `use_diffusers(action="run", ...)` hands the agent both a playable world and
+a robot-ready action vector.
+
+## Cosmos3OmniPipeline availability
+
+`Cosmos3OmniPipeline` ships in **diffusers from source** (>0.38). `use_diffusers`
+resolves pipeline classes dynamically, so the moment your diffusers has it, the
+example works unchanged:
+
+```bash
+pip install 'git+https://github.com/huggingface/diffusers'
+python examples/cosmos_action_policy.py
+```
+
+On older diffusers the example degrades gracefully and still lists the
+action-capable WFM pipelines available now (Cosmos2*, CosmosVideoToWorld, Wan, …).

strands_diffusers-0.1.0/examples/SETUP_COSMOS.md

@@ -0,0 +1,56 @@
+# Running real Cosmos 3 (action-policy) with strands-diffusers
+
+`Cosmos3OmniPipeline` + `CosmosActionCondition` ship in **diffusers from source**
+(>0.38). `use_diffusers` resolves pipeline classes dynamically, so no code change
+is needed once they're importable.
+
+## Option A — install from source into your env
+
+```bash
+pip install 'git+https://github.com/huggingface/diffusers'
+python examples/cosmos_action_policy.py
+```
+
+## Option B — side-load from source (don't disturb a pinned diffusers)
+
+Install only the diffusers source tree (no deps) and prepend it to `PYTHONPATH`,
+reusing your existing torch / transformers:
+
+```bash
+pip install 'git+https://github.com/huggingface/diffusers' --no-deps --target /tmp/dmain
+PYTHONPATH=/tmp/dmain python examples/cosmos_action_policy.py
+```
+
+This is exactly how the example above was verified end-to-end.
+
+## What you get
+
+A single `use_diffusers(action="run", pipeline="Cosmos3OmniPipeline", ...)` returns
+a `Cosmos3OmniPipelineOutput` that `core/io.py` serializes to artifacts:
+
+```
+📎 artifacts:
+  • /tmp/strands_diffusers/video_*.mp4    # world rollout  (17, 480, 640, 3)
+  • /tmp/strands_diffusers/action_*.json  # robot actions  (1, 16, 10)
+```
+
+The action JSON is the model-normalized action chunk `[num_chunks, T, action_dim]`
+(values in `[-1, 1]`) — feed it straight to your embodiment's un-normalizer /
+controller. Pick `domain_name` to match your robot (e.g. `bridge_orig_lerobot`).
+
+## Action modes (see the Cosmos 3 docs)
+
+- `policy` — predict future video **and** actions from the first frame + task.
+- `forward_dynamics` — roll out video from a first frame + a given `raw_actions` seq.
+- `inverse_dynamics` — infer the actions connecting the frames of a conditioning video.
+
+Build the condition with `use_diffusers(action="call",
+target="CosmosActionCondition", parameters={...}, cache_key="cond")` then pass
+`parameters={"action": "cached:cond"}` to the run.
+
+## Notes
+
+- ~33 GB of weights for `nvidia/Cosmos3-Nano`; needs a CUDA GPU.
+- The default NVIDIA guardrail (`cosmos_guardrail`) is on under the model license.
+  These demos pass `enable_safety_checker=False` for development; keep it enabled
+  for anything public-facing.