Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

8.1 KB
Raw Blame
"""Safe, serialization-only checkpoint helpers for Cua-S1 models."""

from __future__ import annotations

import hashlib
import json
import os
import tempfile
from collections.abc import Mapping
from pathlib import Path
from typing import Any

import torch

FORMAT_NAME = "cua-s1"
FORMAT_VERSION = 1


def _canonical_json(value: Any) -> bytes:
    return json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")


def _state_signature(tensors: Mapping[str, Any], config: Mapping[str, Any]) -> str:
    digest = hashlib.sha256()
    digest.update(_canonical_json(dict(config)))
    for name in sorted(tensors):
        tensor = tensors[name]
        digest.update(_canonical_json([name, str(tensor.dtype), list(tensor.shape)]))
        raw = tensor.detach().cpu().contiguous().reshape(-1).view(torch.uint8)
        digest.update(raw.numpy().tobytes())
    return digest.hexdigest()


def _temporary_path(target: Path) -> Path:
    descriptor, name = tempfile.mkstemp(prefix=f".{target.name}.", suffix=".tmp", dir=target.parent)
    os.close(descriptor)
    return Path(name)


def resolve_checkpoint_paths(directory_or_path: str | Path) -> tuple[Path, Path]:
    """Return the weights and JSON paths for a checkpoint location."""
    path = Path(directory_or_path).expanduser()
    suffix = path.suffix.lower()
    if suffix in {".pt", ".pth", ".bin", ".pkl", ".pickle"}:
        raise ValueError(
            "legacy pickle-based checkpoints are not supported; convert the model "
            "to a safetensors file plus JSON configuration in a trusted environment"
        )
    if suffix == ".safetensors":
        same_stem_config = path.with_suffix(".json")
        if path.name == "model.safetensors":
            canonical_config = path.with_name("config.json")
            if canonical_config.exists() or not same_stem_config.exists():
                return path, canonical_config
        return path, same_stem_config
    if suffix == ".json":
        same_stem_weights = path.with_suffix(".safetensors")
        if path.name == "config.json":
            canonical_weights = path.with_name("model.safetensors")
            if canonical_weights.exists() or not same_stem_weights.exists():
                return canonical_weights, path
        return same_stem_weights, path
    if suffix:
        raise ValueError("checkpoint path must be a directory, .safetensors file, or .json file")
    return path / "model.safetensors", path / "config.json"


def save_checkpoint_files(
    directory_or_path: str | Path,
    state_dict: Mapping[str, Any],
    config: Mapping[str, Any],
    metadata: Mapping[str, Any] | None = None,
) -> tuple[Path, Path]:
    """Write tensors with safetensors and non-executable data with JSON."""
    weights_path, config_path = resolve_checkpoint_paths(directory_or_path)
    try:
        from safetensors.torch import save_file
    except ImportError as exc:  # pragma: no cover - depends on optional installation
        raise RuntimeError("saving Cua-S1 checkpoints requires the 'safetensors' package") from exc

    if weights_path.exists() and weights_path.is_dir():
        raise ValueError(f"weights path is a directory: {weights_path}")
    if config_path.exists() and config_path.is_dir():
        raise ValueError(f"config path is a directory: {config_path}")
    weights_path.parent.mkdir(parents=True, exist_ok=True)
    config_path.parent.mkdir(parents=True, exist_ok=True)

    tensors: dict[str, Any] = {}
    for name, tensor in state_dict.items():
        if not isinstance(name, str) or not name:
            raise ValueError("state_dict keys must be non-empty strings")
        if not hasattr(tensor, "detach"):
            raise TypeError(f"state_dict value {name!r} is not a tensor")
        tensors[name] = tensor.detach().cpu().contiguous()
    if not tensors:
        raise ValueError("cannot save an empty state_dict")

    try:
        state_signature = _state_signature(tensors, config)
    except (TypeError, ValueError) as exc:
        raise ValueError("checkpoint config and metadata must be JSON serializable") from exc
    document = {
        "format": FORMAT_NAME,
        "format_version": FORMAT_VERSION,
        "state_signature": state_signature,
        "config": dict(config),
        "metadata": dict(metadata or {}),
    }
    try:
        encoded = json.dumps(document, indent=2, sort_keys=True) + "\n"
    except (TypeError, ValueError) as exc:
        raise ValueError("checkpoint config and metadata must be JSON serializable") from exc

    weights_temporary = _temporary_path(weights_path)
    config_temporary = _temporary_path(config_path)
    try:
        save_file(
            tensors,
            str(weights_temporary),
            metadata={
                "format": FORMAT_NAME,
                "format_version": str(FORMAT_VERSION),
                "state_signature": state_signature,
            },
        )
        os.replace(weights_temporary, weights_path)
        config_temporary.write_text(encoded, encoding="utf-8")
        os.replace(config_temporary, config_path)
    finally:
        weights_temporary.unlink(missing_ok=True)
        config_temporary.unlink(missing_ok=True)
    return weights_path, config_path


def load_checkpoint_files(
    directory_or_path: str | Path,
) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
    """Load a safetensors state dict and validate its JSON configuration."""
    weights_path, config_path = resolve_checkpoint_paths(directory_or_path)
    try:
        from safetensors import safe_open
        from safetensors.torch import load_file
    except ImportError as exc:  # pragma: no cover - depends on optional installation
        raise RuntimeError("loading Cua-S1 checkpoints requires the 'safetensors' package") from exc

    if not weights_path.is_file():
        raise FileNotFoundError(f"checkpoint weights not found: {weights_path}")
    if not config_path.is_file():
        raise FileNotFoundError(f"checkpoint config not found: {config_path}")

    try:
        document = json.loads(config_path.read_text(encoding="utf-8"))
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise ValueError(f"invalid checkpoint JSON: {config_path}") from exc
    if not isinstance(document, dict):
        raise ValueError("checkpoint JSON must contain an object")
    if document.get("format") != FORMAT_NAME:
        raise ValueError(f"unsupported checkpoint format: {document.get('format')!r}")
    if document.get("format_version") != FORMAT_VERSION:
        raise ValueError(
            f"unsupported checkpoint format version: {document.get('format_version')!r}"
        )
    config = document.get("config")
    metadata = document.get("metadata", {})
    state_signature = document.get("state_signature")
    if not isinstance(config, dict):
        raise ValueError("checkpoint JSON field 'config' must be an object")
    if not isinstance(metadata, dict):
        raise ValueError("checkpoint JSON field 'metadata' must be an object")
    if not isinstance(state_signature, str) or len(state_signature) != 64:
        raise ValueError("checkpoint JSON field 'state_signature' must be a SHA-256 digest")

    try:
        with safe_open(str(weights_path), framework="pt", device="cpu") as handle:
            weights_metadata = handle.metadata() or {}
        if weights_metadata.get("format") != FORMAT_NAME:
            raise ValueError("unsupported safetensors checkpoint format")
        if weights_metadata.get("format_version") != str(FORMAT_VERSION):
            raise ValueError("unsupported safetensors checkpoint format version")
        if weights_metadata.get("state_signature") != state_signature:
            raise ValueError("checkpoint state signature mismatch")
        state_dict = load_file(str(weights_path), device="cpu")
    except ValueError:
        raise
    except Exception as exc:
        raise ValueError(f"invalid safetensors checkpoint: {weights_path}") from exc
    if not state_dict:
        raise ValueError("checkpoint contains no tensors")
    if _state_signature(state_dict, config) != state_signature:
        raise ValueError("checkpoint state signature mismatch")
    return state_dict, config, metadata