# cosmos_battery

This directory is the staging area for the inference-only package of the Piper14 Cosmos3 battery policy run.

- run: `battery_piper14_cosmos3_nano_20000step_4gpu_b8_acc1_offline`
- source checkpoint format: DCP directory checkpoints
- exported model directories: `12k/`, `16k/`, `18k/`, `20k/`

Use this folder as the package root when preparing an export for handoff or upload. It keeps the inference-facing model directories and the provenance copies that explain where they came from in one place.

## What belongs in the inference-only package

Required:

- exactly one or more exported model directories produced by `cosmos_framework.scripts.export_model`
- `provenance/config.yaml`
- `provenance/job_env.yaml`
- `provenance/launch_info.yaml`
- this README plus `package_manifest.yaml`

## What does not belong here by default

Do not package these into the inference-only artifact unless a downstream environment explicitly requires them:

- raw DCP checkpoint directories under `reports/.../checkpoints/`
- full training dataset
- local Qwen snapshot cache
- local `Wan2.2_VAE.pth`

## Why the source checkpoints are directories

This training run uses distributed Cosmos Framework checkpointing. Each training checkpoint is a directory with sharded state, not a single `.pt` file. The intended inference flow is to export those DCP checkpoints into inference-only model directories and ship the exported directories instead of the raw training checkpoints.

## Package layout

```text
cosmos_battery/
  README.md
  package_manifest.yaml
  provenance/
    README.md
    config.yaml
    job_env.yaml
    launch_info.yaml
  12k/
  16k/
  18k/
  20k/
```

Notes:

- `12k/`, `16k/`, `18k/`, and `20k/` are complete exported inference checkpoints.
- Each of those directories should contain `config.json`, `checkpoint.json`, `model.safetensors.index.json`, and seven `model-*.safetensors` shards.

## Runtime expectation outside this package

The downstream inference side still needs the local Piper14 registration code from this repository:

- `piper_cosmos/cosmos3/domain.py`
- `piper_cosmos/cosmos3/action_policy_piper14_nano.py`

Those files are runtime code dependencies, not part of this `cosmos_battery/` packaging bundle.

## How to use this folder

1. Verify the chosen checkpoint directory contains exporter-produced inference artifacts.
2. Keep the copied provenance files under `provenance/` with the exported model directory.