# examples/sam2.py
"""Offline original-SAM-2 memory mechanics, not a segmentation model.

Conventions: facebookresearch/sam2 revision
0e78a118995e66bb27d78518c4bd9a3e95b4e266 (August 2024).
Reduced CPU modules use synthetic cached features, supplied mask logits and
supplied decoder tokens. There is no Hiera, learned mask decoder, checkpoint,
video inference or benchmark. Attention is one identity-projection cross-
attention residual, not SAM 2's self/cross-attention/MLP stack with RoPE.
"""

import argparse
from dataclasses import dataclass, field
import hashlib
import json
import math
from pathlib import Path

import torch
from torch import nn

UPSTREAM_REVISION = "0e78a118995e66bb27d78518c4bd9a3e95b4e266"
NO_OBJECT_SCORE = -1024.0


def check_tensor(value, shape, name):
    """Reject malformed, nonfinite or non-CPU float32 fixture tensors."""
    if (
        not isinstance(value, torch.Tensor)
        or tuple(value.shape) != shape
        or value.dtype != torch.float32
        or value.device.type != "cpu"
        or not torch.isfinite(value).all()
    ):
        raise ValueError(f"{name} must be a finite CPU float32 tensor {shape}")


def check_index(index):
    """Require a nonnegative integer frame index."""
    if isinstance(index, bool) or not isinstance(index, int) or index < 0:
        raise ValueError("frame index must be a nonnegative integer")


# region: frame_state
@dataclass
class FrameRecord:
    """Keep supplied masks, encoded spatial memory and decoder pointers apart."""

    spatial: torch.Tensor  # [1,4,2,2]
    pointer: torch.Tensor  # [1,8], split into two width-4 attention tokens
    mask_logits: torch.Tensor  # [1,1,4,4], absence is -1024
    conditioned: torch.Tensor  # [1,4,2,2], derived from current bank

    def __post_init__(self):
        check_tensor(self.spatial, (1, 4, 2, 2), "spatial")
        check_tensor(self.pointer, (1, 8), "pointer")
        check_tensor(self.mask_logits, (1, 1, 4, 4), "mask_logits")
        check_tensor(self.conditioned, (1, 4, 2, 2), "conditioned")


@dataclass
class FrameState:
    """Image features are unconditioned; propagated outputs are derived state."""

    cached_features: dict = field(default_factory=dict)
    conditioning: dict = field(default_factory=dict)
    nonconditioning: dict = field(default_factory=dict)

    def cache(self, index, features):
        """Store a synthetic unconditioned image embedding, independently of masks."""
        check_index(index)
        check_tensor(features, (1, 4, 2, 2), "features")
        self.cached_features[index] = features

    def store(self, index, record, prompted=False):
        """A conditioning output supersedes a derived output at the same frame."""
        check_index(index)
        if not isinstance(record, FrameRecord):
            raise ValueError("record must be a FrameRecord")
        if prompted:
            self.conditioning[index] = record
            self.nonconditioning.pop(index, None)
        elif index in self.conditioning:
            raise ValueError(
                "cannot overwrite a conditioning frame by propagation"
            )
        else:
            self.nonconditioning[index] = record


# endregion: frame_state


# region: select_memory
def select_memory(
    state,
    current,
    num_maskmem=4,
    max_conditioning=2,
    reverse=False,
    online=False,
):
    """Use the pinned closest-conditioning policy and stride-one recent slots.

    Online rejects future unprompted evidence. Reverse traversal is explicitly
    offline: its already processed memories have larger chronological indices.
    Storage is not evicted; these bounds apply to spatial attention inputs.
    """
    check_index(current)
    if (
        isinstance(num_maskmem, bool)
        or not isinstance(num_maskmem, int)
        or num_maskmem < 1
        or max_conditioning not in (-1,)
        and (not isinstance(max_conditioning, int) or max_conditioning < 2)
    ):
        raise ValueError(
            "require num_maskmem >= 1 and max_conditioning >= 2 or -1"
        )
    if online and reverse:
        raise ValueError("reverse traversal is offline")
    for index in (*state.conditioning, *state.nonconditioning):
        check_index(index)
    if online and any(index >= current for index in state.nonconditioning):
        raise ValueError(
            "online mode rejects future/current unprompted evidence"
        )
    eligible = {
        i: r
        for i, r in state.conditioning.items()
        if i != current and (not online or i < current)
    }
    if max_conditioning == -1 or len(eligible) <= max_conditioning:
        selected = dict(eligible)
    else:
        selected = {}
        before = max((i for i in eligible if i < current), default=None)
        after = min((i for i in eligible if i >= current), default=None)
        for index in (before, after):
            if index is not None:
                selected[index] = eligible[index]
        remaining = sorted(
            (i for i in eligible if i not in selected),
            key=lambda i: abs(i - current),
        )
        for index in remaining[: max_conditioning - len(selected)]:
            selected[index] = eligible[index]
    unselected = {i: r for i, r in eligible.items() if i not in selected}
    spatial = [(i, 0, record) for i, record in selected.items()]
    direction = 1 if reverse else -1
    for slot in range(1, num_maskmem):
        index = current + direction * (num_maskmem - slot)
        record = state.nonconditioning.get(index, unselected.get(index))
        if record is not None:
            spatial.append((index, slot, record))
    return spatial, selected, unselected


# endregion: select_memory


# region: time_positions
def time_positions(spatial, temporal_table, num_maskmem):
    """Apply original learned slot indexing; prompted frames share one slot.

    No signed-distance pointer positions are used: pointer temporal encoding is
    disabled in this original-release convention, unlike later SAM 2.1 options.
    Spatial sinusoidal/RoPE positions are omitted in this reduced fixture.
    """
    check_tensor(temporal_table, (num_maskmem, 4), "temporal_table")
    values, keys = [], []
    for _, slot, record in spatial:
        if not 0 <= slot < num_maskmem:
            raise ValueError("temporal slot outside bank")
        tokens = record.spatial.flatten(2).transpose(1, 2).squeeze(0)
        values.append(tokens)
        keys.append(tokens + temporal_table[num_maskmem - slot - 1])
    empty = temporal_table.new_empty(0, 4)
    return (
        torch.cat(keys) if keys else empty,
        torch.cat(values) if values else empty,
    )


# endregion: time_positions


# region: memory_attention
def memory_attention(features, keys, values, pointer_tokens, no_memory):
    """One reduced cross-attention residual; no decoder and no tracking output."""
    check_tensor(features, (1, 4, 2, 2), "features")
    check_tensor(no_memory, (4,), "no_memory")
    for name, tokens in (
        ("keys", keys),
        ("values", values),
        ("pointer_tokens", pointer_tokens),
    ):
        if not isinstance(tokens, torch.Tensor) or tokens.ndim != 2:
            raise ValueError(f"{name} must be a [tokens,4] tensor")
        check_tensor(tokens, (tokens.shape[0], 4), name)
    if keys.shape != values.shape:
        raise ValueError("keys and values must have matching shape")
    query = features.flatten(2).transpose(1, 2).squeeze(0)
    if keys.shape[0] + pointer_tokens.shape[0] == 0:
        # Matches the directly_add_no_mem_embed initial-frame branch.
        output = query + no_memory
    else:
        key = torch.cat((keys, pointer_tokens))
        value = torch.cat((values, pointer_tokens))
        weights = torch.softmax(query @ key.T / math.sqrt(4), dim=-1)
        output = query + weights @ value
    return output.T.reshape(1, 4, 2, 2)


# endregion: memory_attention


# region: encode_memory
class ReducedMemoryEncoder(nn.Module):
    """Reduced trainable mask downsampling, feature sum and convolutional fusion."""

    def __init__(self):
        super().__init__()
        self.mask_downsample = nn.Conv2d(1, 4, 2, stride=2)
        self.feature_projection = nn.Conv2d(4, 4, 1)
        self.fuser = nn.Conv2d(4, 4, 3, padding=1)

    def forward(self, features, mask_logits, from_points=False):
        """Follow sigmoid scale/bias (20,-10) or hard point-mask convention."""
        check_tensor(features, (1, 4, 2, 2), "features")
        check_tensor(mask_logits, (1, 1, 4, 4), "mask_logits")
        probabilities = (
            (mask_logits > 0).float() if from_points else mask_logits.sigmoid()
        )
        scaled_mask = probabilities * 20.0 - 10.0
        fused = self.feature_projection(features) + self.mask_downsample(
            scaled_mask
        )
        return self.fuser(fused)


# endregion: encode_memory


# region: object_pointer
def object_pointer(decoder_token, mask_logits, presence_logit, no_object):
    """Use supplied scores/tokens, hard absence and fixed no-object pointer.

    The token is a synthetic decoder-output fixture, never inferred from a
    spatial-memory average. Original pred_obj_scores/fixed_no_obj_ptr behavior
    gates mask logits at score > 0 and replaces an absent pointer.
    """
    check_tensor(decoder_token, (1, 8), "decoder_token")
    check_tensor(mask_logits, (1, 1, 4, 4), "mask_logits")
    check_tensor(no_object, (1, 8), "no_object")
    if not isinstance(presence_logit, (int, float)) or not math.isfinite(
        presence_logit
    ):
        raise ValueError("presence_logit must be finite")
    present = presence_logit > 0
    mask = (
        mask_logits
        if present
        else torch.full_like(mask_logits, NO_OBJECT_SCORE)
    )
    pointer = decoder_token if present else no_object
    return mask, pointer


def pointer_memory(
    state,
    current,
    selected,
    unselected,
    max_pointers=6,
    reverse=False,
    only_past=True,
):
    """Select pointers independently of spatial capacity, then split 8 into 2×4.

    Like the pinned code, the recent loop has max_pointers-1 offsets; selected
    conditioning pointers are added separately, so this is not a universal
    total-pointer FIFO cap. Caller supplies a video-length-clamped limit.
    """
    check_index(current)
    if (
        isinstance(max_pointers, bool)
        or not isinstance(max_pointers, int)
        or max_pointers < 1
    ):
        raise ValueError("max_pointers must be a positive integer")
    direction = 1 if reverse else -1
    pointers = [
        r.pointer
        for i, r in selected.items()
        if not only_past or (i >= current if reverse else i <= current)
    ]
    for distance in range(1, max_pointers):
        index = current + direction * distance
        if index < 0:
            break
        record = state.nonconditioning.get(index, unselected.get(index))
        if record is not None:
            pointers.append(record.pointer)
    return (
        torch.cat(pointers).reshape(-1, 4)
        if pointers
        else torch.empty(0, 4, dtype=torch.float32)
    )


# endregion: object_pointer


# region: correction
def correct(state, index, replacement):
    """Replace a prompted output and conservatively invalidate derived records.

    This fixture clears ALL nonconditioning outputs, including reverse passes:
    a stricter lifecycle than the pinned predictor's optional local clearing.
    Unconditioned image features and other prompted outputs remain reusable.
    No old masks are silently accepted as recomputed predictions.
    """
    state.store(index, replacement, prompted=True)
    invalidated = sorted(state.nonconditioning)
    state.nonconditioning.clear()
    return invalidated


# endregion: correction


def condition(state, current, temporal_table, no_memory, **selection):
    """Read cached features and return derived context, not mask predictions."""
    spatial, selected, unselected = select_memory(state, current, **selection)
    keys, values = time_positions(
        spatial, temporal_table, selection.get("num_maskmem", 4)
    )
    pointers = pointer_memory(
        state,
        current,
        selected,
        unselected,
        reverse=selection.get("reverse", False),
    )
    output = memory_attention(
        state.cached_features[current], keys, values, pointers, no_memory
    )
    return output, [i for i, _, _ in spatial], pointers.shape[0]


def smoke(seed=7):
    """Execute deterministic finite mechanics and state/gradient observations."""
    torch.manual_seed(seed)
    encoder = ReducedMemoryEncoder()
    state = FrameState()
    table = torch.randn(4, 4) * 0.1
    no_memory = torch.randn(4) * 0.1
    no_object = torch.randn(1, 8)
    for index in range(6):
        state.cache(index, torch.randn(1, 4, 2, 2))
    empty, _, _ = condition(state, 0, table, no_memory, online=True)
    for index in range(4):
        context, _, _ = condition(state, index, table, no_memory, online=True)
        mask, pointer = object_pointer(
            torch.randn(1, 8),
            torch.randn(1, 1, 4, 4),
            -1.0 if index == 2 else 1.0,
            no_object,
        )
        spatial = encoder(state.cached_features[index], mask)
        state.store(
            index,
            FrameRecord(spatial, pointer, mask, context),
            prompted=index == 0,
        )
    before, indices, pointer_count = condition(
        state, 4, table, no_memory, online=True
    )
    replacement_mask = torch.ones(1, 1, 4, 4) * 3
    replacement = FrameRecord(
        encoder(state.cached_features[0], replacement_mask),
        torch.ones(1, 8),
        replacement_mask,
        empty,
    )
    cache_ids = {i: id(x) for i, x in state.cached_features.items()}
    absent_mask_count = int(
        (state.nonconditioning[2].mask_logits == NO_OBJECT_SCORE).sum()
    )
    invalidated = correct(state, 0, replacement)
    after, after_indices, _ = condition(state, 4, table, no_memory, online=True)
    loss = after.square().mean()
    loss.backward()
    gradients = [p.grad for p in encoder.parameters()]
    return {
        "source_sha256": hashlib.sha256(
            Path(__file__).read_bytes()
        ).hexdigest(),
        "upstream_revision": UPSTREAM_REVISION,
        "seed": seed,
        "boundary": "synthetic memory mechanics; no segmentation decoder or pretrained tracking",
        "reductions": {
            "batch": 1,
            "feature_width": 4,
            "pointer_width": 8,
            "grid": [2, 2],
            "mask_grid": [4, 4],
            "num_maskmem": 4,
            "temporal_stride": 1,
            "max_conditioning": 2,
            "pointer_recent_limit": 6,
            "cross_attention_heads": 1,
        },
        "shapes": {
            "context": list(after.shape),
            "spatial": list(replacement.spatial.shape),
            "pointer": list(replacement.pointer.shape),
        },
        "selected_before": indices,
        "selected_after": after_indices,
        "pointer_tokens_before": pointer_count,
        "invalidated_frames": invalidated,
        "empty_path_error": float(
            (empty - state.cached_features[0] - no_memory[None, :, None, None])
            .abs()
            .max()
            .detach()
        ),
        "absence_suppressed_pixels": absent_mask_count,
        "correction_context_delta": float(
            (before - after).abs().max().detach()
        ),
        "cached_features_reused": all(
            id(state.cached_features[i]) == old for i, old in cache_ids.items()
        ),
        "loss": float(loss.detach()),
        "finite_gradients": all(
            g is not None and bool(torch.isfinite(g).all()) for g in gradients
        ),
        "gradient_norm": float(sum(g.square().sum() for g in gradients).sqrt()),
    }


def main():
    """Print JSON only when explicitly requested; imports do not run examples."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--smoke", action="store_true")
    parser.add_argument("--seed", type=int, default=7)
    args = parser.parse_args()
    if args.smoke:
        print(json.dumps(smoke(args.seed), indent=2, allow_nan=False))


if __name__ == "__main__":
    main()
