// The model-recommendations contract: one static JSON file
// (shared/model-recommendations.json) carrying every model config we have actually
// tested, on every hardware class we have data for, with the exact startup commands
// used. The download/setup UIs read this to show only pareto-frontier picks that fit
// the user's rig instead of a generic catalog.
//
// Keyed by Hugging Face repo id. "Tested" is the bar for inclusion: an entry's
// commands and speeds come from a real run recorded in the local.ai benchmark data,
// not from estimates. Estimated entries are allowed but must say so via
// `benchmarks: []` + `expectSpeed.source: "estimated"`.

export type QuantKind =
  | "nvfp4"
  | "fp8"
  | "awq"
  | "gptq"
  | "gguf"
  | "exl3"
  | "mlx"
  | "mixed-bit"
  | "bf16";

export type RecommendationEngine = "vllm" | "sglang" | "llamacpp" | "mlx" | "exllamav3";

/** A hardware class an entry is known to run on. Matching is by memory pool first
 *  (VRAM, or unified RAM on Apple/Spark) with named-GPU hints for the UI. */
export interface HardwareTarget {
  /** e.g. "rtx-pro-6000-x4", "rtx-4090", "m1-max-32gb", "dgx-spark" */
  readonly id: string;
  readonly label: string;
  /** Minimum memory pool that ran this config, in GB. */
  readonly minMemoryGb: number;
  readonly gpuCount: number;
  readonly unifiedMemory: boolean;
  /** True when this exact hardware ran the config; false = derived headroom match. */
  readonly tested: boolean;
}

export interface BenchmarkRecord {
  readonly hardwareId: string;
  readonly engine: RecommendationEngine;
  readonly decodeTps: number | null;
  readonly prefillTps: number | null;
  readonly ttftMs: number | null;
  readonly contextTokens: number | null;
  /** ISO date of the measurement run. */
  readonly measuredAt: string | null;
  readonly notes: string | null;
}

export interface ExpectedSpeed {
  readonly decodeTps: number | null;
  readonly prefillTps: number | null;
  readonly source: "measured" | "estimated";
}

export interface ModelRecommendation {
  readonly name: string;
  readonly quant: QuantKind;
  /** Human-facing size of the weights on disk, e.g. "32gb". */
  readonly filesize: string;
  readonly filesizeGb: number;
  readonly hardware: readonly HardwareTarget[];
  /** Exact startup command per engine, as tested. Absent engine = not tested. */
  readonly commands: Readonly<Partial<Record<RecommendationEngine, string>>>;
  /** Pareto rank within its memory class: 1 = best quality/speed tradeoff. */
  readonly rank: number;
  readonly benchmarks: readonly BenchmarkRecord[];
  readonly expectSpeed: ExpectedSpeed;
  /** Optional context: params ("235B-A22B"), license, multimodal, notes. */
  readonly params: string | null;
  readonly notes: readonly string[];
}

/** Keyed by Hugging Face repo id, e.g. "zai-org/GLM-5.2-FP8". */
export type ModelRecommendations = Readonly<Record<string, ModelRecommendation>>;

export interface ModelRecommendationsFile {
  readonly version: number;
  readonly updated: string;
  readonly models: ModelRecommendations;
}

/* ── matching ────────────────────────────────────────────────────────────── */

export interface RigDescriptor {
  /** Total usable memory pool in GB: sum of VRAM, or RAM on unified hosts. */
  readonly memoryPoolGb: number;
  readonly gpuCount: number;
  readonly unifiedMemory: boolean;
  readonly appleSilicon: boolean;
}

/** The user's sizing rule: a config is offered when the rig has the file size plus
 *  50% headroom (weights + KV cache + activations margin). */
export const requiredPoolGb = (recommendation: ModelRecommendation): number =>
  Math.ceil(recommendation.filesizeGb * 1.5);

export const fitsRig = (recommendation: ModelRecommendation, rig: RigDescriptor): boolean => {
  if (rig.memoryPoolGb < requiredPoolGb(recommendation)) return false;
  // Apple rigs can only run quants with an mlx or llama.cpp command.
  if (rig.appleSilicon) {
    return Boolean(recommendation.commands.mlx ?? recommendation.commands.llamacpp);
  }
  return true;
};

export interface RankedRecommendation extends ModelRecommendation {
  readonly hfId: string;
  /** True when a benchmark exists for hardware matching this rig's class. */
  readonly measuredOnThisClass: boolean;
}

/** Pareto picks for a rig: everything that fits, best rank first, measured configs
 *  before estimated ones at equal rank. */
export const recommendationsForRig = (
  file: ModelRecommendationsFile,
  rig: RigDescriptor,
): readonly RankedRecommendation[] =>
  Object.entries(file.models)
    .filter(([, model]) => fitsRig(model, rig))
    .map(([hfId, model]) => ({
      ...model,
      hfId,
      measuredOnThisClass: model.hardware.some(
        (target) => target.tested && rig.memoryPoolGb >= target.minMemoryGb,
      ),
    }))
    .sort(
      (left, right) =>
        left.rank - right.rank ||
        Number(right.measuredOnThisClass) - Number(left.measuredOnThisClass) ||
        right.filesizeGb - left.filesizeGb,
    );