Skip to content

Personal AI, On Personal Devices

Python
40.0 KB
Raw Blame
"""Built-in model catalog with well-known ModelSpec entries."""

from __future__ import annotations

from typing import List

from openjarvis.core.registry import ModelRegistry
from openjarvis.core.types import ModelSpec, Quantization

BUILTIN_MODELS: List[ModelSpec] = [
    # -----------------------------------------------------------------------
    # Local models — Dense
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="qwen3:0.6b",
        name="Qwen3 0.6B",
        parameter_count_b=0.6,
        context_length=40960,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx", "lemonade"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-0.6B",
        },
    ),
    ModelSpec(
        model_id="qwen3:1.7b",
        name="Qwen3 1.7B",
        parameter_count_b=1.7,
        context_length=40960,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx", "lemonade"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-1.7B",
        },
    ),
    ModelSpec(
        model_id="qwen3:4b",
        name="Qwen3 4B",
        parameter_count_b=4.0,
        context_length=262144,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx", "lemonade"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-4B",
        },
    ),
    ModelSpec(
        model_id="qwen3:8b",
        name="Qwen3 8B",
        parameter_count_b=8.2,
        context_length=32768,
        supported_engines=("vllm", "ollama", "llamacpp", "sglang", "mlx", "lemonade"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-8B",
        },
    ),
    ModelSpec(
        model_id="qwen3:14b",
        name="Qwen3 14B",
        parameter_count_b=14.0,
        context_length=40960,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "lemonade"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-14B",
        },
    ),
    ModelSpec(
        model_id="qwen3:30b",
        name="Qwen3 30B",
        parameter_count_b=30.0,
        context_length=262144,
        min_vram_gb=18.0,
        supported_engines=("ollama", "vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-30B",
        },
    ),
    ModelSpec(
        model_id="qwen3:32b",
        name="Qwen3 32B",
        parameter_count_b=32.0,
        context_length=32768,
        min_vram_gb=20.0,
        supported_engines=("ollama", "vllm"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3-32B",
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — Qwen3.5 (dense and MoE)
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="qwen3.5:0.8b",
        name="Qwen3.5 0.8B",
        parameter_count_b=0.8,
        context_length=131072,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3.5-0.8B",
            "mlx_repo": "mlx-community/Qwen3.5-0.8B-OptiQ-4bit",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:2b",
        name="Qwen3.5 2B",
        parameter_count_b=2.0,
        context_length=131072,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3.5-2B",
            "mlx_repo": "mlx-community/Qwen3.5-2B-OptiQ-4bit",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:9b",
        name="Qwen3.5 9B",
        parameter_count_b=9.0,
        context_length=131072,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3.5-9B",
            "gguf_file": "qwen3.5-9b-q4_k_m.gguf",
            "mlx_repo": "mlx-community/Qwen3.5-9B-MLX-4bit",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:27b",
        name="Qwen3.5 27B",
        parameter_count_b=27.0,
        context_length=131072,
        min_vram_gb=16.0,
        supported_engines=("ollama", "vllm", "llamacpp", "sglang", "mlx"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3.5-27B",
            "gguf_file": "qwen3.5-27b-q4_k_m.gguf",
            "mlx_repo": "mlx-community/Qwen3.5-27B-4bit-DWQ",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:35b",
        name="Qwen3.5 35B",
        parameter_count_b=35.0,
        active_parameter_count_b=3.0,
        context_length=131072,
        supported_engines=("ollama", "vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "moe",
            "hf_repo": "Qwen/Qwen3.5-35B",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:122b",
        name="Qwen3.5 122B",
        parameter_count_b=122.0,
        active_parameter_count_b=10.0,
        context_length=131072,
        min_vram_gb=70.0,
        supported_engines=("ollama", "vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "moe",
            "hf_repo": "Qwen/Qwen3.5-122B",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:397b",
        name="Qwen3.5 397B",
        parameter_count_b=397.0,
        active_parameter_count_b=17.0,
        context_length=131072,
        min_vram_gb=220.0,
        supported_engines=("vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "moe",
            "hf_repo": "Qwen/Qwen3.5-397B",
        },
    ),
    ModelSpec(
        model_id="llama3.3:70b",
        name="Llama 3.3 70B",
        parameter_count_b=70.0,
        context_length=131072,
        min_vram_gb=40.0,
        supported_engines=("ollama", "vllm"),
        provider="meta",
        metadata={
            "architecture": "dense",
            "hf_repo": "meta-llama/Llama-3.3-70B-Instruct",
        },
    ),
    ModelSpec(
        model_id="llama3.2:3b",
        name="Llama 3.2 3B",
        parameter_count_b=3.0,
        context_length=131072,
        supported_engines=("ollama", "vllm", "llamacpp"),
        provider="meta",
        metadata={
            "architecture": "dense",
            "hf_repo": "meta-llama/Llama-3.2-3B-Instruct",
        },
    ),
    ModelSpec(
        model_id="deepseek-coder-v2:16b",
        name="DeepSeek Coder V2 16B",
        parameter_count_b=16.0,
        context_length=131072,
        supported_engines=("ollama", "vllm"),
        provider="deepseek",
        metadata={
            "architecture": "dense",
            "hf_repo": "deepseek-ai/DeepSeek-Coder-V2-Lite-Instruct",
        },
    ),
    ModelSpec(
        model_id="mistral:7b",
        name="Mistral 7B",
        parameter_count_b=7.0,
        context_length=32768,
        supported_engines=("ollama", "vllm", "llamacpp"),
        provider="mistral",
        metadata={
            "architecture": "dense",
            "hf_repo": "mistralai/Mistral-7B-Instruct-v0.3",
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — Mixture of Experts (MoE)
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="gpt-oss:120b",
        name="GPT-OSS 120B",
        parameter_count_b=117.0,
        active_parameter_count_b=5.1,
        context_length=131072,
        min_vram_gb=12.0,
        supported_engines=("vllm", "ollama"),
        provider="open-source",
        metadata={
            "architecture": "moe",
            "hf_repo": "OpenBuddy/GPT-OSS-120B",
        },
    ),
    ModelSpec(
        model_id="glm-4.7-flash",
        name="GLM 4.7 Flash",
        parameter_count_b=30.0,
        active_parameter_count_b=3.0,
        context_length=131072,
        min_vram_gb=8.0,
        supported_engines=("vllm", "sglang", "llamacpp"),
        provider="zhipu",
        metadata={
            "architecture": "moe",
            "hf_repo": "THUDM/GLM-4.7-Flash-Chat",
        },
    ),
    ModelSpec(
        model_id="trinity-mini",
        name="Trinity Mini",
        parameter_count_b=26.0,
        active_parameter_count_b=3.0,
        context_length=128000,
        min_vram_gb=8.0,
        supported_engines=("vllm", "llamacpp"),
        provider="trinity",
        metadata={
            "architecture": "moe",
            "hf_repo": "TrinityAI/Trinity-Mini-26B",
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — Qwen3.5 (4B dense, plus MoE variants)
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="qwen3.5:4b",
        name="Qwen3.5 4B",
        parameter_count_b=4.0,
        context_length=262144,
        min_vram_gb=3.0,
        supported_engines=("ollama", "vllm", "sglang", "llamacpp", "mlx"),
        provider="alibaba",
        metadata={
            "architecture": "dense",
            "hf_repo": "Qwen/Qwen3.5-4B",
            "gguf_file": "qwen3.5-4b-q4_k_m.gguf",
            "mlx_repo": "mlx-community/Qwen3.5-4B-OptiQ-4bit",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:35b-a3b",
        name="Qwen3.5 35B A3B",
        parameter_count_b=35.0,
        active_parameter_count_b=3.0,
        context_length=262144,
        min_vram_gb=8.0,
        supported_engines=("ollama", "vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "moe",
            "hf_repo": "Qwen/Qwen3.5-35B-A3B",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:122b-a10b",
        name="Qwen3.5 122B A10B",
        parameter_count_b=122.0,
        active_parameter_count_b=10.0,
        context_length=262144,
        min_vram_gb=20.0,
        supported_engines=("vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "moe",
            "hf_repo": "Qwen/Qwen3.5-122B-A10B",
        },
    ),
    ModelSpec(
        model_id="qwen3.5:397b-a17b",
        name="Qwen3.5 397B A17B",
        parameter_count_b=397.0,
        active_parameter_count_b=17.0,
        context_length=262144,
        min_vram_gb=50.0,
        supported_engines=("vllm", "sglang"),
        provider="alibaba",
        metadata={
            "architecture": "moe",
            "hf_repo": "Qwen/Qwen3.5-397B-A17B",
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — Unsloth GGUF Quantizations
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="unsloth/Qwen3.5-35B-A3B-GGUF",
        name="Qwen3.5 35B A3B (Unsloth GGUF)",
        parameter_count_b=35.0,
        active_parameter_count_b=3.0,
        context_length=262144,
        min_vram_gb=6.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/Qwen3.5-35B-A3B-GGUF",
            "base_model": "Qwen/Qwen3.5-35B-A3B",
        },
    ),
    ModelSpec(
        model_id="unsloth/Qwen3.5-122B-A10B-GGUF",
        name="Qwen3.5 122B A10B (Unsloth GGUF)",
        parameter_count_b=122.0,
        active_parameter_count_b=10.0,
        context_length=262144,
        min_vram_gb=16.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/Qwen3.5-122B-A10B-GGUF",
            "base_model": "Qwen/Qwen3.5-122B-A10B",
        },
    ),
    ModelSpec(
        model_id="unsloth/Qwen3.5-397B-A17B-GGUF",
        name="Qwen3.5 397B A17B (Unsloth GGUF)",
        parameter_count_b=397.0,
        active_parameter_count_b=17.0,
        context_length=262144,
        min_vram_gb=40.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/Qwen3.5-397B-A17B-GGUF",
            "base_model": "Qwen/Qwen3.5-397B-A17B",
        },
    ),
    ModelSpec(
        model_id="unsloth/GLM-5-GGUF",
        name="GLM-5 (Unsloth GGUF)",
        parameter_count_b=100.0,
        context_length=131072,
        min_vram_gb=12.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "dense",
            "hf_repo": "unsloth/GLM-5-GGUF",
            "base_model": "THUDM/GLM-5",
        },
    ),
    ModelSpec(
        model_id="unsloth/GLM-4.7-Flash-GGUF",
        name="GLM 4.7 Flash (Unsloth GGUF)",
        parameter_count_b=30.0,
        active_parameter_count_b=3.0,
        context_length=131072,
        min_vram_gb=6.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/GLM-4.7-Flash-GGUF",
            "base_model": "THUDM/GLM-4.7-Flash-Chat",
        },
    ),
    ModelSpec(
        model_id="unsloth/Qwen3-Coder-Next-GGUF",
        name="Qwen3 Coder Next (Unsloth GGUF)",
        parameter_count_b=80.0,
        context_length=131072,
        min_vram_gb=12.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/Qwen3-Coder-Next-GGUF",
            "base_model": "Qwen/Qwen3-Coder-Next",
        },
    ),
    ModelSpec(
        model_id="unsloth/MiniMax-M2.5-GGUF",
        name="MiniMax M2.5 (Unsloth GGUF)",
        parameter_count_b=229.0,
        context_length=131072,
        min_vram_gb=30.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/MiniMax-M2.5-GGUF",
            "base_model": "MiniMax/MiniMax-M2.5",
        },
    ),
    ModelSpec(
        model_id="unsloth/Kimi-K2.5-GGUF",
        name="Kimi K2.5 (Unsloth GGUF)",
        parameter_count_b=1000.0,
        active_parameter_count_b=32.0,
        context_length=131072,
        min_vram_gb=40.0,
        quantization=Quantization.GGUF,
        supported_engines=("ollama", "llamacpp"),
        provider="unsloth",
        metadata={
            "architecture": "moe",
            "hf_repo": "unsloth/Kimi-K2.5-GGUF",
            "base_model": "moonshotai/Kimi-K2.5",
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — LiquidAI LFM2.5 (Hybrid SSM+Transformer)
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="LiquidAI/LFM2.5-1.2B-Instruct-GGUF",
        name="LFM2.5 1.2B Instruct (GGUF)",
        parameter_count_b=1.2,
        context_length=32768,
        min_vram_gb=1.0,
        quantization=Quantization.GGUF,
        supported_engines=("llamacpp", "ollama"),
        provider="liquidai",
        metadata={
            "architecture": "hybrid_ssm_transformer",
            "hf_repo": "LiquidAI/LFM2.5-1.2B-Instruct-GGUF",
            "layers": "10 LIV convolution + 6 GQA",
            "languages": 8,
        },
    ),
    ModelSpec(
        model_id="LiquidAI/LFM2.5-1.2B-Instruct-MLX",
        name="LFM2.5 1.2B Instruct (MLX)",
        parameter_count_b=1.2,
        context_length=32768,
        min_vram_gb=1.0,
        supported_engines=("mlx",),
        provider="liquidai",
        metadata={
            "architecture": "hybrid_ssm_transformer",
            "hf_repo": "LiquidAI/LFM2.5-1.2B-Instruct-MLX",
            "layers": "10 LIV convolution + 6 GQA",
            "languages": 8,
        },
    ),
    ModelSpec(
        model_id="LiquidAI/LFM2.5-1.2B-Thinking-GGUF",
        name="LFM2.5 1.2B Thinking (GGUF)",
        parameter_count_b=1.2,
        context_length=32768,
        min_vram_gb=1.0,
        quantization=Quantization.GGUF,
        supported_engines=("llamacpp", "ollama"),
        provider="liquidai",
        metadata={
            "architecture": "hybrid_ssm_transformer",
            "hf_repo": "LiquidAI/LFM2.5-1.2B-Thinking-GGUF",
            "layers": "10 LIV convolution + 6 GQA",
            "variant": "reasoning-optimized",
            "languages": 8,
        },
    ),
    ModelSpec(
        model_id="LiquidAI/LFM2.5-1.2B-Thinking-MLX",
        name="LFM2.5 1.2B Thinking (MLX)",
        parameter_count_b=1.2,
        context_length=32768,
        min_vram_gb=1.0,
        supported_engines=("mlx",),
        provider="liquidai",
        metadata={
            "architecture": "hybrid_ssm_transformer",
            "hf_repo": "LiquidAI/LFM2.5-1.2B-Thinking-MLX",
            "layers": "10 LIV convolution + 6 GQA",
            "variant": "reasoning-optimized",
            "languages": 8,
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — TeichAI Distilled
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="teichai/glm-4.7-flash-opus-distill",
        name="GLM 4.7 Flash Claude Opus 4.5 Distill",
        parameter_count_b=30.0,
        active_parameter_count_b=3.0,
        context_length=131072,
        min_vram_gb=8.0,
        supported_engines=("vllm", "llamacpp"),
        provider="teichai",
        metadata={
            "architecture": "moe",
            "hf_repo": (
                "TeichAI/GLM-4.7-Flash-Claude-Opus-4.5-High-Reasoning-Distill-GGUF"
            ),
            "teacher": "Claude Opus 4.5",
            "quantization": "GGUF Q4_K_M / Q8_0",
            "license": "apache-2.0",
        },
    ),
    ModelSpec(
        model_id="teichai/qwen3-14b-gpt5.2-distill",
        name="Qwen3 14B GPT-5.2 Distill",
        parameter_count_b=14.8,
        context_length=32768,
        min_vram_gb=10.0,
        supported_engines=("vllm", "llamacpp"),
        provider="teichai",
        metadata={
            "architecture": "dense",
            "hf_repo": "TeichAI/Qwen3-14B-GPT-5.2-Distill-GGUF",
            "teacher": "GPT-5.2",
            "quantization": "GGUF Q4_K_M / Q8_0",
            "license": "apache-2.0",
        },
    ),
    ModelSpec(
        model_id="teichai/nemotron-14b-opus-distill",
        name="Nemotron Cascade 14B Claude Opus Distill",
        parameter_count_b=14.8,
        context_length=32768,
        min_vram_gb=10.0,
        supported_engines=("vllm", "llamacpp"),
        provider="teichai",
        metadata={
            "architecture": "dense",
            "hf_repo": "TeichAI/Nemotron-Cascade-14B-Claude-Opus-Distill-GGUF",
            "teacher": "Claude 4.5 Opus",
            "quantization": "GGUF Q4_K_M / Q8_0",
            "license": "apache-2.0",
        },
    ),
    # -----------------------------------------------------------------------
    # Local models — IBM Granite
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="granite3.3:8b",
        name="Granite 3.3 8B",
        parameter_count_b=8.0,
        context_length=128000,
        supported_engines=("ollama", "vllm", "llamacpp"),
        provider="ibm",
        metadata={
            "architecture": "dense",
            "hf_repo": "ibm-granite/granite-3.3-8b-instruct",
            "url": "https://www.ibm.com/granite",
        },
    ),
    ModelSpec(
        model_id="granite4.0-micro",
        name="Granite 4.0 Micro 3B",
        parameter_count_b=3.0,
        context_length=128000,
        supported_engines=("ollama", "vllm", "llamacpp"),
        provider="ibm",
        metadata={
            "architecture": "dense",
            "hf_repo": "ibm-granite/granite-4.0-micro",
            "url": "https://www.ibm.com/granite",
        },
    ),
    ModelSpec(
        model_id="granite4.0-h-small",
        name="Granite 4.0 H Small 32B",
        parameter_count_b=32.0,
        active_parameter_count_b=9.0,
        context_length=128000,
        supported_engines=("ollama", "vllm"),
        provider="ibm",
        metadata={
            "architecture": "moe",
            "hf_repo": "ibm-granite/granite-4.0-h-small",
            "url": "https://www.ibm.com/granite",
        },
    ),
    # -----------------------------------------------------------------------
    # Cloud models — OpenAI
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="gpt-4o",
        name="GPT-4o",
        parameter_count_b=0.0,
        context_length=128000,
        supported_engines=("cloud",),
        provider="openai",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 2.50,
            "pricing_output": 10.00,
            "url": "https://platform.openai.com/docs/models/gpt-4o",
        },
    ),
    ModelSpec(
        model_id="gpt-4o-mini",
        name="GPT-4o Mini",
        parameter_count_b=0.0,
        context_length=128000,
        supported_engines=("cloud",),
        provider="openai",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.15,
            "pricing_output": 0.60,
            "url": "https://platform.openai.com/docs/models/gpt-4o-mini",
        },
    ),
    ModelSpec(
        model_id="gpt-5-mini",
        name="GPT-5 Mini",
        parameter_count_b=0.0,
        context_length=400000,
        supported_engines=("cloud",),
        provider="openai",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.25,
            "pricing_output": 2.00,
            "url": "https://platform.openai.com/docs/models",
        },
    ),
    ModelSpec(
        model_id="gpt-5-mini-2025-08-07",
        name="GPT-5 Mini (2025-08-07)",
        parameter_count_b=0.0,
        context_length=400000,
        supported_engines=("cloud",),
        provider="openai",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.25,
            "pricing_output": 2.00,
            "url": "https://platform.openai.com/docs/models",
        },
    ),
    # -----------------------------------------------------------------------
    # Cloud models — OpenAI Codex (ChatGPT Plus/Pro subscription)
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="codex/gpt-4o",
        name="GPT-4o (Codex)",
        parameter_count_b=0.0,
        context_length=128000,
        supported_engines=("cloud",),
        provider="openai-codex",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "auth": "OPENAI_CODEX_API_KEY",
            "pricing_input": 0.0,
            "pricing_output": 0.0,
            "url": "https://platform.openai.com/docs/models/gpt-4o",
        },
    ),
    ModelSpec(
        model_id="codex/gpt-4o-mini",
        name="GPT-4o Mini (Codex)",
        parameter_count_b=0.0,
        context_length=128000,
        supported_engines=("cloud",),
        provider="openai-codex",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "auth": "OPENAI_CODEX_API_KEY",
            "pricing_input": 0.0,
            "pricing_output": 0.0,
            "url": "https://platform.openai.com/docs/models/gpt-4o-mini",
        },
    ),
    ModelSpec(
        model_id="codex/o3-mini",
        name="o3-mini (Codex)",
        parameter_count_b=0.0,
        context_length=200000,
        supported_engines=("cloud",),
        provider="openai-codex",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "auth": "OPENAI_CODEX_API_KEY",
            "pricing_input": 0.0,
            "pricing_output": 0.0,
            "url": "https://platform.openai.com/docs/models",
        },
    ),
    ModelSpec(
        model_id="codex/gpt-5-mini",
        name="GPT-5 Mini (Codex)",
        parameter_count_b=0.0,
        context_length=400000,
        supported_engines=("cloud",),
        provider="openai-codex",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "auth": "OPENAI_CODEX_API_KEY",
            "pricing_input": 0.0,
            "pricing_output": 0.0,
            "url": "https://platform.openai.com/docs/models",
        },
    ),
    ModelSpec(
        model_id="codex/gpt-5-mini-2025-08-07",
        name="GPT-5 Mini 2025-08-07 (Codex)",
        parameter_count_b=0.0,
        context_length=400000,
        supported_engines=("cloud",),
        provider="openai-codex",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "auth": "OPENAI_CODEX_API_KEY",
            "pricing_input": 0.0,
            "pricing_output": 0.0,
            "url": "https://platform.openai.com/docs/models",
        },
    ),
    # -----------------------------------------------------------------------
    # Cloud models — Anthropic
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="claude-sonnet-4-20250514",
        name="Claude Sonnet 4",
        parameter_count_b=0.0,
        context_length=200000,
        supported_engines=("cloud",),
        provider="anthropic",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 3.00,
            "pricing_output": 15.00,
            "url": "https://docs.anthropic.com/en/docs/about-claude/models",
        },
    ),
    ModelSpec(
        model_id="claude-opus-4-20250514",
        name="Claude Opus 4",
        parameter_count_b=0.0,
        context_length=200000,
        supported_engines=("cloud",),
        provider="anthropic",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 15.00,
            "pricing_output": 75.00,
            "url": "https://docs.anthropic.com/en/docs/about-claude/models",
        },
    ),
    ModelSpec(
        model_id="claude-opus-4-6",
        name="Claude Opus 4.6",
        parameter_count_b=0.0,
        context_length=200000,
        supported_engines=("cloud",),
        provider="anthropic",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 5.00,
            "pricing_output": 25.00,
            "url": "https://docs.anthropic.com/en/docs/about-claude/models",
        },
    ),
    ModelSpec(
        model_id="claude-sonnet-4-6",
        name="Claude Sonnet 4.6",
        parameter_count_b=0.0,
        context_length=200000,
        supported_engines=("cloud",),
        provider="anthropic",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 3.00,
            "pricing_output": 15.00,
            "url": "https://docs.anthropic.com/en/docs/about-claude/models",
        },
    ),
    ModelSpec(
        model_id="claude-haiku-4-5",
        name="Claude Haiku 4.5",
        parameter_count_b=0.0,
        context_length=200000,
        supported_engines=("cloud",),
        provider="anthropic",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 1.00,
            "pricing_output": 5.00,
            "url": "https://docs.anthropic.com/en/docs/about-claude/models",
        },
    ),
    # -----------------------------------------------------------------------
    # Cloud models — MiniMax
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="MiniMax-M3",
        name="MiniMax M3",
        parameter_count_b=0.0,
        context_length=1_000_000,
        supported_engines=("cloud",),
        provider="minimax",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.30,
            "pricing_output": 1.20,
            "pricing_long_context_input": 0.60,
            "pricing_long_context_output": 2.40,
            "pricing_long_context_threshold": 512_000,
            "url": "https://platform.minimax.io/docs/api-reference/api-overview",
        },
    ),
    ModelSpec(
        model_id="MiniMax-M2.7",
        name="MiniMax M2.7",
        parameter_count_b=0.0,
        context_length=204_800,
        supported_engines=("cloud",),
        provider="minimax",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.30,
            "pricing_output": 1.20,
            "url": "https://platform.minimax.io/docs/api-reference/api-overview",
        },
    ),
    ModelSpec(
        model_id="MiniMax-M2.7-highspeed",
        name="MiniMax M2.7 Highspeed",
        parameter_count_b=0.0,
        context_length=204_800,
        supported_engines=("cloud",),
        provider="minimax",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.60,
            "pricing_output": 2.40,
            "url": "https://platform.minimax.io/docs/api-reference/api-overview",
        },
    ),
    ModelSpec(
        model_id="MiniMax-M2.5",
        name="MiniMax M2.5",
        parameter_count_b=0.0,
        context_length=204_800,
        supported_engines=("cloud",),
        provider="minimax",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.30,
            "pricing_output": 1.20,
            "url": "https://platform.minimax.io/docs/api-reference/api-overview",
        },
    ),
    ModelSpec(
        model_id="MiniMax-M2.5-highspeed",
        name="MiniMax M2.5 Highspeed",
        parameter_count_b=0.0,
        context_length=204_800,
        supported_engines=("cloud",),
        provider="minimax",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.60,
            "pricing_output": 2.40,
            "url": "https://platform.minimax.io/docs/api-reference/api-overview",
        },
    ),
    # -----------------------------------------------------------------------
    # Cloud models — Atlas Cloud (OpenAI-compatible aggregator)
    #
    # IDs carry the "atlascloud/" routing prefix the cloud engine dispatches
    # on. Context lengths and prices are the gateway's own, read from
    # GET https://api.atlascloud.ai/v1/models (context_length, and
    # pricing.prompt / pricing.completion in USD per token).
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="atlascloud/openai/gpt-4.1-mini",
        name="GPT-4.1 Mini (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=1_047_576,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.4,
            "pricing_output": 1.6,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/openai/gpt-5.4-mini",
        name="GPT-5.4 Mini (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=400_000,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.75,
            "pricing_output": 4.5,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/deepseek-ai/deepseek-v3.2",
        name="DeepSeek V3.2 (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=163_840,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "moe",
            "pricing_input": 0.26,
            "pricing_output": 0.38,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/Qwen/Qwen3-235B-A22B-Instruct-2507",
        name="Qwen3 235B A22B Instruct (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=131_072,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "moe",
            "pricing_input": 0.2,
            "pricing_output": 0.88,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/qwen/qwen3.5-35b-a3b",
        name="Qwen3.5 35B A3B (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=262_144,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "moe",
            "pricing_input": 0.225,
            "pricing_output": 1.8,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/zai-org/GLM-4.6",
        name="GLM-4.6 (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=202_752,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "moe",
            "pricing_input": 0.6,
            "pricing_output": 2.2,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/moonshotai/kimi-k2.5",
        name="Kimi K2.5 (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=262_144,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "moe",
            "pricing_input": 0.49,
            "pricing_output": 2.5,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    ModelSpec(
        model_id="atlascloud/minimaxai/minimax-m2.5",
        name="MiniMax M2.5 (Atlas Cloud)",
        parameter_count_b=0.0,
        context_length=196_608,
        supported_engines=("cloud",),
        provider="atlascloud",
        requires_api_key=True,
        metadata={
            "architecture": "moe",
            "pricing_input": 0.295,
            "pricing_output": 1.2,
            "url": "https://www.atlascloud.ai/models",
        },
    ),
    # -----------------------------------------------------------------------
    # Cloud models — Google
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="gemini-2.5-pro",
        name="Gemini 2.5 Pro",
        parameter_count_b=0.0,
        context_length=1000000,
        supported_engines=("cloud",),
        provider="google",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 1.25,
            "pricing_output": 10.00,
            "url": "https://ai.google.dev/gemini-api/docs/models#gemini-2.5-pro",
        },
    ),
    ModelSpec(
        model_id="gemini-2.5-flash",
        name="Gemini 2.5 Flash",
        parameter_count_b=0.0,
        context_length=1000000,
        supported_engines=("cloud",),
        provider="google",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.30,
            "pricing_output": 2.50,
            "url": "https://ai.google.dev/gemini-api/docs/models#gemini-2.5-flash",
        },
    ),
    ModelSpec(
        model_id="gemini-3-pro",
        name="Gemini 3 Pro",
        parameter_count_b=0.0,
        context_length=1000000,
        supported_engines=("cloud",),
        provider="google",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 2.00,
            "pricing_output": 12.00,
            "url": "https://ai.google.dev/gemini-api/docs/models",
        },
    ),
    ModelSpec(
        model_id="gemini-3-flash",
        name="Gemini 3 Flash",
        parameter_count_b=0.0,
        context_length=1000000,
        supported_engines=("cloud",),
        provider="google",
        requires_api_key=True,
        metadata={
            "architecture": "proprietary",
            "pricing_input": 0.50,
            "pricing_output": 3.00,
            "url": "https://ai.google.dev/gemini-api/docs/models",
        },
    ),
    # -----------------------------------------------------------------------
    # Apple Foundation Models (on-device, AFM 3)
    #
    # These ids are run *labels*, not selectors: the Foundation Models
    # framework's dynamic profile picks AFM 3 Core (dense ~3B) or AFM 3 Core
    # Advanced (20B sparse MoE, 1-4B active) from the host device, and the SDK
    # exposes no way to choose. Requesting one label does not guarantee that
    # variant executed -- `AppleFMEngine.describe()` records the host chip and
    # SDK version so a run can be attributed after the fact.
    # -----------------------------------------------------------------------
    ModelSpec(
        model_id="afm-3",
        name="Apple Foundation Model 3",
        parameter_count_b=3.0,
        context_length=4096,
        supported_engines=("afm", "apple_fm"),
        provider="apple",
        metadata={
            "architecture": "dense",
            "variant_selection": "device-chosen; model id is a label only",
        },
    ),
    ModelSpec(
        model_id="afm-3-core",
        name="Apple Foundation Model 3 Core",
        parameter_count_b=3.0,
        context_length=4096,
        supported_engines=("afm", "apple_fm"),
        provider="apple",
        metadata={
            "architecture": "dense",
            "variant_selection": "device-chosen; model id is a label only",
        },
    ),
    ModelSpec(
        model_id="afm-3-core-advanced",
        name="Apple Foundation Model 3 Core Advanced",
        # 20B total, but Instruction-Following Pruning activates only 1-4B per
        # request; the 4B upper bound is what FLOPs accounting should use.
        parameter_count_b=20.0,
        active_parameter_count_b=4.0,
        context_length=4096,
        supported_engines=("afm", "apple_fm"),
        provider="apple",
        metadata={
            "architecture": "sparse-moe",
            "variant_selection": "device-chosen; model id is a label only",
        },
    ),
]


def resolve_model_id_for_engine(model_id: str, engine_id: str) -> str:
    """Resolve a catalog model ID when an engine has a distinct runtime ID."""
    if engine_id != "mlx":
        return model_id

    for spec in BUILTIN_MODELS:
        if spec.model_id == model_id and engine_id in spec.supported_engines:
            mlx_repo = spec.metadata.get("mlx_repo")
            if isinstance(mlx_repo, str) and mlx_repo:
                return mlx_repo
            break
    return model_id


def register_builtin_models() -> None:
    """Populate ``ModelRegistry`` with well-known models."""
    for spec in BUILTIN_MODELS:
        if not ModelRegistry.contains(spec.model_id):
            ModelRegistry.register_value(spec.model_id, spec)


def merge_discovered_models(engine_key: str, model_ids: List[str]) -> None:
    """Create minimal ``ModelSpec`` entries for models not already in the registry."""
    for model_id in model_ids:
        if not ModelRegistry.contains(model_id):
            spec = ModelSpec(
                model_id=model_id,
                name=model_id,
                parameter_count_b=0.0,
                context_length=0,
                supported_engines=(engine_key,),
            )
            ModelRegistry.register_value(model_id, spec)


__all__ = [
    "BUILTIN_MODELS",
    "merge_discovered_models",
    "register_builtin_models",
    "resolve_model_id_for_engine",
]