From 4e8dff733370257d317adfd7b568d53521f49bc9 Mon Sep 17 00:00:00 2001
From: Sylvester Kaczmarek
 <16242628+sylvesterkaczmarek@users.noreply.github.com>
Date: Sat, 31 Oct 2026 01:03:43 +0000
Subject: [PATCH 1/2] Clarify raw vLLM video frame-sampling requests

Signed-off-by: Sylvester Kaczmarek <16242628+sylvesterkaczmarek@users.noreply.github.com>
---
 .../cookbooks/cosmos3/reasoner/README.md      | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/.agents/skills/cookbooks/cosmos3/reasoner/README.md b/.agents/skills/cookbooks/cosmos3/reasoner/README.md
index 6ad50f53..cf44a004 100644
--- a/.agents/skills/cookbooks/cosmos3/reasoner/README.md
+++ b/.agents/skills/cookbooks/cosmos3/reasoner/README.md
@@ -129,6 +129,33 @@ response = client.chat.completions.create(
 print(response.choices[0].message.content)
 ```
 
+For video requests, frame-sampling controls are multimodal processor options.
+Assuming `messages` contains the video content for your request, pass those
+controls via `extra_body` when using the OpenAI client:
+
+```python
+response = client.chat.completions.create(
+    model=client.models.list().data[0].id,
+    messages=messages,
+    extra_body={"mm_processor_kwargs": {"fps": 4, "do_sample_frames": True}},
+)
+```
+
+For direct `/v1/chat/completions` HTTP requests, put `mm_processor_kwargs`
+inside the JSON body as shown below. Do not send `fps` or
+`do_sample_frames` as standalone top-level chat-completion fields.
+
+```python
+payload = {
+    "model": "Cosmos3-Super",
+    "messages": messages,
+    "mm_processor_kwargs": {"fps": 4, "do_sample_frames": True},
+}
+```
+
+This matters for motion-dependent tasks such as physical plausibility analysis,
+where frame sampling determines which temporal events are visible to the Reasoner.
+
 ### Notebook walkthrough
 
 [`run_with_vllm.ipynb`](./run_with_vllm.ipynb) uses the **Cosmos3-Super** launch

From 7bd3b8e860c31f2f3eb8f9b3ceb81034be432fa7 Mon Sep 17 00:00:00 2001
From: Sylvester Kaczmarek
 <16242628+sylvesterkaczmarek@users.noreply.github.com>
Date: Tue, 3 Nov 2026 09:39:55 +0000
Subject: [PATCH 2/2] docs: align vLLM sampling examples with reasoner notebook

Signed-off-by: Sylvester Kaczmarek <16242628+sylvesterkaczmarek@users.noreply.github.com>
---
 .../cookbooks/cosmos3/reasoner/README.md      | 26 +++++++++++--------
 .../cosmos3/reasoner/reasoner_prompt_guide.md |  7 +++--
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/.agents/skills/cookbooks/cosmos3/reasoner/README.md b/.agents/skills/cookbooks/cosmos3/reasoner/README.md
index cf44a004..f1e4c80a 100644
--- a/.agents/skills/cookbooks/cosmos3/reasoner/README.md
+++ b/.agents/skills/cookbooks/cosmos3/reasoner/README.md
@@ -129,32 +129,36 @@ response = client.chat.completions.create(
 print(response.choices[0].message.content)
 ```
 
-For video requests, frame-sampling controls are multimodal processor options.
-Assuming `messages` contains the video content for your request, pass those
-controls via `extra_body` when using the OpenAI client:
+For video requests, the accompanying `run_with_vllm.ipynb` notebook samples
+video frames through vLLM's media loader. If `messages` contains the video
+content for your request, pass the same options via `extra_body` when using
+the OpenAI client:
 
 ```python
 response = client.chat.completions.create(
     model=client.models.list().data[0].id,
     messages=messages,
-    extra_body={"mm_processor_kwargs": {"fps": 4, "do_sample_frames": True}},
+    extra_body={"media_io_kwargs": {"video": {"num_frames": -1, "fps": 4}}},
 )
 ```
 
-For direct `/v1/chat/completions` HTTP requests, put `mm_processor_kwargs`
-inside the JSON body as shown below. Do not send `fps` or
-`do_sample_frames` as standalone top-level chat-completion fields.
+For direct `/v1/chat/completions` HTTP requests, put the equivalent
+`media_io_kwargs` object in the JSON body:
 
 ```python
 payload = {
-    "model": "Cosmos3-Super",
+    "model": "nvidia/Cosmos3-Super",
     "messages": messages,
-    "mm_processor_kwargs": {"fps": 4, "do_sample_frames": True},
+    "media_io_kwargs": {"video": {"num_frames": -1, "fps": 4}},
 }
 ```
 
-This matters for motion-dependent tasks such as physical plausibility analysis,
-where frame sampling determines which temporal events are visible to the Reasoner.
+The model ID above matches the `vllm serve nvidia/Cosmos3-Super` launch
+in the environment setup guide when no `--served-model-name` override is
+specified. Use the model ID returned by `client.models.list()` when in doubt.
+These examples follow the notebook's frame-sampling mechanism; avoid combining
+it with a separate processor-side sampling option without validating how the
+server handles both.
 
 ### Notebook walkthrough
 
diff --git a/.agents/skills/cookbooks/cosmos3/reasoner/reasoner_prompt_guide.md b/.agents/skills/cookbooks/cosmos3/reasoner/reasoner_prompt_guide.md
index ba0f1e98..df7739fb 100644
--- a/.agents/skills/cookbooks/cosmos3/reasoner/reasoner_prompt_guide.md
+++ b/.agents/skills/cookbooks/cosmos3/reasoner/reasoner_prompt_guide.md
@@ -26,12 +26,15 @@ presence_penalty=0.0
 temperature=0.6
 ```
 
-For video inputs, the notebook uses frame sampling through `extra_body`:
+For video inputs, `run_with_vllm.ipynb` uses the media loader's frame
+sampling options through `extra_body`:
 
 ```python
-extra_body={"mm_processor_kwargs": {"fps": 4, "do_sample_frames": True}}
+extra_body={"media_io_kwargs": {"video": {"num_frames": -1, "fps": 4}}}
 ```
 
+This is the same sampling configuration shown in the Reasoner vLLM quickstart.
+
 ### System Prompt
 
 ```text