cosmos-reason1: a 7B vision language model for physical common sense

What physical common sense means for an embodied agent

A robot that can describe a scene is not the same as a robot that can act sensibly in one. Cosmos Reason is described as an open, customizable, 7B parameter reasoning vision language model for physical AI and robotics, and the README's claim is that it lets robots and vision AI agents reason like humans using prior knowledge, physics understanding, and common sense to understand and act in the real world. The model understands space, time, and fundamental physics, and it can serve as a planning model that reasons about what steps an embodied agent might take next. The intended users are robotics teams and researchers who need a reasoning component that produces decisions in natural language rather than a fixed action space. The interesting part is the emphasis on the long tail of diverse scenarios of the physical world with spatial-temporal understanding. That is the hard part of embodied reasoning, and it is where a general purpose video model tends to fall apart.

Post-training with physical common sense and chain-of-thought reasoning

The mechanism behind the behaviour is post-training, and the README is specific about its ingredients. The model is post-trained with physical common sense and embodied reasoning data using supervised fine-tuning and reinforcement learning. It then uses chain-of-thought reasoning capabilities to understand world dynamics without human annotations, which is the part that distinguishes it from a plain captioning model. The consequence is that reasoning steps appear in the output, and the inference examples expose that directly with a flag. A separate news entry from 2025-06-11 records an enhancement to the model's capability on judging the physical plausibility of a video, which is a different question from describing one, and a tutorial under examples/video_critic covers it. The model architecture is based on Qwen2.5-VL, so the upstream repository is the natural place to look for architectural detail and for the wider ecosystem around the base model.

Getting the examples running on a single 24GB GPU

The README is unusually clear that this repository holds documentation, examples, and utilities, and that you do not need it to run inference. The setup instructions exist only for the examples in the repository. System dependencies come first. The Python environment manager is installed with:

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

Then the Hugging Face CLI is installed and authenticated, since the weights live on Hugging Face:

uv tool install -U "huggingface_hub[cli]"
hf auth login

The repository itself is cloned with:

git clone https://github.com/nvidia-cosmos/cosmos-reason1.git
cd cosmos-reason1

For inference the minimum requirement stated in the README is one GPU with 24GB of memory, and the model is included in transformers version 4.51.3 or newer. The pyproject.toml confirms the floor at Python 3.10 with a list of dependencies that includes torch, torchcodec, accelerate, qwen-vl-utils, and transformers, and it pins the PyTorch wheels to a CUDA 12.8 index:

requires-python = ">=3.10"

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

One caveat for anyone reproducing this: the exact index mapping for torch and torchvision lives in a table form in the file rather than in a single line, so treat the pin as a CUDA 12.8 environment rather than a general purpose install.

Three inference entry points: minimal, captioning, and reasoning

A minimal run needs one command:

uv run scripts/inference_sample.py

The fuller script gives you the interesting modes. Captioning a video with the sample asset:

./scripts/inference.py --prompt prompts/caption.yaml --videos assets/sample.mp4 -v

Asking a question and getting the reasoning with it:

./scripts/inference.py --prompt prompts/question.yaml --question 'What are the potential safety hazards?' --reasoning --videos assets/sample.mp4 -v

The third mode captions temporally and drops the input frames to disk for debugging, which is the one to reach for when the model's temporal grounding looks wrong:

./scripts/inference.py --prompt prompts/temporal_caption_text.yaml --videos assets/sample.mp4 --timestamp -v -o outputs/temporal_caption_text

Everything is configurable through three files: the prompts directory, the sampling parameters in configs/sampling_params.yaml, and the vision processor config in configs/vision_config.yaml. The presence of a separate prompt directory rather than inline strings is the useful design detail, since it means prompts can be versioned and shared, and a different task such as the safety hazard question above is a yaml file rather than a code change.

Spatial-temporal reasoning utilities added in August 2025

The news list records that on 2025-08-08 the project added the cosmos-reason1-utils inference utilities package, which adds spatial-temporal reasoning inference and is documented under cosmos_reason1_utils/README.md. A separate entry on 2025-08-01 records support for spatial-temporal reasoning for city and industrial operations, pointing at the Cosmos-Reason1-7B checkpoint. The repository root makes the layout visible: a cosmos_reason1_utils directory sits alongside configs, prompts, scripts, examples, and assets. The utilities are the piece that came after the base model, and they are the reason the repository exists at all rather than pointing at a Hugging Face collection, since the model weights and training data were released under Hugging Face on 2025-05-17. The justfile shows the package has its own test suite, run from inside the directory with pytest:

cd cosmos_reason1_utils && uv run pytest

with linting running first through pre-commit across all files. That is a small signal, but a real one: the utilities are treated as maintained code inside the repository, even where the top level project is not.

Post-training paths: SFT, RLHF, and a Llava variant

Customising the model is the part the project leans into hardest. The tutorials directory holds a video critic example, a full post-training example, a minimal Hugging Face example, and a minimal Llava example. The heavy lifting for SFT and RLHF lives in a separate repository, nvidia-cosmos/cosmos-rl, described as an async post-training framework specialised for Supervised Fine-Tuning and Reinforcement Learning with Human Feedback, with priorities on performance, scalability, and fault tolerance. The README gives clear guidance on which example to start from: to support a custom dataset format, use the minimal Hugging Face example as a template. A benchmark example is also provided. There is a post-training quantization path as well, with the required versions spelled out as vllm 0.9.2, transformers 4.53.1 or newer, qwen-vl-utils with decord, and llmcompressor 0.6.0 or newer, and a script that performs it:

./scripts/quantize_fp8.py --model_id 'nvidia/Cosmos-Reason1-7B' --save_dir 'Cosmos-Reason1-7B-W8A8-FP8'

The Llava example matters because it shows the post-training path is not tied to a single training harness.

Maintenance status: the repository points new work at Cosmos 3

This is the part to read before you plan around the project. A banner at the top of the README announces that Cosmos 3 has arrived, describing it as NVIDIA's next-generation foundation model platform for Physical AI, with stronger physical reasoning capabilities than Cosmos-Reason1 and support for world prediction, simulation, transfer, and action generation in a single unified model. The README states plainly that the Cosmos-Reason1 repository is no longer under active development and will receive only limited maintenance updates, and that future model releases, features, documentation, and community support will be focused on Cosmos 3. It encourages users to migrate. The last push was on 2026-06-07, and the two tagged releases are announcements rather than model builds, one for Cosmos at CES 2026 covering Reason 2 and more on 2026-01-06 and one for Cosmos-Reason2 on 2025-12-20. So this repository is a well documented snapshot, not a growing platform. Licensing is Apache 2, with the pyproject.toml carrying the SPDX header for it, and the README notes that the project downloads and installs additional third-party open source projects whose licence terms you should review separately.

Editorial conclusion

cosmos-reason1 fits research and evaluation work on physical reasoning for robotics and vision agents, particularly for teams that want the weights, the inference examples, and the post-training scripts in one place rather than a hosted API. It is not a good base for a product you intend to keep extending, because the repository states it is no longer under active development and will receive only limited maintenance updates, with future work focused on Cosmos 3. Before adopting it, verify that one GPU with 24GB of memory matches your hardware, check the transformers version requirement of 4.51.3 or newer against your environment, and read the Cosmos 3 announcement to decide whether to migrate instead of starting here.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. nvidia-cosmos/cosmos-reason1 on GitHub
3. Project website
4. README
5. Releases