dita_droid_pretrain / scripts /convert_dita_checkpoints.py

albus2024

Update Dita training configuration and bundled runtime to 2.1.0

1277b9e verified about 1 month ago

22.8 kB

#!/usr/bin/env python3
"""Convert Dita checkpoints into LeRobot policies or DROID fine-tuning initializations."""

from __future__ import annotations

import argparse
import gc
import hashlib
import json
import shutil
import subprocess
import sys
from dataclasses import dataclass, replace
from datetime import datetime, timezone
from pathlib import Path
from typing import Any

REPO_ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(REPO_ROOT / "src"))

import torch
from huggingface_hub import HfApi
from huggingface_hub.errors import HfHubHTTPError
from lerobot.configs.types import FeatureType, NormalizationMode, PolicyFeature
from lerobot.utils.constants import ACTION

from lerobot_policy_dita import DitaConfig, DitaPolicy, make_dita_pre_post_processors
from lerobot_policy_dita.policy.processor_dita import validate_dita_action_stats
DEFAULT_STATS_ROOT = Path(
    "/home/shared/lyanam/huggingface/hub/"
    "datasets--openvla--modified_libero_rlds/snapshots/"
    "6ce6aaaaabdbe590b1eef5cd29c0d33f14a08551"
)


@dataclass(frozen=True)
class ConversionSpec:
    checkpoint: str
    output_name: str
    repo_id: str
    suite: str
    stats_glob: str | None


SPECS: dict[str, ConversionSpec] = {
    "spatial": ConversionSpec(
        "model_ckpt/libero_spatial.pth",
        "dita_spatial",
        "albus2024/dita_spatial",
        "libero_spatial_no_noops",
        "libero_spatial_no_noops/1.0.0/dataset_statistics_*.json",
    ),
    "object": ConversionSpec(
        "model_ckpt/libero_object.pth",
        "dita_object",
        "albus2024/dita_object",
        "libero_object_no_noops",
        "libero_object_no_noops/1.0.0/dataset_statistics_*.json",
    ),
    "goal": ConversionSpec(
        "model_ckpt/libero_goal.pth",
        "dita_goal",
        "albus2024/dita_goal",
        "libero_goal_no_noops",
        "libero_goal_no_noops/1.0.0/dataset_statistics_*.json",
    ),
    "long": ConversionSpec(
        "model_ckpt/libero_long.pth",
        "dita_long",
        "albus2024/dita_long",
        "libero_10_no_noops",
        "libero_10_no_noops/1.0.0/dataset_statistics_*.json",
    ),
    "droid_pretrain": ConversionSpec(
        "model_ckpt/dita_droid_pretrain.pth",
        "dita_droid_pretrain",
        "albus2024/dita_droid_pretrain",
        "droid_pretrain",
        None,
    ),
}


def sha256_file(path: Path) -> str:
    digest = hashlib.sha256()
    with path.open("rb") as stream:
        for chunk in iter(lambda: stream.read(16 * 1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def git_revision() -> str:
    return subprocess.check_output(
        ["git", "rev-parse", "HEAD"], cwd=REPO_ROOT, text=True
    ).strip()


def find_stats_file(stats_root: Path, spec: ConversionSpec) -> Path:
    if spec.stats_glob is None:
        raise RuntimeError(
            "DROID has no bundled action statistics. Convert it as a fine-tuning "
            "initialization and bind target-dataset statistics during training."
        )
    matches = sorted(stats_root.glob(spec.stats_glob))
    if len(matches) != 1:
        raise FileNotFoundError(
            f"Expected exactly one statistics file matching {stats_root / spec.stats_glob}, "
            f"found {len(matches)}."
        )
    return matches[0]


def load_dataset_stats(path: Path) -> tuple[dict[str, dict[str, torch.Tensor]], dict[str, Any]]:
    with path.open() as stream:
        raw = json.load(stream)
    action_stats = raw.get(ACTION)
    if not isinstance(action_stats, dict):
        raise ValueError(f"Statistics file {path} has no {ACTION!r} mapping.")
    for required in ("q01", "q99"):
        values = action_stats.get(required)
        if not isinstance(values, list) or len(values) != 7:
            raise ValueError(f"{path}: action.{required} must contain exactly seven values.")
    validate_dita_action_stats({ACTION: action_stats})
    tensor_stats = {
        ACTION: {
            name: torch.as_tensor(values, dtype=torch.float32)
            for name, values in action_stats.items()
            if isinstance(values, list) and len(values) == 7
        }
    }
    return tensor_stats, raw


def make_dita_config(spec: ConversionSpec, device: str) -> DitaConfig:
    return DitaConfig(
        dataset_suite=None if spec.suite == "droid_pretrain" else spec.suite,
        input_features={
            "observation.images.image": PolicyFeature(
                type=FeatureType.VISUAL,
                shape=(3, 256, 256),
            )
        },
        output_features={ACTION: PolicyFeature(type=FeatureType.ACTION, shape=(7,))},
        device=device,
        num_layers=12,
        traj_length=11,
        dropout_rate=0.0,
        freeze_backbone=False,
        optimizer_lr=5e-4 if spec.suite == "libero_10_no_noops" else 1e-4,
        use_qformer=True,
        prediction_type="epsilon",
        attn_implementation="eager",
        num_inference_steps=10,
        dtype="float16",
        tokenizer_max_length=77,
        image_resolution=(224, 224),
        chunk_size=10,
        n_action_steps=1,
        history_frames=2,
        gripper_threshold=0.5,
        gripper_mode="continuous" if spec.suite == "droid_pretrain" else "binary",
        normalization_mapping={
            "VISUAL": NormalizationMode.IDENTITY,
            "ACTION": NormalizationMode.QUANTILES,
            "LANGUAGE": NormalizationMode.IDENTITY,
        },
        push_to_hub=False,
    )


def extract_parameter_state(checkpoint_path: Path) -> dict[str, torch.Tensor]:
    checkpoint = torch.load(checkpoint_path, map_location="cpu", weights_only=False)
    if not isinstance(checkpoint, dict):
        raise TypeError(f"{checkpoint_path}: expected a checkpoint dictionary.")
    state = checkpoint.get("parameter", checkpoint)
    if not isinstance(state, dict) or not state or not all(
        isinstance(k, str) and isinstance(v, torch.Tensor) for k, v in state.items()
    ):
        raise TypeError(
            f"{checkpoint_path}: expected a tensor state dict or checkpoint['parameter']."
        )
    return state


def align_and_validate_state(
    state: dict[str, torch.Tensor], expected: dict[str, torch.Tensor]
) -> tuple[dict[str, torch.Tensor], str | None]:
    prefix: str | None = None
    if set(state) == set(expected):
        aligned = state
    elif state and all(key.startswith("module.") for key in state):
        stripped = {key.removeprefix("module."): value for key, value in state.items()}
        aligned = stripped
        if set(stripped) == set(expected):
            prefix = "module."
    else:
        aligned = state

    missing = sorted(set(expected) - set(aligned))
    unexpected = sorted(set(aligned) - set(expected))
    shape_mismatches = sorted(
        (key, tuple(aligned[key].shape), tuple(expected[key].shape))
        for key in set(aligned) & set(expected)
        if aligned[key].shape != expected[key].shape
    )
    if missing or unexpected or shape_mismatches:
        raise RuntimeError(
            "Checkpoint incompatibility:\n"
            f"missing keys ({len(missing)}): {missing}\n"
            f"unexpected keys ({len(unexpected)}): {unexpected}\n"
            f"shape mismatches ({len(shape_mismatches)}): {shape_mismatches}"
        )
    return aligned, prefix


def model_card(
    spec: ConversionSpec,
    checkpoint_path: Path,
    checkpoint_sha: str,
    stats_path: Path,
    stats_sha: str,
    stats_raw: dict[str, Any],
    code_sha: str,
    runtime_wheel_name: str | None = None,
) -> str:
    q01 = stats_raw[ACTION]["q01"]
    q99 = stats_raw[ACTION]["q99"]
    install = (
        f'pip install "lerobot_policy_dita[libero] @ https://huggingface.co/{spec.repo_id}/resolve/main/{runtime_wheel_name}"'
        if runtime_wheel_name
        else f'pip install "git+https://github.com/A-Dumbledore/lerobot_policy_dita.git@{code_sha}"'
    )
    return f"""---
library_name: lerobot
pipeline_tag: robotics
tags:
- lerobot
- dita
- libero
---
# Dita — {spec.suite}
This repository is a strict LeRobot conversion of `{checkpoint_path.name}` from the original
[Dita](https://github.com/RoboDita/Dita) implementation. It is configured for the
`{spec.suite}` action distribution and is not interchangeable with another LIBERO suite.
## Provenance and compatibility contract
- Source checkpoint: `{checkpoint_path.as_posix()}`
- Source checkpoint SHA256: `{checkpoint_sha}`
- Conversion code commit: `{code_sha}`
- Dataset statistics: `{stats_path.as_posix()}`
- Dataset statistics SHA256: `{stats_sha}`
- Image processing: one RGB primary/agentview camera, resized to 224×224, followed once by
  ImageNet mean `(0.485, 0.456, 0.406)` and std `(0.229, 0.224, 0.225)`.
- Action processing: dimensions 0–5 use this suite's `q01`/`q99`; dimension 6 is not normalized.
- Action mask: `[true, true, true, true, true, true, false]`.
- q01: `{json.dumps(q01)}`
- q99: `{json.dumps(q99)}`
- Gripper: normalized output is thresholded with `> 0.5`, then the Cartesian dimensions are
  unnormalized, then the original Dita gripper sign flip is applied.
- Rollout: `traj_length=11`, two-frame history, `chunk_size=10`, `n_action_steps=1`,
  `num_inference_steps=10`, DDIM `prediction_type=epsilon`, and CUDA AMP by default.
- `policy.dtype` controls compute precision (`float32`, `float16`, `bfloat16`);
  parameters remain FP32. It is the sole precision setting; `use_amp` is derived internally.
- LIBERO's LeRobot environment processor performs the 180° image rotation. The policy does not
  rotate the image a second time.
## Install
```bash
{install}
```
## Evaluate
```bash
lerobot-eval \\
  --policy.path={spec.repo_id} \\
  --policy.gripper_mode=binary \\
  --policy.device=cuda \\
  --env.type=libero \\
  --env.task={spec.suite.removesuffix('_no_noops')} \\
  --env.max_parallel_tasks=1 \\
  --eval.batch_size=1 \\
  --eval.n_episodes=10 \\
  --output_dir=./outputs/{spec.output_name}
```
The processor state in this repository contains the required statistics; no source `.pth` file or
local dataset metadata is needed at evaluation time.
## Validation
The converter checks all parameter names and shapes, loads with `strict=True`, and checks the
saved artifact files. Run the project's parity and converted-checkpoint verification scripts
separately before using the policy; conversion alone does not establish rollout parity.
"""


def pretraining_model_card(
    spec: ConversionSpec, checkpoint_sha: str, code_sha: str, runtime_wheel_name: str | None
) -> str:
    install = (
        f'pip install "lerobot_policy_dita[training] @ https://huggingface.co/{spec.repo_id}/resolve/main/{runtime_wheel_name}"'
        if runtime_wheel_name
        else 'pip install -e ".[training]"  # From the updated lerobot_policy_dita checkout'
    )
    return f"""---
library_name: lerobot
pipeline_tag: robotics
tags:
- lerobot
- dita
- droid
- pretraining
---
# Dita DROID pretraining initialization
This repository converts the original Dita DROID weights for subsequent fine-tuning.
It contains model weights, a LeRobot Dita configuration, and processor templates without
dataset action statistics. It is not a ready-to-deploy DROID or LIBERO policy.
## Provenance
- Source: `{spec.checkpoint}` from the original [Dita](https://github.com/RoboDita/Dita) release.
- Source checkpoint SHA256: `{checkpoint_sha}`.
- Conversion base Git commit: `{code_sha}`. See `conversion_metadata.json` for the
  working-tree status, conversion-script hash, and packaged runtime hash when present.
- All model parameter keys and shapes are checked, followed by `strict=True` loading.
- Optimizer/scheduler state is not exported. No source DROID action statistics are inferred.
## Install
Use Python 3.12. The updated Dita runtime translates LeRobot's standard fine-tuning
normalizer overrides to Dita's custom processors.
```bash
{install}
```
## Fine-tune
Use a LeRobot dataset with seven-dimensional actions, a compatible primary RGB camera,
and task language. Its action metadata must contain seven-element `q01` and `q99` arrays
computed in the target training action convention. The default `gripper_mode=continuous`
uses quantiles for the first six dimensions and dataset `action.min/max` for the gripper.
Continuous outputs are restored to the recorded position units without thresholding or
sign inversion. Use `--policy.gripper_mode=binary` for LIBERO signed training targets
(-1=open, +1=closed), encoded internally as 1=open, 0=closed.
ImageNet image normalization and CLIP text encoding remain fixed.
```bash
lerobot-train \\
  --policy.path={spec.repo_id} \\
  --policy.gripper_mode=continuous \\
  --policy.device=cuda \\
  --policy.dtype=bfloat16 \\
  --policy.input_features=null \\
  --policy.push_to_hub=false \\
  --dataset.repo_id=YOUR_USERNAME/YOUR_DATASET \\
  --output_dir=outputs/train/dita_droid_finetune
```
`policy.dtype` accepts `float32`, `float16` and `bfloat16` and controls autocast;
weights and optimizer state remain FP32. Use BF16 on a supported GPU, or select
FP32/FP16 explicitly. The default CUDA precision remains FP16 for compatibility.
At the start of a new fine-tuning run, LeRobot binds the target dataset's statistics to
both processor templates. They remain fixed during that run and are saved with the
fine-tuned checkpoint. LeRobot 0.6.1 restores saved statistics on resume. The same
pretraining repository can initialize multiple target datasets; no per-dataset pretraining
upload is needed. Missing quantiles cause an explicit error when processing actions.
The processor templates require cached or downloadable DINOv2/CLIP assets. Load the
fine-tuned checkpoint together with its saved processors for evaluation and deployment.
Any `validation_report.json` documents the checks actually run for this upload; no
task success rate or DROID deployment equivalence is claimed.
"""


def previous_revision(api: HfApi, repo_id: str) -> str | None:
    try:
        return api.model_info(repo_id).sha
    except HfHubHTTPError as error:
        if error.response is not None and error.response.status_code == 404:
            return None
        raise


def convert_one(
    spec: ConversionSpec,
    *,
    output_root: Path,
    stats_root: Path,
    device: str,
    push_to_hub: bool,
    repo_id_override: str | None,
    runtime_wheel: Path | None = None,
) -> dict[str, Any]:
    if repo_id_override:
        spec = replace(spec, repo_id=repo_id_override)
    pretraining_only = spec.suite == "droid_pretrain"
    if runtime_wheel is not None and (not runtime_wheel.is_file() or runtime_wheel.suffix != ".whl"):
        raise ValueError(f"Expected an existing runtime wheel: {runtime_wheel}")
    checkpoint_path = REPO_ROOT / spec.checkpoint
    if not checkpoint_path.is_file():
        raise FileNotFoundError(checkpoint_path)
    stats_path = None if pretraining_only else find_stats_file(stats_root, spec)
    output_dir = output_root / spec.output_name
    if output_dir.exists() and any(output_dir.iterdir()):
        raise FileExistsError(
            f"Refusing to mix artifacts in non-empty {output_dir}; use a fresh output root."
        )
    output_dir.mkdir(parents=True, exist_ok=True)

    checkpoint_sha = sha256_file(checkpoint_path)
    stats_sha = sha256_file(stats_path) if stats_path else None
    dataset_stats, stats_raw = load_dataset_stats(stats_path) if stats_path else (None, None)
    code_sha = git_revision()

    config = make_dita_config(spec, device)
    policy = DitaPolicy(config)
    expected = policy.model.state_dict()
    state = extract_parameter_state(checkpoint_path)
    aligned, stripped_prefix = align_and_validate_state(state, expected)
    load_result = policy.model.load_state_dict(aligned, strict=True)
    if load_result.missing_keys or load_result.unexpected_keys:
        raise RuntimeError(f"Strict load unexpectedly returned {load_result}.")

    policy.save_pretrained(output_dir)
    preprocessor, postprocessor = make_dita_pre_post_processors(config, dataset_stats)
    preprocessor.save_pretrained(output_dir)
    postprocessor.save_pretrained(output_dir)

    metadata: dict[str, Any] = {
        "converted_at_utc": datetime.now(timezone.utc).isoformat(),
        "source_model": "Dita/scripts/llama_dp.py",
        "source_checkpoint": spec.checkpoint,
        "source_checkpoint_sha256": checkpoint_sha,
        "checkpoint_parameter_tensors": len(aligned),
        "stripped_prefix": stripped_prefix,
        "strict_load": {
            "missing_keys": [],
            "unexpected_keys": [],
            "shape_mismatches": [],
        },
        "dataset_suite": spec.suite,
        "artifact_purpose": "finetuning_initialization" if pretraining_only else "deployment_policy",
        "statistics_binding": "target_dataset_at_finetuning" if pretraining_only else "bundled",
        "dataset_statistics_file": str(stats_path) if stats_path else None,
        "dataset_statistics_sha256": stats_sha,
        "action_q01": stats_raw[ACTION]["q01"] if stats_raw else None,
        "action_q99": stats_raw[ACTION]["q99"] if stats_raw else None,
        "gripper_mode": config.gripper_mode,
        "action_normalization_mask": list(config.action_normalization_mask),
        "conversion_code_git_sha": code_sha,
        "conversion_code_git_dirty": bool(subprocess.check_output(
            ["git", "status", "--porcelain"], cwd=REPO_ROOT, text=True
        ).strip()),
        "conversion_script_sha256": sha256_file(Path(__file__)),
        "target_repo_id": repo_id_override or spec.repo_id,
    }
    (output_dir / "conversion_metadata.json").write_text(
        json.dumps(metadata, indent=2) + "\n"
    )
    (output_dir / "README.md").write_text(
        pretraining_model_card(spec, checkpoint_sha, code_sha, runtime_wheel.name if runtime_wheel else None)
        if pretraining_only else model_card(
            spec,
            checkpoint_path,
            checkpoint_sha,
            stats_path,
            stats_sha,
            stats_raw,
            code_sha,
            runtime_wheel.name if runtime_wheel else None,
        )
    )

    required = {
        "config.json",
        "model.safetensors",
        "policy_preprocessor.json",
        "policy_postprocessor.json",
        "README.md",
        "conversion_metadata.json",
    }
    missing_artifacts = sorted(required - {path.name for path in output_dir.iterdir()})
    if missing_artifacts:
        raise RuntimeError(f"Conversion did not produce required files: {missing_artifacts}")
    state_files = sorted(path.name for path in output_dir.glob("*.safetensors") if path.name != "model.safetensors")
    if not state_files and not pretraining_only:
        raise RuntimeError("Processor state safetensors were not saved.")
    metadata["processor_state_files"] = state_files
    if runtime_wheel is not None:
        shutil.copy2(runtime_wheel, output_dir / runtime_wheel.name)
        metadata["runtime_wheel"] = runtime_wheel.name
        metadata["runtime_wheel_sha256"] = sha256_file(runtime_wheel)
    (output_dir / "conversion_metadata.json").write_text(
        json.dumps(metadata, indent=2) + "\n"
    )

    if push_to_hub:
        api = HfApi()
        account = api.whoami()["name"]
        target_repo = repo_id_override or spec.repo_id
        if target_repo.split("/", 1)[0] != account:
            raise PermissionError(f"Authenticated as {account}, cannot publish {target_repo}.")
        old_sha = previous_revision(api, target_repo)
        metadata["previous_hub_revision"] = old_sha
        (output_dir / "conversion_metadata.json").write_text(
            json.dumps(metadata, indent=2) + "\n"
        )
        api.create_repo(target_repo, repo_type="model", exist_ok=True)
        commit = api.upload_folder(
            repo_id=target_repo,
            repo_type="model",
            folder_path=output_dir,
            commit_message=f"Synchronize Dita {spec.suite} LeRobot checkpoint",
        )
        metadata["hub_commit_sha"] = commit.oid
        print(f"Uploaded {target_repo} at {commit.oid} (previous: {old_sha})")

    print(
        f"Converted {checkpoint_path.name}: {len(aligned)} tensors, strict=True, "
        f"SHA256={checkpoint_sha}, output={output_dir}"
    )
    del preprocessor, postprocessor, policy, aligned, state, expected
    gc.collect()
    if torch.cuda.is_available():
        torch.cuda.empty_cache()
    return metadata


def parse_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description=__doc__)
    selection = parser.add_mutually_exclusive_group(required=True)
    selection.add_argument(
        "--checkpoint",
        help="spatial/object/goal/long/droid_pretrain, or a known checkpoint filename/path.",
    )
    selection.add_argument("--all", action="store_true", help="Convert all four deployable LIBERO checkpoints.")
    parser.add_argument("--output-dir", type=Path, default=REPO_ROOT / "converted_checkpoints")
    parser.add_argument("--stats-root", type=Path, default=DEFAULT_STATS_ROOT)
    parser.add_argument("--device", default="cuda")
    parser.add_argument("--push-to-hub", action="store_true")
    parser.add_argument("--repo-id", help="Override the target repo for a single checkpoint only.")
    parser.add_argument("--runtime-wheel", type=Path, help="Bundle an updated Dita runtime wheel with the model.")
    return parser.parse_args()


def main() -> None:
    args = parse_args()
    if args.repo_id and args.all:
        raise ValueError("--repo-id can only be used with --checkpoint.")
    selected = [SPECS[name] for name in ("spatial", "object", "goal", "long")]
    if not args.all:
        if args.checkpoint in SPECS:
            selected = [SPECS[args.checkpoint]]
        else:
            checkpoint_path = Path(args.checkpoint).expanduser().resolve()
            matches = [
                spec
                for spec in SPECS.values()
                if Path(spec.checkpoint).name == checkpoint_path.name
                or (spec.suite == "droid_pretrain" and checkpoint_path.name == "droid_pretrain.pth")
            ]
            if len(matches) != 1:
                raise ValueError(
                    f"Unknown checkpoint {args.checkpoint!r}; expected one of "
                    f"{sorted(SPECS)} or their checkpoint paths."
                )
            selected = [replace(matches[0], checkpoint=str(checkpoint_path))]
    for spec in selected:
        convert_one(
            spec,
            output_root=args.output_dir,
            stats_root=args.stats_root,
            device=args.device,
            push_to_hub=args.push_to_hub,
            repo_id_override=args.repo_id,
            runtime_wheel=args.runtime_wheel,
        )


if __name__ == "__main__":
    main()

	#!/usr/bin/env python3
	"""Convert Dita checkpoints into LeRobot policies or DROID fine-tuning initializations."""

	from __future__ import annotations

	import argparse
	import gc
	import hashlib
	import json
	import shutil
	import subprocess
	import sys
	from dataclasses import dataclass, replace
	from datetime import datetime, timezone
	from pathlib import Path
	from typing import Any

	REPO_ROOT = Path(__file__).resolve().parents[1]
	sys.path.insert(0, str(REPO_ROOT / "src"))

	import torch
	from huggingface_hub import HfApi
	from huggingface_hub.errors import HfHubHTTPError
	from lerobot.configs.types import FeatureType, NormalizationMode, PolicyFeature
	from lerobot.utils.constants import ACTION

	from lerobot_policy_dita import DitaConfig, DitaPolicy, make_dita_pre_post_processors
	from lerobot_policy_dita.policy.processor_dita import validate_dita_action_stats
	DEFAULT_STATS_ROOT = Path(
	"/home/shared/lyanam/huggingface/hub/"
	"datasets--openvla--modified_libero_rlds/snapshots/"
	"6ce6aaaaabdbe590b1eef5cd29c0d33f14a08551"
	)


	@dataclass(frozen=True)
	class ConversionSpec:
	checkpoint: str
	output_name: str
	repo_id: str
	suite: str
	stats_glob: str \| None


	SPECS: dict[str, ConversionSpec] = {
	"spatial": ConversionSpec(
	"model_ckpt/libero_spatial.pth",
	"dita_spatial",
	"albus2024/dita_spatial",
	"libero_spatial_no_noops",
	"libero_spatial_no_noops/1.0.0/dataset_statistics_*.json",
	),
	"object": ConversionSpec(
	"model_ckpt/libero_object.pth",
	"dita_object",
	"albus2024/dita_object",
	"libero_object_no_noops",
	"libero_object_no_noops/1.0.0/dataset_statistics_*.json",
	),
	"goal": ConversionSpec(
	"model_ckpt/libero_goal.pth",
	"dita_goal",
	"albus2024/dita_goal",
	"libero_goal_no_noops",
	"libero_goal_no_noops/1.0.0/dataset_statistics_*.json",
	),
	"long": ConversionSpec(
	"model_ckpt/libero_long.pth",
	"dita_long",
	"albus2024/dita_long",
	"libero_10_no_noops",
	"libero_10_no_noops/1.0.0/dataset_statistics_*.json",
	),
	"droid_pretrain": ConversionSpec(
	"model_ckpt/dita_droid_pretrain.pth",
	"dita_droid_pretrain",
	"albus2024/dita_droid_pretrain",
	"droid_pretrain",
	None,
	),
	}


	def sha256_file(path: Path) -> str:
	digest = hashlib.sha256()
	with path.open("rb") as stream:
	for chunk in iter(lambda: stream.read(16 * 1024 * 1024), b""):
	digest.update(chunk)
	return digest.hexdigest()


	def git_revision() -> str:
	return subprocess.check_output(
	["git", "rev-parse", "HEAD"], cwd=REPO_ROOT, text=True
	).strip()


	def find_stats_file(stats_root: Path, spec: ConversionSpec) -> Path:
	if spec.stats_glob is None:
	raise RuntimeError(
	"DROID has no bundled action statistics. Convert it as a fine-tuning "
	"initialization and bind target-dataset statistics during training."
	)
	matches = sorted(stats_root.glob(spec.stats_glob))
	if len(matches) != 1:
	raise FileNotFoundError(
	f"Expected exactly one statistics file matching {stats_root / spec.stats_glob}, "
	f"found {len(matches)}."
	)
	return matches[0]


	def load_dataset_stats(path: Path) -> tuple[dict[str, dict[str, torch.Tensor]], dict[str, Any]]:
	with path.open() as stream:
	raw = json.load(stream)
	action_stats = raw.get(ACTION)
	if not isinstance(action_stats, dict):
	raise ValueError(f"Statistics file {path} has no {ACTION!r} mapping.")
	for required in ("q01", "q99"):
	values = action_stats.get(required)
	if not isinstance(values, list) or len(values) != 7:
	raise ValueError(f"{path}: action.{required} must contain exactly seven values.")
	validate_dita_action_stats({ACTION: action_stats})
	tensor_stats = {
	ACTION: {
	name: torch.as_tensor(values, dtype=torch.float32)
	for name, values in action_stats.items()
	if isinstance(values, list) and len(values) == 7
	}
	}
	return tensor_stats, raw


	def make_dita_config(spec: ConversionSpec, device: str) -> DitaConfig:
	return DitaConfig(
	dataset_suite=None if spec.suite == "droid_pretrain" else spec.suite,
	input_features={
	"observation.images.image": PolicyFeature(
	type=FeatureType.VISUAL,
	shape=(3, 256, 256),
	)
	},
	output_features={ACTION: PolicyFeature(type=FeatureType.ACTION, shape=(7,))},
	device=device,
	num_layers=12,
	traj_length=11,
	dropout_rate=0.0,
	freeze_backbone=False,
	optimizer_lr=5e-4 if spec.suite == "libero_10_no_noops" else 1e-4,
	use_qformer=True,
	prediction_type="epsilon",
	attn_implementation="eager",
	num_inference_steps=10,
	dtype="float16",
	tokenizer_max_length=77,
	image_resolution=(224, 224),
	chunk_size=10,
	n_action_steps=1,
	history_frames=2,
	gripper_threshold=0.5,
	gripper_mode="continuous" if spec.suite == "droid_pretrain" else "binary",
	normalization_mapping={
	"VISUAL": NormalizationMode.IDENTITY,
	"ACTION": NormalizationMode.QUANTILES,
	"LANGUAGE": NormalizationMode.IDENTITY,
	},
	push_to_hub=False,
	)


	def extract_parameter_state(checkpoint_path: Path) -> dict[str, torch.Tensor]:
	checkpoint = torch.load(checkpoint_path, map_location="cpu", weights_only=False)
	if not isinstance(checkpoint, dict):
	raise TypeError(f"{checkpoint_path}: expected a checkpoint dictionary.")
	state = checkpoint.get("parameter", checkpoint)
	if not isinstance(state, dict) or not state or not all(
	isinstance(k, str) and isinstance(v, torch.Tensor) for k, v in state.items()
	):
	raise TypeError(
	f"{checkpoint_path}: expected a tensor state dict or checkpoint['parameter']."
	)
	return state


	def align_and_validate_state(
	state: dict[str, torch.Tensor], expected: dict[str, torch.Tensor]
	) -> tuple[dict[str, torch.Tensor], str \| None]:
	prefix: str \| None = None
	if set(state) == set(expected):
	aligned = state
	elif state and all(key.startswith("module.") for key in state):
	stripped = {key.removeprefix("module."): value for key, value in state.items()}
	aligned = stripped
	if set(stripped) == set(expected):
	prefix = "module."
	else:
	aligned = state

	missing = sorted(set(expected) - set(aligned))
	unexpected = sorted(set(aligned) - set(expected))
	shape_mismatches = sorted(
	(key, tuple(aligned[key].shape), tuple(expected[key].shape))
	for key in set(aligned) & set(expected)
	if aligned[key].shape != expected[key].shape
	)
	if missing or unexpected or shape_mismatches:
	raise RuntimeError(
	"Checkpoint incompatibility:\n"
	f"missing keys ({len(missing)}): {missing}\n"
	f"unexpected keys ({len(unexpected)}): {unexpected}\n"
	f"shape mismatches ({len(shape_mismatches)}): {shape_mismatches}"
	)
	return aligned, prefix


	def model_card(
	spec: ConversionSpec,
	checkpoint_path: Path,
	checkpoint_sha: str,
	stats_path: Path,
	stats_sha: str,
	stats_raw: dict[str, Any],
	code_sha: str,
	runtime_wheel_name: str \| None = None,
	) -> str:
	q01 = stats_raw[ACTION]["q01"]
	q99 = stats_raw[ACTION]["q99"]
	install = (
	f'pip install "lerobot_policy_dita[libero] @ https://huggingface.co/{spec.repo_id}/resolve/main/{runtime_wheel_name}"'
	if runtime_wheel_name
	else f'pip install "git+https://github.com/A-Dumbledore/lerobot_policy_dita.git@{code_sha}"'
	)
	return f"""---
	library_name: lerobot
	pipeline_tag: robotics
	tags:
	- lerobot
	- dita
	- libero
	---

	# Dita — {spec.suite}

	This repository is a strict LeRobot conversion of `{checkpoint_path.name}` from the original
	[Dita](https://github.com/RoboDita/Dita) implementation. It is configured for the
	`{spec.suite}` action distribution and is not interchangeable with another LIBERO suite.

	## Provenance and compatibility contract

	- Source checkpoint: `{checkpoint_path.as_posix()}`
	- Source checkpoint SHA256: `{checkpoint_sha}`
	- Conversion code commit: `{code_sha}`
	- Dataset statistics: `{stats_path.as_posix()}`
	- Dataset statistics SHA256: `{stats_sha}`
	- Image processing: one RGB primary/agentview camera, resized to 224×224, followed once by
	ImageNet mean `(0.485, 0.456, 0.406)` and std `(0.229, 0.224, 0.225)`.
	- Action processing: dimensions 0–5 use this suite's `q01`/`q99`; dimension 6 is not normalized.
	- Action mask: `[true, true, true, true, true, true, false]`.
	- q01: `{json.dumps(q01)}`
	- q99: `{json.dumps(q99)}`
	- Gripper: normalized output is thresholded with `> 0.5`, then the Cartesian dimensions are
	unnormalized, then the original Dita gripper sign flip is applied.
	- Rollout: `traj_length=11`, two-frame history, `chunk_size=10`, `n_action_steps=1`,
	`num_inference_steps=10`, DDIM `prediction_type=epsilon`, and CUDA AMP by default.
	- `policy.dtype` controls compute precision (`float32`, `float16`, `bfloat16`);
	parameters remain FP32. It is the sole precision setting; `use_amp` is derived internally.
	- LIBERO's LeRobot environment processor performs the 180° image rotation. The policy does not
	rotate the image a second time.

	## Install

	```bash
	{install}
	```

	## Evaluate

	```bash
	lerobot-eval \\
	--policy.path={spec.repo_id} \\
	--policy.gripper_mode=binary \\
	--policy.device=cuda \\
	--env.type=libero \\
	--env.task={spec.suite.removesuffix('_no_noops')} \\
	--env.max_parallel_tasks=1 \\
	--eval.batch_size=1 \\
	--eval.n_episodes=10 \\
	--output_dir=./outputs/{spec.output_name}
	```

	The processor state in this repository contains the required statistics; no source `.pth` file or
	local dataset metadata is needed at evaluation time.

	## Validation

	The converter checks all parameter names and shapes, loads with `strict=True`, and checks the
	saved artifact files. Run the project's parity and converted-checkpoint verification scripts
	separately before using the policy; conversion alone does not establish rollout parity.
	"""


	def pretraining_model_card(
	spec: ConversionSpec, checkpoint_sha: str, code_sha: str, runtime_wheel_name: str \| None
	) -> str:
	install = (
	f'pip install "lerobot_policy_dita[training] @ https://huggingface.co/{spec.repo_id}/resolve/main/{runtime_wheel_name}"'
	if runtime_wheel_name
	else 'pip install -e ".[training]" # From the updated lerobot_policy_dita checkout'
	)
	return f"""---
	library_name: lerobot
	pipeline_tag: robotics
	tags:
	- lerobot
	- dita
	- droid
	- pretraining
	---

	# Dita DROID pretraining initialization

	This repository converts the original Dita DROID weights for subsequent fine-tuning.
	It contains model weights, a LeRobot Dita configuration, and processor templates without
	dataset action statistics. It is not a ready-to-deploy DROID or LIBERO policy.

	## Provenance

	- Source: `{spec.checkpoint}` from the original [Dita](https://github.com/RoboDita/Dita) release.
	- Source checkpoint SHA256: `{checkpoint_sha}`.
	- Conversion base Git commit: `{code_sha}`. See `conversion_metadata.json` for the
	working-tree status, conversion-script hash, and packaged runtime hash when present.
	- All model parameter keys and shapes are checked, followed by `strict=True` loading.
	- Optimizer/scheduler state is not exported. No source DROID action statistics are inferred.

	## Install

	Use Python 3.12. The updated Dita runtime translates LeRobot's standard fine-tuning
	normalizer overrides to Dita's custom processors.

	```bash
	{install}
	```

	## Fine-tune

	Use a LeRobot dataset with seven-dimensional actions, a compatible primary RGB camera,
	and task language. Its action metadata must contain seven-element `q01` and `q99` arrays
	computed in the target training action convention. The default `gripper_mode=continuous`
	uses quantiles for the first six dimensions and dataset `action.min/max` for the gripper.
	Continuous outputs are restored to the recorded position units without thresholding or
	sign inversion. Use `--policy.gripper_mode=binary` for LIBERO signed training targets
	(-1=open, +1=closed), encoded internally as 1=open, 0=closed.
	ImageNet image normalization and CLIP text encoding remain fixed.

	```bash
	lerobot-train \\
	--policy.path={spec.repo_id} \\
	--policy.gripper_mode=continuous \\
	--policy.device=cuda \\
	--policy.dtype=bfloat16 \\
	--policy.input_features=null \\
	--policy.push_to_hub=false \\
	--dataset.repo_id=YOUR_USERNAME/YOUR_DATASET \\
	--output_dir=outputs/train/dita_droid_finetune
	```

	`policy.dtype` accepts `float32`, `float16` and `bfloat16` and controls autocast;
	weights and optimizer state remain FP32. Use BF16 on a supported GPU, or select
	FP32/FP16 explicitly. The default CUDA precision remains FP16 for compatibility.

	At the start of a new fine-tuning run, LeRobot binds the target dataset's statistics to
	both processor templates. They remain fixed during that run and are saved with the
	fine-tuned checkpoint. LeRobot 0.6.1 restores saved statistics on resume. The same
	pretraining repository can initialize multiple target datasets; no per-dataset pretraining
	upload is needed. Missing quantiles cause an explicit error when processing actions.

	The processor templates require cached or downloadable DINOv2/CLIP assets. Load the
	fine-tuned checkpoint together with its saved processors for evaluation and deployment.
	Any `validation_report.json` documents the checks actually run for this upload; no
	task success rate or DROID deployment equivalence is claimed.
	"""


	def previous_revision(api: HfApi, repo_id: str) -> str \| None:
	try:
	return api.model_info(repo_id).sha
	except HfHubHTTPError as error:
	if error.response is not None and error.response.status_code == 404:
	return None
	raise


	def convert_one(
	spec: ConversionSpec,
	*,
	output_root: Path,
	stats_root: Path,
	device: str,
	push_to_hub: bool,
	repo_id_override: str \| None,
	runtime_wheel: Path \| None = None,
	) -> dict[str, Any]:
	if repo_id_override:
	spec = replace(spec, repo_id=repo_id_override)
	pretraining_only = spec.suite == "droid_pretrain"
	if runtime_wheel is not None and (not runtime_wheel.is_file() or runtime_wheel.suffix != ".whl"):
	raise ValueError(f"Expected an existing runtime wheel: {runtime_wheel}")
	checkpoint_path = REPO_ROOT / spec.checkpoint
	if not checkpoint_path.is_file():
	raise FileNotFoundError(checkpoint_path)
	stats_path = None if pretraining_only else find_stats_file(stats_root, spec)
	output_dir = output_root / spec.output_name
	if output_dir.exists() and any(output_dir.iterdir()):
	raise FileExistsError(
	f"Refusing to mix artifacts in non-empty {output_dir}; use a fresh output root."
	)
	output_dir.mkdir(parents=True, exist_ok=True)

	checkpoint_sha = sha256_file(checkpoint_path)
	stats_sha = sha256_file(stats_path) if stats_path else None
	dataset_stats, stats_raw = load_dataset_stats(stats_path) if stats_path else (None, None)
	code_sha = git_revision()

	config = make_dita_config(spec, device)
	policy = DitaPolicy(config)
	expected = policy.model.state_dict()
	state = extract_parameter_state(checkpoint_path)
	aligned, stripped_prefix = align_and_validate_state(state, expected)
	load_result = policy.model.load_state_dict(aligned, strict=True)
	if load_result.missing_keys or load_result.unexpected_keys:
	raise RuntimeError(f"Strict load unexpectedly returned {load_result}.")

	policy.save_pretrained(output_dir)
	preprocessor, postprocessor = make_dita_pre_post_processors(config, dataset_stats)
	preprocessor.save_pretrained(output_dir)
	postprocessor.save_pretrained(output_dir)

	metadata: dict[str, Any] = {
	"converted_at_utc": datetime.now(timezone.utc).isoformat(),
	"source_model": "Dita/scripts/llama_dp.py",
	"source_checkpoint": spec.checkpoint,
	"source_checkpoint_sha256": checkpoint_sha,
	"checkpoint_parameter_tensors": len(aligned),
	"stripped_prefix": stripped_prefix,
	"strict_load": {
	"missing_keys": [],
	"unexpected_keys": [],
	"shape_mismatches": [],
	},
	"dataset_suite": spec.suite,
	"artifact_purpose": "finetuning_initialization" if pretraining_only else "deployment_policy",
	"statistics_binding": "target_dataset_at_finetuning" if pretraining_only else "bundled",
	"dataset_statistics_file": str(stats_path) if stats_path else None,
	"dataset_statistics_sha256": stats_sha,
	"action_q01": stats_raw[ACTION]["q01"] if stats_raw else None,
	"action_q99": stats_raw[ACTION]["q99"] if stats_raw else None,
	"gripper_mode": config.gripper_mode,
	"action_normalization_mask": list(config.action_normalization_mask),
	"conversion_code_git_sha": code_sha,
	"conversion_code_git_dirty": bool(subprocess.check_output(
	["git", "status", "--porcelain"], cwd=REPO_ROOT, text=True
	).strip()),
	"conversion_script_sha256": sha256_file(Path(__file__)),
	"target_repo_id": repo_id_override or spec.repo_id,
	}
	(output_dir / "conversion_metadata.json").write_text(
	json.dumps(metadata, indent=2) + "\n"
	)
	(output_dir / "README.md").write_text(
	pretraining_model_card(spec, checkpoint_sha, code_sha, runtime_wheel.name if runtime_wheel else None)
	if pretraining_only else model_card(
	spec,
	checkpoint_path,
	checkpoint_sha,
	stats_path,
	stats_sha,
	stats_raw,
	code_sha,
	runtime_wheel.name if runtime_wheel else None,
	)
	)

	required = {
	"config.json",
	"model.safetensors",
	"policy_preprocessor.json",
	"policy_postprocessor.json",
	"README.md",
	"conversion_metadata.json",
	}
	missing_artifacts = sorted(required - {path.name for path in output_dir.iterdir()})
	if missing_artifacts:
	raise RuntimeError(f"Conversion did not produce required files: {missing_artifacts}")
	state_files = sorted(path.name for path in output_dir.glob("*.safetensors") if path.name != "model.safetensors")
	if not state_files and not pretraining_only:
	raise RuntimeError("Processor state safetensors were not saved.")
	metadata["processor_state_files"] = state_files
	if runtime_wheel is not None:
	shutil.copy2(runtime_wheel, output_dir / runtime_wheel.name)
	metadata["runtime_wheel"] = runtime_wheel.name
	metadata["runtime_wheel_sha256"] = sha256_file(runtime_wheel)
	(output_dir / "conversion_metadata.json").write_text(
	json.dumps(metadata, indent=2) + "\n"
	)

	if push_to_hub:
	api = HfApi()
	account = api.whoami()["name"]
	target_repo = repo_id_override or spec.repo_id
	if target_repo.split("/", 1)[0] != account:
	raise PermissionError(f"Authenticated as {account}, cannot publish {target_repo}.")
	old_sha = previous_revision(api, target_repo)
	metadata["previous_hub_revision"] = old_sha
	(output_dir / "conversion_metadata.json").write_text(
	json.dumps(metadata, indent=2) + "\n"
	)
	api.create_repo(target_repo, repo_type="model", exist_ok=True)
	commit = api.upload_folder(
	repo_id=target_repo,
	repo_type="model",
	folder_path=output_dir,
	commit_message=f"Synchronize Dita {spec.suite} LeRobot checkpoint",
	)
	metadata["hub_commit_sha"] = commit.oid
	print(f"Uploaded {target_repo} at {commit.oid} (previous: {old_sha})")

	print(
	f"Converted {checkpoint_path.name}: {len(aligned)} tensors, strict=True, "
	f"SHA256={checkpoint_sha}, output={output_dir}"
	)
	del preprocessor, postprocessor, policy, aligned, state, expected
	gc.collect()
	if torch.cuda.is_available():
	torch.cuda.empty_cache()
	return metadata


	def parse_args() -> argparse.Namespace:
	parser = argparse.ArgumentParser(description=__doc__)
	selection = parser.add_mutually_exclusive_group(required=True)
	selection.add_argument(
	"--checkpoint",
	help="spatial/object/goal/long/droid_pretrain, or a known checkpoint filename/path.",
	)
	selection.add_argument("--all", action="store_true", help="Convert all four deployable LIBERO checkpoints.")
	parser.add_argument("--output-dir", type=Path, default=REPO_ROOT / "converted_checkpoints")
	parser.add_argument("--stats-root", type=Path, default=DEFAULT_STATS_ROOT)
	parser.add_argument("--device", default="cuda")
	parser.add_argument("--push-to-hub", action="store_true")
	parser.add_argument("--repo-id", help="Override the target repo for a single checkpoint only.")
	parser.add_argument("--runtime-wheel", type=Path, help="Bundle an updated Dita runtime wheel with the model.")
	return parser.parse_args()


	def main() -> None:
	args = parse_args()
	if args.repo_id and args.all:
	raise ValueError("--repo-id can only be used with --checkpoint.")
	selected = [SPECS[name] for name in ("spatial", "object", "goal", "long")]
	if not args.all:
	if args.checkpoint in SPECS:
	selected = [SPECS[args.checkpoint]]
	else:
	checkpoint_path = Path(args.checkpoint).expanduser().resolve()
	matches = [
	spec
	for spec in SPECS.values()
	if Path(spec.checkpoint).name == checkpoint_path.name
	or (spec.suite == "droid_pretrain" and checkpoint_path.name == "droid_pretrain.pth")
	]
	if len(matches) != 1:
	raise ValueError(
	f"Unknown checkpoint {args.checkpoint!r}; expected one of "
	f"{sorted(SPECS)} or their checkpoint paths."
	)
	selected = [replace(matches[0], checkpoint=str(checkpoint_path))]
	for spec in selected:
	convert_one(
	spec,
	output_root=args.output_dir,
	stats_root=args.stats_root,
	device=args.device,
	push_to_hub=args.push_to_hub,
	repo_id_override=args.repo_id,
	runtime_wheel=args.runtime_wheel,
	)


	if __name__ == "__main__":
	main()