# examples/siglip2.py
"""Offline CPU mechanics for the SigLIP 2 review, using authored tiny tensors.

Exact inherited signed sigmoid reduction and EMA arithmetic; generic token NLL.
Global/masked squared errors are TEACHING SURROGATES, not the SILC/TIPS
consistency objective used by SigLIP 2. Grid bookkeeping is not NaFlex resize.
No pretrained model, training pipeline, data curation or benchmark reproduction.
Source: https://arxiv.org/html/2502.14786v1 sections 2.2 to 2.4.
"""

import argparse
import hashlib
import json
import math
from pathlib import Path

import torch
from torch.nn import functional as F


def _features(value, dimensions):
    """Require finite nonempty floating CPU features of the stated rank."""
    if (not isinstance(value, torch.Tensor) or value.ndim != dimensions
            or min(value.shape) < 1 or value.device.type != "cpu"
            or value.dtype not in (torch.float32, torch.float64)
            or not torch.isfinite(value).all()):
        raise ValueError("expected nonempty finite CPU float32/64 features")


def _same_features(student, teacher, dimensions):
    """Require corresponding feature tensors with matching dtype and shape."""
    _features(student, dimensions)
    _features(teacher, dimensions)
    if student.shape != teacher.shape or student.dtype != teacher.dtype:
        raise ValueError("student and teacher must share shape and dtype")


# region: alignment
def alignment_loss(image, text, log_scale, bias):
    """Compute inherited all-pairs sigmoid sum/N, not mean over N squared."""
    _same_features(image, text, 2)
    for parameter in (log_scale, bias):
        if (not isinstance(parameter, torch.Tensor) or parameter.ndim != 0
                or parameter.dtype != image.dtype or parameter.device != image.device
                or not torch.isfinite(parameter)):
            raise ValueError("scale and bias must be matching finite scalars")
    scale = log_scale.exp()
    if not torch.isfinite(scale) or scale <= 0:
        raise ValueError("exponentiated scale must be finite and positive")
    image = image / (image.norm(dim=-1, keepdim=True) + 1e-8)
    text = text / (text.norm(dim=-1, keepdim=True) + 1e-8)
    logits = scale * (image @ text.T) + bias
    n = image.shape[0]
    labels = 2 * torch.eye(n, dtype=image.dtype) - 1
    return F.softplus(-labels * logits).sum() / n
# endregion: alignment


# region: decoder
def decoder_token_nll(logits, targets):
    """Generic mean token NLL; inputs/attention/task serialization are external."""
    _features(logits, 3)  # [batch, target positions, vocabulary]
    if (not isinstance(targets, torch.Tensor)
            or targets.shape != logits.shape[:2] or targets.dtype != torch.int64
            or targets.device.type != "cpu"):
        raise ValueError("targets must be matching CPU integer token IDs")
    valid = targets != -100
    if not valid.any() or ((targets[valid] < 0)
                           | (targets[valid] >= logits.shape[-1])).any():
        raise ValueError("need valid vocabulary IDs; -100 denotes padding")
    return F.cross_entropy(logits[valid], targets[valid])
# endregion: decoder


# region: ema
@torch.no_grad()
def ema_update(teacher, student, momentum):
    """Return EMA parameters without a gradient path; leave inputs unchanged."""
    _same_features(student, teacher, 1)
    if not math.isfinite(momentum) or not 0 <= momentum <= 1:
        raise ValueError("momentum must be in [0, 1]")
    return momentum * teacher + (1 - momentum) * student
# endregion: ema


# region: global
def global_consistency(student_local, teacher_global):
    """TEACHING SURROGATE: squared feature error, not official consistency loss."""
    _features(student_local, 2)  # [number of local views, channels]
    _features(teacher_global, 2)  # [1, channels], one image in this toy
    if (teacher_global.shape != (1, student_local.shape[1])
            or teacher_global.dtype != student_local.dtype):
        raise ValueError("one global teacher vector must match channel width")
    target = teacher_global.detach().expand_as(student_local)
    return (student_local - target).square().mean()
# endregion: global


# region: masked
def masked_consistency(student, teacher, masked, valid):
    """TEACHING SURROGATE: error only at valid masked feature positions."""
    _same_features(student, teacher, 3)  # [batch, patches, channels]
    for mask in (masked, valid):
        if (not isinstance(mask, torch.Tensor) or mask.dtype != torch.bool
                or mask.shape != student.shape[:2] or mask.device.type != "cpu"):
            raise ValueError("masks must be matching CPU boolean [B, P] tensors")
    selected = masked & valid
    if not selected.any():
        raise ValueError("need at least one valid masked position")
    difference = student[selected] - teacher.detach()[selected]
    return difference.square().mean()
# endregion: masked


# region: geometry
def grid_layout(rows, columns, budget):
    """Bookkeep a chosen grid; does NOT choose NaFlex resize/interpolation."""
    for value in (rows, columns, budget):
        if isinstance(value, bool) or not isinstance(value, int) or value < 1:
            raise ValueError("grid dimensions and budget must be positive integers")
    used = rows * columns
    if used > budget:
        raise ValueError("chosen grid exceeds token budget")
    return {
        "coordinates": [[row, col] for row in range(rows) for col in range(columns)],
        "valid": [True] * used + [False] * (budget - used),
        "used": used,
        "padding": budget - used,
    }
# endregion: geometry


def smoke(seed=7):
    """Return measured toy arithmetic and actual autograd checks, offline."""
    generator = torch.Generator(device="cpu").manual_seed(seed)

    def features(*shape):
        return torch.randn(*shape, generator=generator, dtype=torch.float64,
                           requires_grad=True)

    image, text = features(3, 4), features(3, 4)
    log_scale = torch.tensor(math.log(10.), dtype=torch.float64, requires_grad=True)
    bias = torch.tensor(-10., dtype=torch.float64, requires_grad=True)
    local, global_target = features(8, 4), features(1, 4)
    patches, patch_targets = features(1, 4, 4), features(1, 4, 4)
    masked = torch.tensor([[True, False, True, False]])
    valid = torch.ones(1, 4, dtype=torch.bool)
    decoder = features(1, 3, 7)
    losses = {
        "alignment": alignment_loss(image, text, log_scale, bias),
        "decoder_generic_nll": decoder_token_nll(decoder, torch.tensor([[1, 2, -100]])),
        "global_teaching_surrogate": global_consistency(local, global_target),
        "masked_teaching_surrogate": masked_consistency(patches, patch_targets, masked, valid),
    }
    # Summation exercises independent paths; it is NOT the paper's total loss.
    sum(losses.values()).backward()
    gradients = {name: value.grad.norm().item() for name, value in (
        ("image", image), ("text", text), ("log_scale", log_scale),
        ("bias", bias), ("local", local), ("patches", patches), ("decoder", decoder))}
    assert all(math.isfinite(value) and value > 0 for value in gradients.values())
    assert global_target.grad is None and patch_targets.grad is None
    assert patches.grad[~masked].abs().sum().item() == 0
    ema = ema_update(torch.tensor([2., 4.]), torch.tensor([6., 8.]), .75)
    return {
        "scope": "authored CPU mechanics, not pretrained outputs or official auxiliary losses",
        "seed": seed,
        "dtype": "float64",
        "device": "cpu",
        "torch": torch.__version__,
        "source_sha256": hashlib.sha256(Path(__file__).read_bytes()).hexdigest(),
        "losses": {name: value.item() for name, value in losses.items()},
        "gradient_norms": gradients,
        "teacher_gradients_absent": True,
        "unmasked_patch_gradients_zero": True,
        "ema_fixture": ema.tolist(),
        "geometry": grid_layout(2, 3, 8),
        "optimizer_steps": 0,
    }


def main():
    """Run the deterministic mechanics smoke without network access."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--smoke", action="store_true", help="Run offline arithmetic checks.")
    parser.add_argument("--seed", type=int, default=7)
    arguments = parser.parse_args()
    print(json.dumps(smoke(arguments.seed), indent=2, allow_nan=False))


if __name__ == "__main__":
    main()
