# TOPReward

TOPReward é um **modelo de recompensa zero-shot** que extrai as log-probabilidades dos tokens de um modelo de linguagem visual (VLM) pronto para uso como sinal de recompensa robótica. Dada uma trajetória em vídeo e uma instrução de tarefa, ele retorna a verossimilhança logarítmica do VLM de que a instrução é verdadeira — sem necessidade de ajuste fino.

**Artigo**: [TOPReward: Token Probabilities as Hidden Zero-Shot Rewards for Robotics](https://arxiv.org/abs/2602.19313) **Projeto**: [topreward.github.io](https://topreward.github.io/webpage/) **Código original**: [github.com/TOPReward/TOPReward](https://github.com/TOPReward/TOPReward) **Backbone padrão**: [Qwen/Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)

## Visão geral

TOPReward pergunta a um VLM genérico qual é a probabilidade de uma instrução de tarefa, **condicionada ao vídeo** de um robô tentando completar essa tarefa. Concretamente, dado:

- Um vídeo de trajetória (uma sequência de quadros).
- Uma instrução de tarefa (por exemplo, _"abra a gaveta"_).

ele constrói um prompt de chat do formato

```text
<video>
"The above video shows a robot manipulation trajectory that completes the
 following task: <instruction> Decide whether the above statement is True
 or not. The answer is: True"
```

encaminha-o pelo VLM, aplica label-masks em tudo exceto no último token e lê de volta a log-probabilidade desse token — por padrão, o literal `"True"` que fecha o template do sufixo. O resultado, `log P("True" | video + prompt + instruction)`, é a recompensa.

Como o método depende apenas de um VLM congelado, o TOPReward é **zero-shot**: não há pesos ajustados para hospedar. O "modelo" no LeRobot é um pequeno wrapper em torno do `Qwen3VLForConditionalGeneration` do `transformers`, além da lógica de mascaramento de rótulos. O processor é responsável pelo tokenizador e constrói o prompt de chat completo (padrão EO-1/Robometer).

## O que a integração do LeRobot abrange

- Configuração padrão `reward_model.type=topreward` por meio do LeRobot.
- Carregamento de VLMs por meio da API `Qwen3VLForConditionalGeneration` do `transformers`.
- Montagem do prompt + tokenização no processador (correspondente ao `QwenClient.compute_instruction_reward` upstream).
- `compute_reward()` retorna um log-prob escalar por amostra.
- Salvamento/carregamento do modelo de recompensa do LeRobot — `save_pretrained` grava apenas `config.json` (o VLM é identificado por `vlm_name`).
- Um script de rotulagem offline que grava um `topreward_progress.parquet` (esquema compatível com SARM) para RA-BC e overlay.

A portação atual do LeRobot suporta apenas o **cliente Qwen3-VL**. Outros clientes upstream (Gemini, OpenAI, Gemma, Molmo) podem ser adicionados como extras subsequentes.

## Requisitos de instalação

1. Instale o LeRobot seguindo o [Guia de Instalação](./installation).
2. Instale o extra opcional TOPReward:

```bash
pip install -e ".[topreward]"
```

ou, com `uv` a partir de um checkout de fonte:

```bash
uv sync --extra topreward
```

Isso importa o `transformers`. Na primeira vez que você executar o TOPReward, o Hugging Face também baixará os pesos do VLM do Hub (~16 GB para Qwen3-VL-8B-Instruct). É fortemente recomendável o uso de uma GPU.

## Entradas e Saídas do Modelo

O TOPReward espera:

- Um vídeo de trajetória ou uma sequência de quadros.
- Uma descrição da tarefa em linguagem natural.

Nos conjuntos de dados do LeRobot, o pré-processador lê:

| Campo de configuração              | Padrão                     | Significado                                       |
| ------------------------- | --------------------------- | --------------------------------------------- |
| `reward_model.image_key`  | `observation.images.top`    | Observação da câmera usada pelo TOPReward          |
| `reward_model.task_key`   | `task`                      | Digite dados complementares para a string da tarefa |
| `reward_model.max_frames` | `16`                        | Limite de quadros por amostra                      |
| `reward_model.fps`        | `2.0`                       | Metadados passados ao processador de vídeo Qwen   |
| `reward_model.vlm_name`   | `Qwen/Qwen3-VL-8B-Instruct` | ID do Hugging Face Hub do VLM subjacente     |

O modelo retorna:

- `compute_reward(batch)`: uma log-probabilidade por amostra. Valores maiores indicam melhor alinhamento entre a tarefa e o vídeo. Quando `success_threshold` é finito, retorna o valor binário limiarizado em vez disso.

## Uso

### Carregue o modelo de recompensa diretamente

```python
from lerobot.rewards.topreward import TOPRewardConfig, TOPRewardModel

cfg = TOPRewardConfig(
    vlm_name="Qwen/Qwen3-VL-8B-Instruct",
    device="cuda",
)
reward_model = TOPRewardModel(cfg)
```

### Use a fábrica de recompensas

```python
from lerobot.rewards import make_reward_model, make_reward_model_config, make_reward_pre_post_processors

cfg = make_reward_model_config(
    "topreward",
    vlm_name="Qwen/Qwen3-VL-8B-Instruct",
    device="cuda",
    image_key="observation.images.top",
)
reward_model = make_reward_model(cfg)
preprocessor, postprocessor = make_reward_pre_post_processors(cfg)
```

O pré-processador tokeniza o prompt completo (vídeo + prefixo + sufixo de instrução) e grava os tensores do Qwen-VL + `prompt_length` sob `observation.topreward.*`. O modelo lê esses tensores, aplica a máscara de rótulos com base em `prompt_length` e extrai a recompensa de log-prob.

### Rótulos de dados offline

Escreva um `topreward_progress.parquet` para o treinamento RA-BC e vídeos de sobreposição:

```bash
# Sparse-dense (15 anchors per episode, matches upstream)
uv run python -m lerobot.rewards.topreward.compute_rabc_weights \
    --dataset-repo-id lerobot/libero_10_image \
    --num-samples 15 \
    --device cuda
```

Em seguida, renderize a sobreposição de progresso para qualquer episódio:

```bash
uv run examples/dataset/create_progress_videos.py \
    --repo-id lerobot/libero_10_image \
    --episode 0 \
    --progress-file topreward_progress.parquet \
    --gif
```

## Notas de configuração

### Ajustes de prompt

O prompt padrão espelha o artigo original:

```text
prompt_prefix = "The above video shows a robot manipulation trajectory that completes the following task: "
prompt_suffix_template = "{instruction} Decide whether the above statement is True or not. The answer is: True"
```

Ambos são expostos em `TOPRewardConfig` para ablação. O modelo de sufixo **deve** conter `{instruction}`.

### Modelo de chat

`add_chat_template=True` envolve o prompt completo (incluindo a instrução) com o modelo de chat do tokenizer antes da tokenização. O padrão é `False`, em conformidade com os experimentos principais do artigo original.

## Limitações

- A portação atual do LeRobot é **apenas para inferência e zero-shot**; `forward()` não é sobrescrito e `is_trainable` retorna `False`.
- Apenas a **família Qwen3-VL** é suportada; outros clientes upstream estão fora do escopo.
- TOPReward herda os vieses do VLM subjacente.

## Referências

- [página do projeto TOPReward](https://topreward.github.io/webpage/)
- [paper TOPReward](https://arxiv.org/abs/2602.19313)
- [Código original do TOPReward](https://github.com/TOPReward/TOPReward)
- [Qwen3-VL-8B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)

## Citação

```bibtex
@article{chen2026topreward,
  title={TOPReward: Token Probabilities as Hidden Zero-Shot Rewards for Robotics},
  author={Chen, Shirui and Harrison, Cole and Lee, Ying-Chun and Yang, Angela Jin and
          Ren, Zhongzheng and Ratliff, Lillian J and Duan, Jiafei and Fox, Dieter and
          Krishna, Ranjay},
  journal={arXiv preprint arXiv:2602.19313},
  year={2026}
}
```

## Licença

A base de código original do TOPReward é licenciada sob a licença MIT. A portação para o LeRobot segue a licença Apache 2.0 do LeRobot; os pesos do Qwen3-VL encapsulados estão sujeitos à licença original do Qwen.

