"""Auditable locked recipes, official optimizer preparation and integration status.

Constrained YOLO and RF-DETR run through sensor research integration. Official
defaults remain gated despite runnable optimizer helpers.
"""
from __future__ import annotations

import hashlib
import importlib.metadata
import importlib.util
import math
from pathlib import Path
from types import SimpleNamespace

import torch

LOCKED_VERSIONS = {"ultralytics": "8.4.163", "rfdetr": "1.11.0"}
RECIPE_NAMES = ("official_default", "official_research_constrained", "project_adamw_pilot")


def _source(package, relative):
    version = importlib.metadata.version(package)
    if version != LOCKED_VERSIONS[package]:
        raise RuntimeError(f"{package}=={LOCKED_VERSIONS[package]} required, found {version}")
    path = Path(importlib.util.find_spec(package).origin).parent / relative
    return {"package": package, "version": version, "file": relative,
            "sha256": hashlib.sha256(path.read_bytes()).hexdigest()}


def _positive_int(name, value):
    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
        raise ValueError(f"{name} must be a positive integer")


def _batch(batch_size, effective_batch):
    _positive_int("batch_size", batch_size)
    _positive_int("effective_batch", effective_batch)
    if effective_batch < batch_size or effective_batch % batch_size:
        raise ValueError("effective_batch must be divisible by batch_size")


def resolve_ultralytics_auto(*, num_train_samples, epochs, batch_size, nbs=64, nc=1):
    """Resolve the exact locked BaseTrainer auto branch, including >10000 boundary.

    iterations is upstream's selection estimate, not actual accumulated steps.
    """
    for name, value in locals().copy().items():
        _positive_int(name, value)
    _source("ultralytics", "engine/trainer.py")
    iterations = math.ceil(num_train_samples / max(batch_size, nbs)) * epochs
    name, lr = ("MuSGD", 0.01) if iterations > 10000 else ("AdamW", round(0.002 * 5 / (4 + nc), 6))
    return {"name": name, "lr": lr, "momentum": 0.9,
            "iterations": iterations, "warmup_bias_lr": 0.0}


def get_recipe_spec(family, recipe="official_research_constrained", *, batch_size=4):
    """Return a JSON-safe specification; preserve full upstream default snapshots.

    RF-DETR defaults include both Small model config and TrainConfig. Dataset paths
    are placeholders. Research constraints use one device; global batch requires
    a separate explicit distributed design. Structural comparisons must use the
    same recipe, batch, preprocessing and selection protocol.
    """
    if family not in {"yolo26", "yolov8", "yolov8-cspnext", "rfdetr-small"}:
        raise ValueError(f"unsupported family: {family}")
    if recipe not in RECIPE_NAMES:
        raise ValueError(f"unknown recipe: {recipe}")
    _positive_int("batch_size", batch_size)
    if recipe == "official_research_constrained":
        _batch(batch_size, 16)
    is_rf = family == "rfdetr-small"
    if is_rf:
        from rfdetr.config import TrainConfig, RFDETRSmallConfig
        defaults = {"train": TrainConfig(dataset_dir="<dataset_dir>").model_dump(mode="json"),
                    "model": RFDETRSmallConfig().model_dump(mode="json")}
        sources = [_source("rfdetr", p) for p in (
            "config.py", "training/param_groups.py", "models/backbone/backbone.py",
            "training/module_model.py", "training/callbacks/ema.py", "training/trainer.py",
            "datasets/coco.py", "datasets/transforms.py")]
        optimizer = {"name": "AdamW", "lr": defaults["train"]["lr"],
                     "lr_encoder": defaults["train"]["lr_encoder"],
                     "lr_component_decay": 0.7, "lr_vit_layer_decay": 0.8,
                     "weight_decay": 1e-4, "betas": [0.9, 0.999],
                     "groups": {"other": "lr", "decoder": "lr * lr_component_decay",
                                "encoder": "lr_encoder * lr_component_decay**2 * layer_decay",
                                "encoder_decay": "zero for gamma/pos_embed/rel_pos/bias/norm/embeddings; otherwise weight_decay",
                                "other_decay": "optimizer weight_decay, including head/decoder biases"},
                     "layer_decay": "num_layers=out_feature_indexes[-1]+1; exponent=num_layers+1-layer_id; embeddings=0; .layer.k.=k+1; otherwise num_layers+1",
                     "fused": "model fused_optimizer=True, gated by upstream runtime/precision eligibility"}
        schedule = {"name": "step", "warmup_epochs": 0.0, "lr_drop": 100,
                    "gamma": 0.1, "interval": "optimizer_step", "cosine_min_factor_if_selected": 0.0}
        ema = {"enabled": True, "decay": 0.993, "tau": 100, "update_interval": 1,
               "formula": "decay * (1-exp(-updates/tau))", "evaluation": "selected EMA by default"}
        augmentation = {"backend_selector": "cpu", "aug_config": None,
                        "default_optional_transform": "torchvision horizontal flip p=.5",
                        "square_resize_div_64": True, "scale_jitter": True,
                        "multi_scale": "per-batch", "expanded_scales": True,
                        "resize_crop": "direct random resize or resize[400,500,600] + random crop + selected target resize",
                        "mosaic": "not present in upstream RF-DETR pipeline"}
        overrides = {"model": {"resolution": 640}, "train": {
            "batch_size": batch_size, "grad_accum_steps": 16 // batch_size,
            "epochs": 300, "early_stopping": True, "early_stopping_patience": 50,
            "multi_scale": "off", "expanded_scales": False, "scale_jitter": False},
            "protocol": {"mosaic": False, "effective_batch": 16, "max_epochs": 300,
                         "patience": 50, "size": 640}}
    else:
        import yaml
        sources = [_source("ultralytics", p) for p in (
            "cfg/default.yaml", "engine/trainer.py", "utils/torch_utils.py", "data/augment.py")]
        package = Path(importlib.util.find_spec("ultralytics").origin).parent
        defaults = {"train": yaml.safe_load((package / "cfg/default.yaml").read_text())}
        optimizer = {"name": "auto", "selection_iterations": "ceil(train_samples/max(batch,nbs))*epochs",
                     "selection": "MuSGD lr=.01 momentum=.9 iff iterations>10000; else AdamW lr=round(.002*5/(4+nc),6), beta1=.9",
                     "warmup_bias_lr_after_auto": 0.0, "weight_decay": 0.0005,
                     "scaled_weight_decay": "weight_decay * batch * max(round(nbs/batch),1) / nbs",
                     "groups": {"priority": ["MuSGD ndim in {2,4}", "bias substring", "Norm module or logit_scale substring", "weight"],
                                "bias_decay": 0.0, "norm_decay": 0.0,
                                "weight_decay": "scaled_weight_decay", "muon_decay": "scaled_weight_decay"},
                     "MuSGD": {"muon": 0.2, "sgd": 1.0,
                                "boosted_lr": "3x for head cv3/one2one_cv3, proto.semseg/SemanticSegment"},
                     "fused": "Adam/AdamW only on eligible CUDA"}
        schedule = {"name": "linear", "lrf": 0.01, "warmup_epochs": 3.0,
                    "warmup_iterations": "round(min(warmup_epochs,max(epochs-1,0))*num_batches)",
                    "warmup": "group LR interpolation plus momentum/accumulation interpolation in upstream loop",
                    "interval": "epoch"}
        ema = {"enabled": True, "decay": 0.9999, "tau": 2000,
               "formula": "decay * (1-exp(-updates/tau))", "evaluation": "EMA"}
        augmentation = {k: defaults["train"][k] for k in (
            "hsv_h", "hsv_s", "hsv_v", "degrees", "translate", "scale", "shear", "perspective",
            "flipud", "fliplr", "mosaic", "mixup", "cutmix", "copy_paste", "close_mosaic", "multi_scale")}
        overrides = {"train": {"imgsz": 640, "batch": batch_size, "nbs": 16,
                               "mosaic": 0.0, "epochs": 300, "patience": 50},
                     "protocol": {"effective_batch": 16, "size": 640, "mosaic": False,
                                  "max_epochs": 300, "patience": 50}}
    blockers = ["Project train.py does not consume this recipe specification.",
                "Official EMA, schedule/warmup, augmentation/preprocessing and trainer checkpoint state are not integrated.",
                "Sensor adapters and project evaluation/selection must be explicitly integrated and compared under one fixed protocol."]
    if is_rf and importlib.util.find_spec("pytorch_lightning") is None:
        blockers.append("RF-DETR training/__init__.py requires pytorch_lightning, absent from this environment; official Lightning trainer cannot be imported.")
    spec = {"schema_version": 1, "family": family, "recipe": recipe,
            "training_status": "not_runnable", "optimizer_preparation_status": "runnable",
            "sources": sources, "official_defaults": defaults,
            "research_overrides": overrides if recipe == "official_research_constrained" else {},
            "optimizer": optimizer, "schedule": schedule, "ema": ema,
            "augmentation": augmentation, "blockers": blockers}
    if recipe == "official_research_constrained":
        spec["constraint_caveats"] = [
            "Ultralytics warmup ramps accumulation from 1 to nbs/batch; exact effective batch 16 at every step requires an additional non-default policy.",
            "RF-DETR disables multi_scale/scale_jitter to keep training inputs at 640; those are research overrides.",
            "Research patience=50 does not equalize upstream min_delta or checkpoint selection semantics."]
        if not is_rf:
            spec["constraint_caveats"][0] = "Nominal batch16 uses fixed accumulation; partial epoch tails have fewer real examples with explicit16/actual loss rescaling. This is a research deviation from upstream's accumulation warmup/carry behavior."
            spec["augmentation"]["mosaic"] = 0.0
            spec.update(training_status="runnable_sensor_research_integration", blockers=[])
            spec["sensor_research_deviations"] = [
                "Fixed nominal accumulation16, no accumulation warmup ramp; epoch tail raw loss is multiplied by16/actual_examples and flushed.",
                "Four float sensor channels with masked interpolation and zero missing-signal padding replace uint8 RGB/114 padding and HSV; synchronized scale=.5 and translate=.1 affine geometry plus fliplr=.5; no pilot modality perturbations.",
                "Project original-coordinate AP50_95 selects EMA checkpoints; strict improvement and patience50 use project selection, not upstream fitness/tie behavior.",
                "Single device, project float normalization and model adapters; no upstream OOM batch reduction, distributed trainer, RGB AMP eligibility probe or callbacks.",
                "Checkpoints store FP32 EMA, full optimizer/scaler/RNG and YOLO26 criterion update count; EMA updates only on successful optimizer steps."]
            spec["schedule"]["accumulation"] = "fixed16_epoch_tail_rescale"
            spec["augmentation"].update(hsv_h=0., hsv_s=0., hsv_v=0.,
                                         implementation="sensor_float_spatial_v1")
            spec["project_integration_sources"] = [
                {"file": f"pallet/experiments/{name}",
                 "sha256": hashlib.sha256(Path(__file__).with_name(name).read_bytes()).hexdigest()}
                for name in ("train.py", "yolo_recipe.py", "dataset.py")]
        else:
            spec["augmentation"].update(multi_scale="off", expanded_scales=False, scale_jitter=False)
            spec.update(training_status="runnable_sensor_research_integration", blockers=[])
            spec["constraint_caveats"][0] = "RF detection loss uses its native per-microbatch box normalization; the loop weights each microbatch mean by its real examples over the accumulation window and flushes epoch tails."
            spec["sensor_research_deviations"] = [
                "Fixed sensor letterbox with supported float/mask interpolation replaces RF square resize, random resize/crop and RGB normalization; native horizontal flip probability .5 is synchronized with boxes and masks.",
                "Scale jitter and expanded multi-scale are disabled for fixed640; one-device effective16 accumulation uses actual-example weighted epoch tails, a named deviation from Lightning's fixed divisor on partial windows.",
                "Project original-coordinate AP50_95 selects EMA strict improvement, unlike RF's separate regular/EMA tracks, smoothing/skip epochs, min_delta and checkpoint metric policy.",
                "Official AveragedModel callback buffers/counter, step scheduler, grouping, fused eligibility, precision choice and clip norm .1 are used; model sensor adapter adds base-lr/decay group.",
                "CUDA deformable-attention training is numerically nondeterministic across identical seeds in this environment; RNG/scheduler/optimizer/EMA resume state is preserved, but bit-exact GPU weights cannot be guaranteed.",
                "ONNX export supports checkpoint loading but RF near-tied query ordering in missing-mask probes can fail strict parity; report parity case explicitly."]
            spec["schedule"]["accumulation"] = "fixed16_actual_example_mean_epoch_tail"
            spec["augmentation"].update(implementation="rf_sensor_float_flip_v1",
                                         native_resize_crop=False,
                                         synchronized_sensor_flip_probability=.5)
            spec["project_integration_sources"] = [
                {"file": f"pallet/experiments/{name}",
                 "sha256": hashlib.sha256(Path(__file__).with_name(name).read_bytes()).hexdigest()}
                for name in ("train.py", "rfdetr_recipe.py", "dataset.py")]
    if recipe == "project_adamw_pilot":
        spec.update(training_status="runnable_existing_train_py",
                    optimizer_preparation_status="existing_train_py",
                    optimizer={"name": "AdamW", "lr": 0.0001 if is_rf else 0.001,
                               "weight_decay": 0.0005, "betas": [0.9, 0.999],
                               "groups": "all model parameters in one group; no encoder or bias/norm policy"},
                    schedule={"name": "project_optimizer_step_warmup_cosine", "warmup_epochs": 3,
                              "warmup_start_factor": 0.1, "min_lr_ratio": 0.01},
                    ema={"enabled": False},
                    augmentation={"implementation": "PalletDataset augmentation", "mosaic": False},
                    blockers=[], pilot_defaults={"size": 640, "batch_size": 4, "effective_batch": 16,
                                               "epochs": 300, "patience": 50})
        spec["project_source"] = {"file": "pallet/experiments/train.py",
            "sha256": hashlib.sha256(Path(__file__).with_name("train.py").read_bytes()).hexdigest()}
    return spec


def validate_parameter_coverage(model, groups, *, trainable_only=True):
    """Reject missing, duplicated or foreign parameters; return named group report."""
    expected = {id(p): n for n, p in model.named_parameters() if p.requires_grad or not trainable_only}
    seen = set()
    report = []
    for group in groups:
        names = []
        for p in group["params"]:
            key = id(p)
            if key not in expected:
                raise ValueError("optimizer has foreign or frozen parameter")
            if key in seen:
                raise ValueError(f"duplicate optimizer parameter: {expected[key]}")
            seen.add(key)
            names.append(expected[key])
        report.append({**{k: v for k, v in group.items() if k != "params"}, "parameter_names": names})
    missing = [name for key, name in expected.items() if key not in seen]
    if missing:
        raise ValueError(f"optimizer missing parameters: {', '.join(missing)}")
    if not expected:
        raise ValueError("model has no parameters to optimize")
    return report


def build_ultralytics_optimizer(model, *, num_train_samples, epochs, batch_size=4,
                                nbs=16, nc=1, weight_decay=0.0005):
    """Use upstream builder verbatim; model must support upstream MuSGD head access.

    This prepares an optimizer only. It does not implement upstream trainer semantics.
    """
    resolved = resolve_ultralytics_auto(num_train_samples=num_train_samples, epochs=epochs,
                                        batch_size=batch_size, nbs=nbs, nc=nc)
    if not math.isfinite(weight_decay) or weight_decay < 0:
        raise ValueError("weight_decay must be finite and nonnegative")
    from ultralytics.engine.trainer import BaseTrainer
    context = SimpleNamespace(args=SimpleNamespace(lr0=0.01, momentum=0.937,
                                                   warmup_bias_lr=0.1), data={"nc": nc})
    decay = weight_decay * batch_size * max(round(nbs / batch_size), 1) / nbs
    # PalletDetector owns a DetectionModel at .yolo; expose its head through
    # upstream's student_model access without registering duplicate parameters.
    class OptimizerView(torch.nn.Module):
        def __init__(self, detector):
            super().__init__()
            self.detector = detector

        @property
        def student_model(self):
            return self.detector.yolo

    target = OptimizerView(model) if hasattr(model, "yolo") else model
    optimizer = BaseTrainer.build_optimizer(context, target, name="auto", decay=decay,
                                           iterations=resolved["iterations"])
    validate_parameter_coverage(model, optimizer.param_groups, trainable_only=False)
    return optimizer


def build_rfdetr_param_groups(model, *, core_model=None, out_feature_indexes=None,
                              allow_adapter_parameters=False, lr=1e-4, lr_encoder=1.5e-4,
                              lr_component_decay=0.7, lr_vit_layer_decay=0.8, weight_decay=1e-4):
    """Delegate core grouping to RF-DETR; explicit adapter extension uses base LR/WD.

    For a project wrapper, pass core_model=model.model. Missing wrapper parameters
    fail by default. Opting into adapter coverage is a declared research extension,
    not a claim that the sensor adapter exists in upstream's model recipe.
    """
    _source("rfdetr", "training/param_groups.py")
    for name, value in {"lr": lr, "lr_encoder": lr_encoder,
                        "lr_component_decay": lr_component_decay, "lr_vit_layer_decay": lr_vit_layer_decay,
                        "weight_decay": weight_decay}.items():
        if not math.isfinite(value) or value < 0 or (name != "weight_decay" and value == 0):
            raise ValueError(f"{name} must be finite and {'nonnegative' if name == 'weight_decay' else 'positive'}")
    if out_feature_indexes is None:
        config = getattr(model, "model_config", None)
        out_feature_indexes = getattr(config, "out_feature_indexes", None)
    if not out_feature_indexes or any(isinstance(i, bool) or not isinstance(i, int) or i < 0 for i in out_feature_indexes):
        raise ValueError("out_feature_indexes must contain nonnegative integer layer indices")
    if list(out_feature_indexes) != sorted(set(out_feature_indexes)):
        raise ValueError("out_feature_indexes must be strictly increasing")
    core = model if core_model is None else core_model
    # Load the pure official grouping source directly. This helper can then be
    # used independently of Lightning's trainer lifecycle or side effects.
    package = Path(importlib.util.find_spec("rfdetr").origin).parent
    module_spec = importlib.util.spec_from_file_location(
        "_pallet_official_rfdetr_param_groups", package / "training/param_groups.py")
    official_module = importlib.util.module_from_spec(module_spec)
    module_spec.loader.exec_module(official_module)
    args = SimpleNamespace(lr=lr, lr_encoder=lr_encoder, lr_component_decay=lr_component_decay,
                           lr_vit_layer_decay=lr_vit_layer_decay, weight_decay=weight_decay,
                           out_feature_indexes=list(out_feature_indexes))
    groups = official_module.get_param_dict(args, core)
    validate_parameter_coverage(core, groups)
    covered = {id(p) for group in groups for p in group["params"]}
    adapters = [p for p in model.parameters() if p.requires_grad and id(p) not in covered]
    if adapters and allow_adapter_parameters:
        groups.append({"params": adapters, "lr": lr, "weight_decay": weight_decay,
                       "recipe_extension": "sensor_adapter_base_lr_weight_decay"})
    validate_parameter_coverage(model, groups)
    return groups


def build_rfdetr_optimizer(model, *, fused=False, **group_kwargs):
    """Construct official default AdamW numerics; caller explicitly chooses fused.

    Runtime fused eligibility, EMA and scheduler remain trainer responsibilities.
    """
    groups = build_rfdetr_param_groups(model, **group_kwargs)
    return torch.optim.AdamW(groups, lr=group_kwargs.get("lr", 1e-4),
                             weight_decay=group_kwargs.get("weight_decay", 1e-4), fused=fused)
