cct-cli 0.7.9.0__py3-none-any.whl

calc_terminal/models/profiles.py

@@ -0,0 +1,194 @@
+"""
+CAT Model Capabilities & Profile System.
+
+Enforces Section 13, 14, 26, 35-37 of the CAT AI Mode Reliability Contract.
+Distinguishes small/base models (e.g. deepseek-coder:1.3b-base-q8_0) from
+large instruction-following models, providing conservative budgets,
+minimal prompting, and specialized generation parameters.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional
+import re
+
+
+@dataclass
+class ModelCapabilities:
+    chat: bool = True
+    instruction_following: bool = True
+    tool_calling: bool = True
+    vision: bool = False
+    reasoning: bool = False
+    context_length: int = 4096
+    is_small_model: bool = False
+    is_base_model: bool = False
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "chat": self.chat,
+            "instruction_following": self.instruction_following,
+            "tool_calling": self.tool_calling,
+            "vision": self.vision,
+            "reasoning": self.reasoning,
+            "context_length": self.context_length,
+            "is_small_model": self.is_small_model,
+            "is_base_model": self.is_base_model,
+        }
+
+
+@dataclass
+class ModelProfile:
+    provider: str
+    model: str
+    capabilities: ModelCapabilities
+    prompt_template: str = "chat"  # "chat", "minimal", "completion"
+    recommended_temperature: float = 0.7
+    max_context_tokens: int = 4096
+    reserved_output_tokens: int = 1024
+    generation_options: Dict[str, Any] = field(default_factory=dict)
+
+    def is_small_or_base(self) -> bool:
+        return self.capabilities.is_small_model or self.capabilities.is_base_model
+
+    def supports_tools(self) -> bool:
+        return self.capabilities.tool_calling and not self.capabilities.is_base_model
+
+    def get_effective_options(self, user_options: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Merge base generation options with model defaults and optional user overrides."""
+        opts = dict(self.generation_options)
+        if user_options:
+            for k, v in user_options.items():
+                if v is not None:
+                    opts[k] = v
+        return opts
+
+
+# Regex patterns identifying small or base models
+_BASE_MODEL_PATTERNS = [
+    re.compile(r"[-:_]base($|[-:_])", re.IGNORECASE),
+    re.compile(r"base-q\d", re.IGNORECASE),
+]
+
+_SMALL_MODEL_PATTERNS = [
+    re.compile(r"[:\-_](0\.\d+|1\.[0-8]+|2|3)b($|[:\-_])", re.IGNORECASE),
+    re.compile(r"(tinyllama|smollm|qwen.*0\.5b|qwen.*1\.8b|deepseek.*1\.3b)", re.IGNORECASE),
+]
+
+_VISION_PATTERNS = [
+    re.compile(r"(vision|llava|gpt-4o|claude-3|gemini-1\.5|gemini-2\.0)", re.IGNORECASE),
+]
+
+_REASONING_PATTERNS = [
+    re.compile(r"(o1|o3|r1|reasoning|deepseek-r1)", re.IGNORECASE),
+]
+
+_TOOL_CAPABLE_PATTERNS = [
+    re.compile(r"(gpt-4|claude-3|gemini|llama-?3\.[123]|qwen2\.5.*(7b|14b|32b|72b)|mistral)", re.IGNORECASE),
+]
+
+
+def detect_capabilities(provider: str, model_name: str) -> ModelCapabilities:
+    """Analyze provider and model string to infer capabilities safely."""
+    provider_str = (provider or "").lower().strip()
+    model_str = (model_name or "").lower().strip()
+
+    is_base = any(p.search(model_str) for p in _BASE_MODEL_PATTERNS)
+    is_small = any(p.search(model_str) for p in _SMALL_MODEL_PATTERNS) or ("1.3b" in model_str)
+
+    # Base models do not reliably follow complex multi-turn instruction schemas
+    instruction_following = not is_base
+    tool_calling = False if (is_base or is_small) else any(p.search(model_str) for p in _TOOL_CAPABLE_PATTERNS)
+
+    # If provider is OpenAI/Anthropic/Gemini standard models, tool calling is standard
+    if provider_str in ("openai", "anthropic", "gemini") and not is_small:
+        tool_calling = True
+        instruction_following = True
+
+    vision = any(p.search(model_str) for p in _VISION_PATTERNS)
+    reasoning = any(p.search(model_str) for p in _REASONING_PATTERNS)
+
+    if is_small:
+        context_length = 2048
+    elif is_base:
+        context_length = 2048
+    elif "16k" in model_str:
+        context_length = 16384
+    elif "32k" in model_str:
+        context_length = 32768
+    elif "128k" in model_str or "gpt-4o" in model_str or "gemini" in model_str:
+        context_length = 131072
+    else:
+        context_length = 4096
+
+    return ModelCapabilities(
+        chat=True,
+        instruction_following=instruction_following,
+        tool_calling=tool_calling,
+        vision=vision,
+        reasoning=reasoning,
+        context_length=context_length,
+        is_small_model=is_small,
+        is_base_model=is_base,
+    )
+
+
+def get_model_profile(provider: str, model_name: str, config: Optional[Dict[str, Any]] = None) -> ModelProfile:
+    """Build a complete ModelProfile tailored to the given provider and model."""
+    caps = detect_capabilities(provider, model_name)
+
+    if caps.is_small_model or caps.is_base_model:
+        # Conservative defaults for small/base local models (e.g. deepseek-coder:1.3b-base-q8_0)
+        recommended_temp = 0.3
+        max_context = min(caps.context_length, 1536)
+        reserved_out = 512
+        prompt_template = "minimal" if caps.is_base_model else "chat"
+        gen_opts = {
+            "temperature": recommended_temp,
+            "top_p": 0.9,
+            "repeat_penalty": 1.18,
+            "num_predict": reserved_out,
+        }
+    else:
+        # Standard instruction/chat model defaults
+        recommended_temp = 0.7
+        max_context = min(caps.context_length, 8192)
+        reserved_out = 1024
+        prompt_template = "chat"
+        gen_opts = {
+            "temperature": recommended_temp,
+            "top_p": 0.95,
+        }
+
+    # Override temperature if explicitly provided in config
+    if config and config.get("temperature") is not None:
+        try:
+            gen_opts["temperature"] = float(config["temperature"])
+        except (ValueError, TypeError):
+            pass
+
+    # For Ollama models, check if model size exceeds GPU VRAM (e.g. 8B/9.6GB model on 4GB VRAM)
+    # Default to num_gpu: 0 (CPU) to prevent llama-server crashing with 0xc0000409 buffer overrun
+    if (provider or "").lower() == "ollama":
+        if config and config.get("num_gpu") is not None:
+            gen_opts["num_gpu"] = int(config["num_gpu"])
+        else:
+            try:
+                from .. import pc_specs
+                specs = pc_specs.get_specs()
+                vram = specs.get("gpu_vram_gb", 0)
+                is_large = any(k in (model_name or "").lower() for k in ("8b", "9b", "14b", "32b", "70b", "e4b", "gemma4", "gemma:7b", "llama3:8b"))
+                if vram and vram <= 4.5 and is_large:
+                    gen_opts["num_gpu"] = 0
+            except Exception:
+                pass
+
+    return ModelProfile(
+        provider=provider or "ollama",
+        model=model_name or "default",
+        capabilities=caps,
+        prompt_template=prompt_template,
+        recommended_temperature=recommended_temp,
+        max_context_tokens=max_context,
+        reserved_output_tokens=reserved_out,
+        generation_options=gen_opts,
+    )

calc_terminal/models/registry.py

@@ -0,0 +1,265 @@
+"""Model registry — curated metadata + dynamic discovery merging.
+
+Data-driven redesign (v0.7.4+): curated model metadata lives in
+`models/model_metadata.json`, provider metadata + fallback model lists
+live in `providers/providers.json`. No model names are hardcoded in
+Python source — this module only loads and queries the JSON stores.
+
+Dynamic model discovery, disk caching, refresh and category filtering
+live in `models/manager.py`; this module keeps the classic lookup API
+used by the picker UIs (get_model_info / get_badges / enrich_models /
+group_by_tier / ...).
+"""
+
+import json
+import os
+from typing import Optional
+
+from . import manager
+
+
+# ── Schema ─────────────────────────────────────────────────────────────────
+
+class ModelInfo:
+    __slots__ = (
+        "id", "provider", "family",
+        "context_window", "capabilities",
+        "pricing_tier", "status",
+        "input_price_per_1m", "output_price_per_1m",
+    )
+
+    def __init__(self, id="", provider="", family="",
+                 context_window=0, capabilities=None,
+                 pricing_tier="unknown", status="stable",
+                 input_price_per_1m=0.0, output_price_per_1m=0.0):
+        self.id = id
+        self.provider = provider
+        self.family = family
+        self.context_window = context_window
+        self.capabilities = capabilities or []
+        self.pricing_tier = pricing_tier
+        self.status = status
+        self.input_price_per_1m = input_price_per_1m
+        self.output_price_per_1m = output_price_per_1m
+
+    def to_dict(self):
+        return {
+            "id": self.id,
+            "provider": self.provider,
+            "family": self.family,
+            "context_window": self.context_window,
+            "capabilities": list(self.capabilities),
+            "pricing_tier": self.pricing_tier,
+            "status": self.status,
+            "input_price_per_1m": self.input_price_per_1m,
+            "output_price_per_1m": self.output_price_per_1m,
+        }
+
+
+# ── Metadata helpers (JSON-backed) ─────────────────────────────────────────
+
+def _meta_to_legacy(entry: dict) -> dict:
+    """Convert a model_metadata.json entry to the legacy ModelInfo dict."""
+    caps = []
+    for key, label in (("reasoning", "reasoning"), ("vision", "vision"),
+                       ("coding", "coding"), ("embedding", "embeddings"),
+                       ("image_generation", "image_gen"), ("speech", "audio"),
+                       ("tools", "tool_use"), ("streaming", "streaming")):
+        if entry.get(key):
+            caps.append(label)
+    if not caps:
+        caps = ["chat", "streaming"]
+    tier = "free" if entry.get("free") else "paid" if entry.get("paid") else "unknown"
+    status = ("deprecated" if entry.get("deprecated")
+              else "preview" if entry.get("preview") else "stable")
+    return {
+        "id": entry.get("id", ""),
+        "provider": entry.get("provider", ""),
+        "family": entry.get("family", ""),
+        "context_window": int(entry.get("context_length", 0) or 0),
+        "capabilities": caps,
+        "pricing_tier": tier,
+        "status": status,
+        "input_price_per_1m": float(entry.get("input_price_per_1m", 0.0) or 0.0),
+        "output_price_per_1m": float(entry.get("output_price_per_1m", 0.0) or 0.0),
+        "recommendation_badges": entry.get("recommendation_badges", []),
+    }
+
+
+def _resolve_meta(model_id: str, provider_id: str) -> Optional[dict]:
+    entry = manager.get_model_meta(model_id, provider_id)
+    if entry:
+        return _meta_to_legacy(entry)
+    return None
+
+
+# ── Lookup Helpers ─────────────────────────────────────────────────────────
+
+def get_model_info(model_id: str, provider_id: str) -> Optional[dict]:
+    """Look up curated metadata for a specific model+provider combination."""
+    return _resolve_meta(model_id, provider_id)
+
+
+def get_price_tier(model_id: str, provider_id: str) -> str:
+    """Return 'free', 'paid', or 'unknown'."""
+    info = get_model_info(model_id, provider_id)
+    if info:
+        return info.get("pricing_tier", "unknown")
+    lower = model_id.lower()
+    if any(kw in lower for kw in ("free", "open-")):
+        return "free"
+    return "unknown"
+
+
+def get_capabilities(model_id: str, provider_id: str) -> list[str]:
+    """Return list of known capabilities for this model."""
+    info = get_model_info(model_id, provider_id)
+    if info:
+        return list(info.get("capabilities", []))
+    return []
+
+
+def get_badges(model_id: str, provider_id: str) -> list[str]:
+    """Return list of badge strings for UI display.
+    Each badge is a short color-tagged string like \"[FREE]\", \"[VISION]\", etc.
+    """
+    badges = []
+    info = get_model_info(model_id, provider_id)
+
+    # Pricing badge
+    tier = (info.get("pricing_tier", "unknown") if info
+            else get_price_tier(model_id, provider_id))
+    if tier == "free":
+        badges.append("[FREE]")
+    elif tier == "paid":
+        badges.append("[PAID]")
+    else:
+        badges.append("[?]")
+
+    # Status badge
+    if info:
+        status = info.get("status", "")
+        if status == "preview":
+            badges.append("[PREVIEW]")
+        elif status == "experimental":
+            badges.append("[EXP]")
+        elif status == "deprecated":
+            badges.append("[DEPRECATED]")
+
+    # Capability badges
+    caps = info.get("capabilities", []) if info else []
+    if "vision" in caps:
+        badges.append("[VISION]")
+    if "reasoning" in caps:
+        badges.append("[REASONING]")
+    if "coding" in caps:
+        badges.append("[CODING]")
+    if "image_gen" in caps:
+        badges.append("[IMAGE]")
+    if "audio" in caps:
+        badges.append("[AUDIO]")
+    if "embeddings" in caps:
+        badges.append("[EMBED]")
+
+    # Context window badge
+    if info:
+        ctx = info.get("context_window", 0)
+        if ctx >= 1000000:
+            badges.append("[1M]")
+        elif ctx >= 100000:
+            badges.append("[100K]")
+        elif ctx >= 32000:
+            badges.append("[32K]")
+        elif ctx >= 8000:
+            badges.append("[8K]")
+
+    # Recommendation badges from dynamic registry (e.g. Best for Coding)
+    if info:
+        for b in info.get("recommendation_badges", []):
+            b_clean = f"[{b.strip('[]').upper()}]"
+            if b_clean not in badges:
+                badges.append(b_clean)
+
+    return badges
+
+
+def get_family(model_id: str, provider_id: str) -> str:
+    """Return the model family name, if known."""
+    info = get_model_info(model_id, provider_id)
+    if info:
+        return info.get("family", "")
+    return ""
+
+
+def get_context_window(model_id: str, provider_id: str) -> int:
+    """Return the context window size, if known."""
+    info = get_model_info(model_id, provider_id)
+    if info:
+        return info.get("context_window", 0)
+    return 0
+
+
+# ── Dynamic Merge ──────────────────────────────────────────────────────────
+
+def enrich_models(provider_id: str, model_ids: list[str]) -> list[dict]:
+    """Merge dynamic model list with curated metadata.
+
+    Returns a list of dicts, one per model, sorted alphabetically:
+        {"id": str, "pricing_tier": str, "badges": list[str],
+         "capabilities": list[str], "family": str, "context_window": int}
+    """
+    result = []
+    for mid in model_ids:
+        info = get_model_info(mid, provider_id)
+        if info:
+            result.append({
+                "id": mid,
+                "pricing_tier": info.get("pricing_tier", "unknown"),
+                "badges": get_badges(mid, provider_id),
+                "capabilities": list(info.get("capabilities", [])),
+                "family": info.get("family", ""),
+                "context_window": info.get("context_window", 0),
+                "status": info.get("status", "stable"),
+            })
+        else:
+            tier = get_price_tier(mid, provider_id)
+            result.append({
+                "id": mid,
+                "pricing_tier": tier,
+                "badges": ["[?]"],
+                "capabilities": [],
+                "family": "",
+                "context_window": 0,
+                "status": "unknown",
+            })
+    result.sort(key=lambda x: x["id"].lower())
+    return result
+
+
+def tier_sort_key(entry: dict) -> int:
+    """Sort key: free (0) before paid (1) before unknown (2)."""
+    t = entry.get("pricing_tier", "unknown")
+    return {"free": 0, "paid": 1, "unknown": 2}.get(t, 2)
+
+
+def group_by_tier(enriched: list[dict]) -> dict[str, list[dict]]:
+    """Group enriched model list by pricing tier.
+
+    Returns {"free": [...], "paid": [...], "unknown": [...]}
+    """
+    groups: dict[str, list[dict]] = {"free": [], "paid": [], "unknown": []}
+    for entry in enriched:
+        tier = entry.get("pricing_tier", "unknown")
+        groups.setdefault(tier, []).append(entry)
+    return groups
+
+
+# ── Re-exports (new manager API convenience) ───────────────────────────────
+
+def get_providers() -> list[dict]:
+    """All provider metadata from providers.json."""
+    return manager.list_providers()
+
+
+def get_provider(provider_id: str) -> Optional[dict]:
+    return manager.get_provider(provider_id)

calc_terminal/models/schema.py

@@ -0,0 +1,197 @@
+"""
+calc_terminal/models/schema.py
+==============================
+Standardized Model Metadata Schema for CAT's Dynamic Model Registry.
+
+Represents AI models in a unified, provider-agnostic format supporting:
+  - Canonical model identity across multiple deployment endpoints.
+  - Granular capability detection (reasoning, coding, vision, computer use, etc.).
+  - Multi-level reasoning configurations (e.g. low, medium, high, xhigh, max).
+  - Clear access tier categorization (open_weight, free_api, paid_api, local, cloud).
+  - Release and verification tracking (first_seen, last_seen, last_verified).
+"""
+
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import List, Dict, Any, Optional
+
+
+# Standard Availability States
+AVAILABILITY_API = "api"
+AVAILABILITY_OPEN_WEIGHT = "open_weight"
+AVAILABILITY_FREE_API = "free_api"
+AVAILABILITY_FREE_TIER = "free_tier"
+AVAILABILITY_PAID_API = "paid_api"
+AVAILABILITY_LOCAL = "local"
+AVAILABILITY_CLOUD = "cloud"
+AVAILABILITY_SUBSCRIPTION = "subscription"
+
+# Standard Model Statuses
+STATUS_ACTIVE = "active"
+STATUS_PREVIEW = "preview"
+STATUS_BETA = "beta"
+STATUS_DEPRECATED = "deprecated"
+STATUS_RETIRED = "retired"
+STATUS_UNAVAILABLE = "unavailable"
+STATUS_AUTH_REQUIRED = "auth_required"
+STATUS_DISCOVERED_UNAVAILABLE = "discovered_but_unavailable"
+
+# Standard Categories
+CATEGORY_GENERAL = "general"
+CATEGORY_REASONING = "reasoning"
+CATEGORY_CODING = "coding"
+CATEGORY_FAST = "fast"
+CATEGORY_CHEAP = "cheap"
+CATEGORY_LONG_CONTEXT = "long_context"
+CATEGORY_VISION = "vision"
+CATEGORY_AUDIO = "audio"
+CATEGORY_MULTIMODAL = "multimodal"
+CATEGORY_AGENT = "agent"
+CATEGORY_RESEARCH = "research"
+CATEGORY_LOCAL = "local"
+CATEGORY_OPEN_WEIGHT = "open_weight"
+CATEGORY_EMBEDDING = "embedding"
+CATEGORY_SPECIALIZED = "specialized"
+CATEGORY_FREE_API = "free"
+CATEGORY_PAID_API = "paid"
+AVAILABILITY_FREE_TIER = "free_tier"
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+@dataclass
+class ModelInfo:
+    """Standardized representation of an AI model in CAT."""
+
+    provider: str
+    model_id: str
+    display_name: str = ""
+    family: str = ""
+    version: str = ""
+    canonical_model_id: str = ""
+    release_date: Optional[str] = None
+    status: str = STATUS_ACTIVE
+    availability: str = AVAILABILITY_PAID_API
+    modalities: List[str] = field(default_factory=lambda: ["text"])
+    capabilities: List[str] = field(default_factory=lambda: ["chat", "streaming"])
+    context_window: int = 128000
+    max_output_tokens: int = 4096
+    reasoning_levels: List[str] = field(default_factory=list)
+    pricing: Dict[str, float] = field(default_factory=lambda: {"input_price_per_1m": 0.0, "output_price_per_1m": 0.0})
+    endpoint: str = ""
+    authentication_required: bool = True
+    local: bool = False
+    cloud: bool = True
+    verified: bool = False
+    source: str = "official_api"
+    first_seen: str = field(default_factory=_now_iso)
+    last_seen: str = field(default_factory=_now_iso)
+    last_verified: str = field(default_factory=_now_iso)
+    stale: bool = False
+    tags: List[str] = field(default_factory=list)
+    recommendation_badges: List[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if not self.display_name:
+            self.display_name = self.model_id
+        if not self.canonical_model_id:
+            self.canonical_model_id = f"{self.provider}:{self.model_id}"
+        if not self.family:
+            self.family = self._derive_family()
+
+    def _derive_family(self) -> str:
+        mid = self.model_id.lower()
+        if "gpt" in mid or "o1" in mid or "o3" in mid:
+            return "GPT"
+        if "claude" in mid:
+            return "Claude"
+        if "gemini" in mid:
+            return "Gemini"
+        if "deepseek" in mid:
+            return "DeepSeek"
+        if "qwen" in mid:
+            return "Qwen"
+        if "kimi" in mid or "moonshot" in mid:
+            return "Kimi"
+        if "glm" in mid:
+            return "GLM"
+        if "grok" in mid:
+            return "Grok"
+        if "mistral" in mid or "codestral" in mid:
+            return "Mistral"
+        if "command" in mid:
+            return "Command"
+        if "llama" in mid:
+            return "Llama"
+        if "minimax" in mid or "abab" in mid:
+            return "MiniMax"
+        if "hunyuan" in mid or "hy" in mid:
+            return "Hunyuan"
+        if "doubao" in mid or "seed" in mid:
+            return "Seed"
+        if "ernie" in mid:
+            return "ERNIE"
+        return self.provider.capitalize()
+
+    @property
+    def availability_state(self) -> str:
+        return self.status
+
+    def is_usable(self) -> bool:
+        """A model is usable only when it has an active/preview state,
+        is verified or from an official provider endpoint, and is not
+        marked as discovered_but_unavailable."""
+        return (
+            self.status in (STATUS_ACTIVE, STATUS_PREVIEW, STATUS_BETA)
+            and not self.status == STATUS_DISCOVERED_UNAVAILABLE
+        )
+
+    def has_capability(self, capability: str) -> bool:
+        cap = capability.lower().strip()
+        return cap in [c.lower() for c in self.capabilities]
+
+    def matches_category(self, category: str) -> bool:
+        cat = category.lower().strip()
+        if cat in ("all", "*"):
+            return True
+        if cat == CATEGORY_LOCAL:
+            return self.local
+        if cat == CATEGORY_OPEN_WEIGHT:
+            return self.availability == AVAILABILITY_OPEN_WEIGHT or "open_weight" in self.tags
+        if cat in (CATEGORY_FREE_API, "free"):
+            return self.availability in (AVAILABILITY_FREE_API, AVAILABILITY_FREE_TIER) or self.pricing.get("input_price_per_1m", 0.0) == 0.0
+        if cat in (CATEGORY_PAID_API, "paid"):
+            return self.pricing.get("input_price_per_1m", 0.0) > 0.0
+        if cat == CATEGORY_REASONING:
+            return self.has_capability("reasoning") or bool(self.reasoning_levels) or any(k in self.model_id.lower() for k in ("reasoner", "r1", "o1", "o3", "qwq", "k3", "thinking"))
+        if cat == CATEGORY_CODING:
+            return self.has_capability("coding") or any(k in self.model_id.lower() for k in ("coder", "codestral", "astra", "code"))
+        if cat == CATEGORY_VISION:
+            return self.has_capability("vision") or "image" in self.modalities or any(k in self.model_id.lower() for k in ("vision", "4o", "4v", "pixtral", "vl", "gemini"))
+        if cat == CATEGORY_FAST:
+            return self.has_capability("fast") or any(k in self.model_id.lower() for k in ("mini", "flash", "turbo", "instant", "haiku", "8b"))
+        if cat == CATEGORY_LONG_CONTEXT:
+            return self.context_window >= 128000
+        if cat == CATEGORY_AGENT:
+            return self.has_capability("agent") or self.has_capability("computer_use") or self.has_capability("tools")
+        if cat == CATEGORY_RESEARCH:
+            return self.has_capability("research") or self.matches_category(CATEGORY_REASONING)
+        return self.has_capability(cat) or cat in self.tags
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "ModelInfo":
+        cleaned = dict(data)
+        # Handle backward-compatible fields
+        if "id" in cleaned and "model_id" not in cleaned:
+            cleaned["model_id"] = cleaned.pop("id")
+        if "context_length" in cleaned and "context_window" not in cleaned:
+            cleaned["context_window"] = int(cleaned.pop("context_length") or 128000)
+        # Retain only recognized dataclass keys
+        valid_keys = {f for f in cls.__dataclass_fields__}
+        filtered = {k: v for k, v in cleaned.items() if k in valid_keys}
+        return cls(**filtered)