# examples/beit.py
"""Readable BEiT mechanics and strict loaders for the two selected releases.

The MIM profile matches Microsoft's absolute-position ImageNet-1K release.
The classification profile matches the relative-bias, LayerScale 22K->1K release.
The smoke tokenizer is a synthetic mechanics fixture, never a learned dVAE.
Model weights and the DALL-E adapter belong to the separate inference exporter.

References: microsoft/unilm revision 31c5b904ca1bf2afb4c234a6675c683a4e5fc7cd,
beit/{masking_generator,modeling_pretrain,modeling_finetune}.py (MIT license).
"""

import argparse
import json
import math
from pathlib import Path
import random

from PIL import Image
import torch
from torch import nn
from torch.nn import functional as F


IMAGENET_MEAN = (0.485, 0.456, 0.406)
IMAGENET_STD = (0.229, 0.224, 0.225)


def _pixels(image):
    """Convert an RGB PIL image to floating CHW pixels without torchvision."""
    pixels = torch.frombuffer(bytearray(image.tobytes()), dtype=torch.uint8)
    return (
        pixels.reshape(image.height, image.width, 3).permute(2, 0, 1).float()
        / 255
    )


def _crop(image, crop_box):
    if not isinstance(image, Image.Image):
        raise ValueError("image must be a PIL image")
    image = image.convert("RGB")
    if crop_box is not None:
        if len(crop_box) != 4 or any(
            type(value) is not int for value in crop_box
        ):
            raise ValueError(
                "crop_box must contain four integer pixel coordinates"
            )
        left, top, right, bottom = crop_box
        if not (
            0 <= left < right <= image.width
            and 0 <= top < bottom <= image.height
        ):
            raise ValueError(
                "crop_box must be nonempty and inside the source image"
            )
        image = image.crop(crop_box)
    return image


# region: views
def make_views(image, crop_box=None, flip=False):
    """Crop once, then make spatially aligned Transformer and tokenizer views."""
    crop = _crop(image, crop_box)
    if flip:
        crop = crop.transpose(Image.Transpose.FLIP_LEFT_RIGHT)
    beit_crop = crop.resize((224, 224), Image.Resampling.BICUBIC)
    dvae_crop = crop.resize((112, 112), Image.Resampling.LANCZOS)
    mean = torch.tensor(IMAGENET_MEAN).reshape(3, 1, 1)
    std = torch.tensor(IMAGENET_STD).reshape(3, 1, 1)
    return {
        "beit": (_pixels(beit_crop) - mean) / std,
        "dvae": 0.8 * _pixels(dvae_crop) + 0.1,
        "beit_crop": beit_crop,
        "dvae_crop": dvae_crop,
    }


# endregion: views


def _image_batch(images):
    if not isinstance(images, torch.Tensor):
        raise ValueError("images must be a floating RGB tensor")
    if images.ndim == 3:
        images = images.unsqueeze(0)
    if (
        images.ndim != 4
        or images.shape[0] == 0
        or images.shape[1] != 3
        or not images.is_floating_point()
        or min(images.shape[2:]) <= 0
    ):
        raise ValueError("images must have shape [B,3,H,W] or [3,H,W]")
    return images


def _validate_tokenizer_logits(logits, images):
    expected = (images.shape[2] // 8, images.shape[3] // 8)
    if (
        not isinstance(logits, torch.Tensor)
        or logits.ndim != 4
        or logits.shape[0] != images.shape[0]
        or logits.shape[1] < 1
        or tuple(logits.shape[2:]) != expected
    ):
        raise ValueError("tokenizer must return [B,V,H/8,W/8] logits")


# region: targets
def visual_targets(tokenizer, dvae_images):
    """Freeze the tokenizer and flatten vocabulary argmax in row-major order."""
    images = _image_batch(dvae_images)
    if images.shape[2] % 8 or images.shape[3] % 8:
        raise ValueError("DALL-E view dimensions must be divisible by eight")
    tokenizer.eval().requires_grad_(False)
    for parameter in tokenizer.parameters():
        parameter.grad = None
    with torch.no_grad():
        logits = tokenizer(images)
        _validate_tokenizer_logits(logits, images)
        return logits.argmax(dim=1).flatten(1)


# endregion: targets


def _integer(value, name, minimum=1):
    if type(value) is not int or value < minimum:
        raise ValueError(f"{name} must be an integer >= {minimum}")
    return value


def _grid(grid_size):
    if isinstance(grid_size, tuple) and len(grid_size) == 2:
        return tuple(_integer(value, "grid_size") for value in grid_size)
    return (_integer(grid_size, "grid_size"),) * 2


def _place_rectangle(mask, remaining, min_area, rng):
    """Released sampler: ten attempts, uniform area, log-uniform aspect."""
    height, width = mask.shape
    for _ in range(10):
        area = rng.uniform(min_area, remaining)
        aspect = math.exp(rng.uniform(math.log(0.3), math.log(1 / 0.3)))
        h, w = round(math.sqrt(area * aspect)), round(math.sqrt(area / aspect))
        if h < height and w < width:
            top, left = rng.randint(0, height - h), rng.randint(0, width - w)
            rectangle = mask[top : top + h, left : left + w]
            added = h * w - int(rectangle.sum())
            if 0 < added <= remaining:
                rectangle.fill_(True)
                return added
    return 0


# region: masking
def block_mask(grid_size=14, num_masked=75, seed=0, min_area=4):
    """Released rectangle algorithm; bounded retries can leave an undershoot."""
    height, width = _grid(grid_size)
    _integer(num_masked, "num_masked", minimum=0)
    _integer(min_area, "min_area")
    if num_masked > height * width:
        raise ValueError("num_masked cannot exceed the patch grid")
    rng = random.Random(seed)
    mask = torch.zeros(height, width, dtype=torch.bool)
    count = 0
    while count < num_masked:
        added = _place_rectangle(mask, num_masked - count, min_area, rng)
        if added == 0:
            break  # No random single-patch completion.
        count += added
    return mask.flatten()


# endregion: masking


def _patch_mask(mask, batch, patches, device):
    if not isinstance(mask, torch.Tensor) or mask.dtype != torch.bool:
        raise ValueError("mask must be a Boolean tensor")
    if mask.shape == (patches,):
        mask = mask.unsqueeze(0).expand(batch, -1)
    if mask.shape != (batch, patches):
        raise ValueError(
            "mask must have shape [N] or [B,N] without the special token"
        )
    return mask.to(device)


class PatchEmbed(nn.Module):
    """Nonoverlapping patch projection, with official checkpoint state keys."""

    def __init__(self, image_size, patch_size, width):
        super().__init__()
        self.image_size = image_size
        self.patch_shape = (image_size // patch_size,) * 2
        self.num_patches = self.patch_shape[0] ** 2
        self.proj = nn.Conv2d(3, width, patch_size, stride=patch_size)

    def forward(self, images):
        images = _image_batch(images)
        if tuple(images.shape[2:]) != (self.image_size,) * 2:
            raise ValueError("input resolution must match image_size")
        return self.proj(images).flatten(2).transpose(1, 2)


def _relative_position_index(grid_size):
    """Index patch offsets and the three distinct special-token relationships."""
    height, width = grid_size
    coords = torch.stack(
        torch.meshgrid(torch.arange(height), torch.arange(width), indexing="ij")
    ).flatten(1)
    offsets = (coords[:, :, None] - coords[:, None, :]).permute(1, 2, 0)
    offsets[..., 0] += height - 1
    offsets[..., 1] += width - 1
    offsets[..., 0] *= 2 * width - 1
    distances = (2 * height - 1) * (2 * width - 1)
    index = torch.empty(
        height * width + 1, height * width + 1, dtype=torch.long
    )
    index[1:, 1:] = offsets.sum(-1)
    index[0, 1:] = distances  # Special query -> patch key.
    index[1:, 0] = distances + 1  # Patch query -> special key.
    index[0, 0] = distances + 2
    return index, distances + 3


class Attention(nn.Module):
    """Q/V biases, a zero key bias, and optional per-block relative bias."""

    def __init__(self, width, heads, grid_size=None):
        super().__init__()
        self.heads = heads
        self.scale = (width // heads) ** -0.5
        self.qkv = nn.Linear(width, 3 * width, bias=False)
        self.q_bias = nn.Parameter(torch.zeros(width))
        self.v_bias = nn.Parameter(torch.zeros(width))
        self.proj = nn.Linear(width, width)
        if grid_size is None:
            self.relative_position_bias_table = None
            self.register_buffer("relative_position_index", None)
        else:
            index, distances = _relative_position_index(grid_size)
            self.relative_position_bias_table = nn.Parameter(
                torch.zeros(distances, heads)
            )
            self.register_buffer("relative_position_index", index)

    def forward(self, x):
        bias = torch.cat(
            (self.q_bias, torch.zeros_like(self.v_bias), self.v_bias)
        )
        qkv = F.linear(x, self.qkv.weight, bias)
        batch, tokens, width = x.shape
        q, k, v = qkv.reshape(batch, tokens, 3, self.heads, -1).permute(
            2, 0, 3, 1, 4
        )
        relative_bias = None
        if self.relative_position_bias_table is not None:
            relative_bias = self.relative_position_bias_table[
                self.relative_position_index
            ]
            relative_bias = relative_bias.permute(2, 0, 1).unsqueeze(0)
        context = scaled_attention(q, k, v, self.scale, relative_bias)
        return self.proj(context.transpose(1, 2).reshape(batch, tokens, width))


class Mlp(nn.Module):
    """The released two-layer GELU MLP uses a fourfold hidden width."""

    def __init__(self, width):
        super().__init__()
        self.fc1 = nn.Linear(width, 4 * width)
        self.fc2 = nn.Linear(4 * width, width)

    def forward(self, x):
        return self.fc2(F.gelu(self.fc1(x)))


class Block(nn.Module):
    """Pre-norm residual block, optionally with LayerScale and stochastic depth."""

    def __init__(self, width, heads, grid_size=None, drop_path=0.0):
        super().__init__()
        self.norm1 = nn.LayerNorm(width, eps=1e-6)
        self.attn = Attention(width, heads, grid_size)
        self.norm2 = nn.LayerNorm(width, eps=1e-6)
        self.mlp = Mlp(width)
        self.drop_path = drop_path
        self.gamma_1 = (
            nn.Parameter(torch.full((width,), 0.1)) if grid_size else None
        )
        self.gamma_2 = (
            nn.Parameter(torch.full((width,), 0.1)) if grid_size else None
        )

    def _drop(self, x):
        if not self.training or self.drop_path == 0:
            return x
        keep = 1 - self.drop_path
        selector = (
            keep
            + torch.rand((x.shape[0], 1, 1), dtype=x.dtype, device=x.device)
        ).floor()
        return x / keep * selector

    def forward(self, x):
        return encode_block(x, self)


class BEiT(nn.Module):
    """Checkpoint-compatible original MIM and released mean-pooling classifier.

    Args:
        image_size: Square input resolution.
        patch_size: Nonoverlapping patch width and height.
        width: Encoder feature dimension, divisible by heads.
        depth: Number of pre-norm residual blocks.
        heads: Number of attention heads.
        vocab_size: Number of categorical visual targets, for MIM.
        classes: Number of image classes, for classification.
        profile: 'mim' or 'classification'; these select distinct state schemas.
        drop_path: Maximum stochastic depth probability, linearly scheduled.
    """

    def __init__(
        self,
        image_size=224,
        patch_size=16,
        width=768,
        depth=12,
        heads=12,
        vocab_size=8192,
        classes=1000,
        profile="mim",
        drop_path=0.0,
    ):
        super().__init__()
        for name, value in [
            ("image_size", image_size),
            ("patch_size", patch_size),
            ("width", width),
            ("heads", heads),
            ("vocab_size", vocab_size),
            ("classes", classes),
        ]:
            _integer(value, name)
        _integer(depth, "depth", minimum=0)
        if image_size % patch_size or width % heads or not 0 <= drop_path < 1:
            raise ValueError(
                "resolution/head divisibility and 0 <= drop_path < 1 are required"
            )
        if profile not in ("mim", "classification"):
            raise ValueError("profile must be 'mim' or 'classification'")
        self.profile = profile
        self.patch_embed = PatchEmbed(image_size, patch_size, width)
        self.cls_token = nn.Parameter(torch.zeros(1, 1, width))
        patches = self.patch_embed.num_patches
        self.mask_token = (
            nn.Parameter(torch.zeros(1, 1, width)) if profile == "mim" else None
        )
        self.pos_embed = (
            nn.Parameter(torch.zeros(1, patches + 1, width))
            if profile == "mim"
            else None
        )
        rates = torch.linspace(0, drop_path, depth).tolist()
        grid = (
            self.patch_embed.patch_shape
            if profile == "classification"
            else None
        )
        self.blocks = nn.ModuleList(
            Block(width, heads, grid, rate) for rate in rates
        )
        self.norm = (
            nn.LayerNorm(width, eps=1e-6) if profile == "mim" else nn.Identity()
        )
        if profile == "mim":
            self.lm_head = nn.Linear(width, vocab_size)
        else:
            self.fc_norm = nn.LayerNorm(width, eps=1e-6)
            self.head = nn.Linear(width, classes)
        self.apply(self._initialize)
        for token in [self.cls_token, self.mask_token, self.pos_embed]:
            if token is not None:
                self._initialize_tensor(token)
        with torch.no_grad():
            for index, block in enumerate(self.blocks, start=1):
                block.attn.proj.weight.div_(math.sqrt(2 * index))
                block.mlp.fc2.weight.div_(math.sqrt(2 * index))

    def _initialize_tensor(self, tensor):
        bound = 0.02 if self.profile == "mim" else 2.0
        nn.init.trunc_normal_(tensor, std=0.02, a=-bound, b=bound)

    def _initialize(self, module):
        if isinstance(module, nn.Linear) or (
            self.profile == "mim" and isinstance(module, nn.Conv2d)
        ):
            self._initialize_tensor(module.weight)
            if module.bias is not None:
                nn.init.zeros_(module.bias)
        elif isinstance(module, nn.LayerNorm):
            nn.init.ones_(module.weight)
            nn.init.zeros_(module.bias)

    @classmethod
    def from_checkpoint(cls, path, profile="mim", heads=12):
        """Load the selected state schema strictly, using restricted unpickling.

        Dimensions come from the state; heads must be supplied for tiny MIM tests
        because absolute-position checkpoint tensors cannot determine that value.
        The selected base releases both use twelve heads. No key is discarded.
        """
        checkpoint = torch.load(
            Path(path), map_location="cpu", weights_only=True
        )
        state = checkpoint.get("model", checkpoint)
        projection = state["patch_embed.proj.weight"]
        width, channels, patch, patch_width = projection.shape
        if channels != 3 or patch != patch_width:
            raise ValueError(
                "checkpoint patch projection must use square RGB patches"
            )
        depth = len(
            {key.split(".")[1] for key in state if key.startswith("blocks.")}
        )
        if profile == "mim":
            grid = math.isqrt(state["pos_embed"].shape[1] - 1)
            vocab_size, classes = state["lm_head.weight"].shape[0], 1000
        elif profile == "classification":
            indices = state["blocks.0.attn.relative_position_index"]
            grid = math.isqrt(indices.shape[0] - 1)
            heads = state["blocks.0.attn.relative_position_bias_table"].shape[1]
            vocab_size, classes = 8192, state["head.weight"].shape[0]
        else:
            raise ValueError("profile must be 'mim' or 'classification'")
        model = cls(
            grid * patch,
            patch,
            width,
            depth,
            heads,
            vocab_size,
            classes,
            profile,
        )
        for name, value in model.state_dict().items():
            if name.endswith("relative_position_index") and name in state:
                if not torch.equal(value, state[name]):
                    raise ValueError(
                        "checkpoint relative-position indices do not match its grid"
                    )
        model.load_state_dict(state, strict=True)
        return model.eval()

    def forward(self, images, mask=None):
        encoded = self.encode(images, mask)
        if self.profile == "classification":
            return self.forward_classification(encoded)
        return self.lm_head(encoded[:, 1:])  # Remove only the special token.

    def forward_classification(self, encoded):
        if self.profile != "classification":
            raise ValueError(
                "classification readout requires the classification profile"
            )
        if (
            encoded.ndim != 3
            or encoded.shape[1] != self.patch_embed.num_patches + 1
        ):
            raise ValueError(
                "encoded must retain all patch positions and the special token"
            )
        return classification_readout(encoded, self.fc_norm, self.head)

    # region: embeddings
    def embed(self, images, mask=None):
        """Replace selected patch embeddings, then add the special token/positions."""
        patches = self.patch_embed(images)
        batch, count, _ = patches.shape
        if mask is not None:
            if self.profile != "mim":
                raise ValueError(
                    "classification uses every patch and accepts no mask"
                )
            mask = _patch_mask(mask, batch, count, patches.device)
            patches = torch.where(mask.unsqueeze(-1), self.mask_token, patches)
        sequence = torch.cat(
            (self.cls_token.expand(batch, -1, -1), patches), dim=1
        )
        return sequence if self.pos_embed is None else sequence + self.pos_embed

    # endregion: embeddings

    def encode(self, images, mask=None):
        """Keep visible, masked, and special positions throughout every block."""
        return encode_sequence(self.embed(images, mask), self.blocks, self.norm)


# region: encoder
def scaled_attention(q, k, v, scale, relative_bias=None):
    """Each query attends to the entire retained sequence, including masked slots."""
    scores = (q * scale) @ k.transpose(-2, -1)
    if relative_bias is not None:
        scores = scores + relative_bias  # Released classification extension.
    return scores.softmax(dim=-1) @ v


def encode_block(sequence, block):
    """Pre-norm residuals; the classifier release adds learned LayerScale."""
    attention = block.attn(block.norm1(sequence))
    if block.gamma_1 is not None:
        attention = block.gamma_1 * attention
    sequence = sequence + block._drop(attention)
    mlp = block.mlp(block.norm2(sequence))
    if block.gamma_2 is not None:
        mlp = block.gamma_2 * mlp
    return sequence + block._drop(mlp)


def encode_sequence(sequence, blocks, final_norm):
    """All 196 patch slots plus the special token remain throughout the encoder."""
    for block in blocks:
        sequence = block(sequence)
    return final_norm(sequence)  # Identity for the mean-pooling classifier.


# endregion: encoder


# region: loss
def masked_loss(logits, targets, mask):
    """Average raw-logit cross entropy only over selected patch positions."""
    if logits.ndim != 3 or logits.shape[-1] < 1:
        raise ValueError("logits must have shape [B,N,V]")
    if targets.shape != logits.shape[:2] or targets.dtype != torch.long:
        raise ValueError("targets must be integer [B,N] labels")
    mask = _patch_mask(mask, *logits.shape[:2], logits.device)
    if not mask.any():
        raise ValueError("masked loss requires at least one selected patch")
    return F.cross_entropy(logits[mask], targets.to(logits.device)[mask])


# endregion: loss


def _student_optimizer(model, optimizer):
    student_ids = {id(parameter) for parameter in model.parameters()}
    if any(
        id(parameter) not in student_ids
        for group in optimizer.param_groups
        for parameter in group["params"]
    ):
        raise ValueError("optimizer must contain only BEiT parameters")
    if model.profile != "mim":
        raise ValueError("masked-token training requires the MIM profile")


# region: training
def training_step(model, tokenizer, views, mask, optimizer):
    """Update BEiT only; the tokenizer sees the complete aligned crop."""
    _student_optimizer(model, optimizer)
    targets = visual_targets(tokenizer, views["dvae"])
    model.train()
    optimizer.zero_grad(set_to_none=True)
    logits = model(_image_batch(views["beit"]), mask)
    loss = masked_loss(logits, targets, mask)
    if not torch.isfinite(loss):
        raise ValueError(
            "masked loss must be finite before updating parameters"
        )
    loss.backward()
    optimizer.step()
    return loss.item()


# endregion: training


# region: classification
def classification_readout(encoded, pooling_norm, classifier):
    """Released readout: exclude special token, mean patches, normalize, classify."""
    patch_features = encoded[:, 1:]
    image_features = pooling_norm(patch_features.mean(dim=1))
    return classifier(image_features)


# endregion: classification


class _SyntheticTokenizer(nn.Module):
    """Tiny frozen fixture logits for smoke mechanics; not DALL-E visual tokens."""

    def __init__(self):
        super().__init__()
        self.proj = nn.Conv2d(3, 17, 8, stride=8)

    def forward(self, images):
        return self.proj(images)


def smoke():
    """Print deterministic two-image CPU evidence without checkpoint downloads."""
    torch.set_num_threads(1)
    torch.manual_seed(0)
    photos = [
        Image.new("RGB", (256, 256), color)
        for color in [(190, 80, 40), (40, 100, 190)]
    ]
    aligned = [make_views(image) for image in photos]
    views = {
        key: torch.stack([view[key] for view in aligned])
        for key in ("beit", "dvae")
    }
    model = BEiT(width=48, depth=2, heads=3, vocab_size=17)
    tokenizer = _SyntheticTokenizer()
    mask = torch.stack([block_mask(seed=seed) for seed in (0, 1)])
    optimizer = torch.optim.AdamW(model.parameters(), lr=1e-3)
    loss = training_step(model, tokenizer, views, mask, optimizer)
    with torch.no_grad():
        logits = model(views["beit"], mask)
    gradient_names = [
        name
        for name, parameter in model.named_parameters()
        if parameter.grad is not None and parameter.grad.abs().sum() > 0
    ]
    return {
        "targetProvider": "synthetic mechanics fixture, not learned DALL-E tokens",
        "beitShape": list(views["beit"].shape),
        "dvaeShape": list(views["dvae"].shape),
        "targetShape": list(visual_targets(tokenizer, views["dvae"]).shape),
        "sequenceShape": list(model.embed(views["beit"], mask).shape),
        "logitsShape": list(logits.shape),
        "actualMaskCounts": mask.sum(1).tolist(),
        "loss": loss,
        "finiteLoss": math.isfinite(loss),
        "beitNonzeroGradientParameters": gradient_names,
        "tokenizerTrainableParameters": sum(
            p.requires_grad for p in tokenizer.parameters()
        ),
        "tokenizerGradientParameters": sum(
            p.grad is not None for p in tokenizer.parameters()
        ),
    }


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    mode = parser.add_mutually_exclusive_group(required=True)
    mode.add_argument("--smoke", action="store_true", help="run CPU mechanics")
    mode.add_argument(
        "--mim", action="store_true", help="predict masked visual tokens"
    )
    mode.add_argument(
        "--predict",
        action="store_true",
        help="classify with the 22K-to-1K checkpoint",
    )
    parser.add_argument("--image", type=Path)
    parser.add_argument("--output-dir", type=Path, default=Path("beit-output"))
    parser.add_argument(
        "--cache-dir",
        type=Path,
        default=Path.home() / ".cache" / "beit-example",
    )
    parser.add_argument("--seed", type=int, default=0)
    args = parser.parse_args()
    if args.smoke:
        result = smoke()
    else:
        if args.image is None:
            parser.error("--mim and --predict require --image")
        from beit_export import infer_image

        result = infer_image(
            args.image,
            args.output_dir,
            args.cache_dir,
            "mim" if args.mim else "classification",
            args.seed,
        )
    print(json.dumps(result, indent=2))


if __name__ == "__main__":
    main()
