gdmcode 0.1.0__py3-none-any.whl

src/models/definitions.py

@@ -0,0 +1,459 @@
+"""Model definitions — IDs, pricing, context windows for all supported providers.
+
+All values are named constants. No magic strings or numbers anywhere else in
+the codebase should reference model IDs or pricing directly.
+
+Pricing as of April 2026 (USD per 1M tokens unless noted).
+Providers:
+  - xAI Grok    — primary, best models, native web_search tool
+  - Google Gemini — fallback, free tier (Flash), easy signup for everyone
+  - OpenAI Codex  — optional, o3/o4-mini for reasoning, GPT-4.1 for cheap bulk
+"""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, replace
+
+__all__ = [
+    "Provider",
+    "ModelTier",
+    "PROXY_DEFAULT_URL",
+    "ModelDef",
+    "MODELS",
+    "SCOUT",
+    "CODER",
+    "THINKER",
+    "REASONER",
+    "DEBATE",
+    "STANDARD",
+    "GEMINI_SCOUT",
+    "GEMINI_CODER",
+    "GEMINI_THINKER",
+    "GEMINI_REASONER",
+    "CODEX_SCOUT",
+    "CODEX_CODER",
+    "CODEX_THINKER",
+    "CODEX_REASONER",
+    "CODEX_DEBATE",
+    "PROVIDER_BASE_URLS",
+    "TOOL_CALL_COSTS",
+    "get_model",
+    "get_capability",
+    "models_for_provider",
+    "apply_model_id_overrides",
+]
+
+
+class Provider:
+    """Supported API providers (string constants for serialisation safety)."""
+    GROK = "grok"
+    GEMINI = "gemini"
+    CODEX = "codex"
+    OLLAMA = "ollama"
+    VLLM = "vllm"
+
+
+# Default proxy relay URL — used when no custom URL is configured.
+# The proxy implements the OpenAI-compatible /v1 API and forwards requests
+# to the real providers, allowing access from geo-restricted regions.
+PROXY_DEFAULT_URL: str = "https://proxy.gdm.dev/v1"
+
+
+class ModelTier:
+    """Human-readable tier names used in routing logic."""
+    SCOUT = "scout"
+    CODER = "coder"
+    THINKER = "thinker"
+    REASONER = "reasoner"
+    DEBATE = "debate"
+    STANDARD = "standard"
+
+
+PROVIDER_BASE_URLS: dict[str, str] = {
+    Provider.GROK: "https://api.x.ai/v1",
+    Provider.GEMINI: "https://generativelanguage.googleapis.com/v1beta/openai/",
+    Provider.CODEX: "https://api.openai.com/v1",
+    Provider.OLLAMA: "http://localhost:11434",
+    Provider.VLLM: "http://localhost:8000",
+}
+
+
+@dataclass(frozen=True)
+class ModelDef:
+    """Complete definition of one model variant."""
+
+    id: str
+    tier: str
+    provider: str
+    input_per_m: float       # USD per 1M input tokens
+    output_per_m: float      # USD per 1M output tokens
+    cached_per_m: float      # USD per 1M cached input tokens (0 if unsupported)
+    context_window: int      # max tokens
+    supports_reasoning: bool = False
+    supports_tools: bool = True
+    supports_web_search: bool = False  # native web_search tool (Grok only)
+    notes: str = ""
+
+    def input_cost(self, tokens: int) -> float:
+        return (tokens / 1_000_000) * self.input_per_m
+
+    def output_cost(self, tokens: int) -> float:
+        return (tokens / 1_000_000) * self.output_per_m
+
+    def cached_cost(self, tokens: int) -> float:
+        return (tokens / 1_000_000) * self.cached_per_m
+
+
+# ---------------------------------------------------------------------------
+# xAI Grok models
+# ---------------------------------------------------------------------------
+
+SCOUT = ModelDef(
+    id="grok-4-1-fast-non-reasoning",
+    tier=ModelTier.SCOUT,
+    provider=Provider.GROK,
+    input_per_m=0.20,
+    output_per_m=0.50,
+    cached_per_m=0.05,
+    context_window=2_000_000,
+    supports_web_search=True,
+    notes="File reads, grep, summarization, compression, Tree-sitter indexing, commit messages",
+)
+
+CODER = ModelDef(
+    id="grok-4-1-fast-reasoning",
+    tier=ModelTier.CODER,
+    provider=Provider.GROK,
+    input_per_m=0.20,
+    output_per_m=0.50,
+    cached_per_m=0.05,
+    context_window=2_000_000,
+    supports_reasoning=True,
+    supports_web_search=True,
+    notes="Quick code edits, tests, boilerplate, ensemble patching strategies",
+)
+
+THINKER = ModelDef(
+    id="grok-4.20-0309-non-reasoning",
+    tier=ModelTier.THINKER,
+    provider=Provider.GROK,
+    input_per_m=2.00,
+    output_per_m=6.00,
+    cached_per_m=0.20,
+    context_window=2_000_000,
+    supports_web_search=True,
+    notes="Standard coding tasks, refactoring, multi-file edits",
+)
+
+REASONER = ModelDef(
+    id="grok-4.20-0309-reasoning",
+    tier=ModelTier.REASONER,
+    provider=Provider.GROK,
+    input_per_m=2.00,
+    output_per_m=6.00,
+    cached_per_m=0.20,
+    context_window=2_000_000,
+    supports_reasoning=True,
+    supports_web_search=True,
+    notes="Architecture decisions, hard bugs, cross-file design, security reviews",
+)
+
+DEBATE = ModelDef(
+    id="grok-4.20-multi-agent-0309",
+    tier=ModelTier.DEBATE,
+    provider=Provider.GROK,
+    input_per_m=2.00,
+    output_per_m=6.00,
+    cached_per_m=0.20,
+    context_window=2_000_000,
+    supports_reasoning=True,
+    supports_web_search=True,
+    notes="4-agent internal debate. Requires SuperGrok Heavy. Falls back to REASONER.",
+)
+
+STANDARD = ModelDef(
+    id="grok-4-0709",
+    tier=ModelTier.STANDARD,
+    provider=Provider.GROK,
+    input_per_m=3.00,
+    output_per_m=15.00,
+    cached_per_m=0.20,
+    context_window=256_000,
+    supports_reasoning=True,
+    supports_web_search=True,
+    notes="Classic Grok 4. Fallback when 2M context not needed.",
+)
+
+# ---------------------------------------------------------------------------
+# Google Gemini models — OpenAI-compatible endpoint, no extra SDK
+# Flash-8B for Coder tier: ultra-cheap bulk edits and indexing
+# ---------------------------------------------------------------------------
+
+GEMINI_SCOUT = ModelDef(
+    id="gemini-2.5-flash",
+    tier=ModelTier.SCOUT,
+    provider=Provider.GEMINI,
+    input_per_m=0.15,
+    output_per_m=0.60,
+    cached_per_m=0.0,
+    context_window=1_000_000,
+    notes="Free tier: 1K req/day. File reads, summarization, quick answers.",
+)
+
+GEMINI_CODER = ModelDef(
+    id="gemini-2.5-flash-8b",
+    tier=ModelTier.CODER,
+    provider=Provider.GEMINI,
+    input_per_m=0.075,
+    output_per_m=0.30,
+    cached_per_m=0.0,
+    context_window=1_000_000,
+    notes="Ultra-cheap bulk: file indexing, convention extraction, boilerplate edits.",
+)
+
+GEMINI_THINKER = ModelDef(
+    id="gemini-2.5-pro",
+    tier=ModelTier.THINKER,
+    provider=Provider.GEMINI,
+    input_per_m=1.25,
+    output_per_m=10.00,
+    cached_per_m=0.0,
+    context_window=1_000_000,
+    supports_reasoning=True,
+    notes="≤200K input tier. Architecture, refactor, hard bugs.",
+)
+
+GEMINI_REASONER = ModelDef(
+    id="gemini-2.5-pro",
+    tier=ModelTier.REASONER,
+    provider=Provider.GEMINI,
+    input_per_m=2.50,
+    output_per_m=10.00,
+    cached_per_m=0.0,
+    context_window=1_000_000,
+    supports_reasoning=True,
+    notes=">200K input tier (long context premium). Also handles DEBATE fallback.",
+)
+
+# ---------------------------------------------------------------------------
+# OpenAI Codex models — o3/o4-mini for reasoning, GPT-4.1 for bulk
+# o4-mini: best cost/performance reasoning model globally for algorithmic bugs
+# ---------------------------------------------------------------------------
+
+CODEX_SCOUT = ModelDef(
+    id="gpt-4.1-mini",
+    tier=ModelTier.SCOUT,
+    provider=Provider.CODEX,
+    input_per_m=0.40,
+    output_per_m=1.60,
+    cached_per_m=0.10,
+    context_window=1_047_576,
+    notes="Fast, cheap bulk. File reads, summarization, grep-class tasks.",
+)
+
+CODEX_CODER = ModelDef(
+    id="gpt-4.1",
+    tier=ModelTier.CODER,
+    provider=Provider.CODEX,
+    input_per_m=2.00,
+    output_per_m=8.00,
+    cached_per_m=0.50,
+    context_window=1_047_576,
+    supports_tools=True,
+    notes="Strong code generation, multi-file edits, test writing.",
+)
+
+CODEX_THINKER = ModelDef(
+    id="o4-mini",
+    tier=ModelTier.THINKER,
+    provider=Provider.CODEX,
+    input_per_m=1.10,
+    output_per_m=4.40,
+    cached_per_m=0.275,
+    context_window=200_000,
+    supports_reasoning=True,
+    notes="Best cost/perf reasoning. Exceptional for algorithmic bugs and hard logic.",
+)
+
+CODEX_REASONER = ModelDef(
+    id="o3",
+    tier=ModelTier.REASONER,
+    provider=Provider.CODEX,
+    input_per_m=2.00,
+    output_per_m=8.00,
+    cached_per_m=0.50,
+    context_window=200_000,
+    supports_reasoning=True,
+    notes="Deep multi-step reasoning. Architecture decisions, security audits.",
+)
+
+CODEX_DEBATE = ModelDef(
+    id="o3",
+    tier=ModelTier.DEBATE,
+    provider=Provider.CODEX,
+    input_per_m=2.00,
+    output_per_m=8.00,
+    cached_per_m=0.50,
+    context_window=200_000,
+    supports_reasoning=True,
+    notes="Simulated debate: 4 parallel o3 calls with adversarial prompts, merged by CODER.",
+)
+
+# ---------------------------------------------------------------------------
+# Catalogue and routing
+# ---------------------------------------------------------------------------
+
+_GROK_MODELS: list[ModelDef] = [SCOUT, CODER, THINKER, REASONER, DEBATE, STANDARD]
+_GEMINI_MODELS: list[ModelDef] = [GEMINI_SCOUT, GEMINI_CODER, GEMINI_THINKER, GEMINI_REASONER]
+_CODEX_MODELS: list[ModelDef] = [CODEX_SCOUT, CODEX_CODER, CODEX_THINKER, CODEX_REASONER, CODEX_DEBATE]
+MODELS: list[ModelDef] = _GROK_MODELS + _GEMINI_MODELS + _CODEX_MODELS
+
+_GROK_BY_TIER: dict[str, ModelDef] = {m.tier: m for m in _GROK_MODELS}
+_GEMINI_BY_TIER: dict[str, ModelDef] = {m.tier: m for m in _GEMINI_MODELS}
+_CODEX_BY_TIER: dict[str, ModelDef] = {m.tier: m for m in _CODEX_MODELS}
+
+_TIER_MAPS: dict[str, dict[str, ModelDef]] = {
+    Provider.GROK: _GROK_BY_TIER,
+    Provider.GEMINI: _GEMINI_BY_TIER,
+    Provider.CODEX: _CODEX_BY_TIER,
+}
+
+# Fallback chain when a tier is missing for a provider
+_FALLBACKS: dict[tuple[str, str], str] = {
+    (Provider.GEMINI, ModelTier.DEBATE): ModelTier.REASONER,
+    (Provider.GEMINI, ModelTier.STANDARD): ModelTier.REASONER,
+}
+
+
+def get_model(id_or_tier: str, provider: str = Provider.GROK) -> ModelDef:
+    """Look up a ModelDef by (tier, provider). Falls back gracefully."""
+    tier_map = _TIER_MAPS.get(provider, _GROK_BY_TIER)
+    if id_or_tier in tier_map:
+        return tier_map[id_or_tier]
+    # Check provider-specific fallbacks
+    fallback_tier = _FALLBACKS.get((provider, id_or_tier))
+    if fallback_tier and fallback_tier in tier_map:
+        return tier_map[fallback_tier]
+    raise KeyError(f"Unknown model tier '{id_or_tier}' for provider '{provider}'.")
+
+
+def models_for_provider(provider: str) -> list[ModelDef]:
+    """Return all models for a given provider in escalation order."""
+    match provider:
+        case Provider.GEMINI:
+            return list(_GEMINI_MODELS)
+        case Provider.CODEX:
+            return list(_CODEX_MODELS)
+        case _:
+            return list(_GROK_MODELS)
+
+
+# ---------------------------------------------------------------------------
+# Tool call costs (USD per 1K calls) — Grok-native tools only
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class ToolCallCost:
+    name: str
+    per_1k_calls: float
+
+    def cost(self, calls: int) -> float:
+        return (calls / 1000) * self.per_1k_calls
+
+
+TOOL_CALL_COSTS: dict[str, ToolCallCost] = {
+    "web_search": ToolCallCost("web_search", 5.00),
+    "x_search": ToolCallCost("x_search", 5.00),
+    "document_query": ToolCallCost("document_query", 2.50),
+    "file_attachment_search": ToolCallCost("file_attachment_search", 10.00),
+}
+
+# ---------------------------------------------------------------------------
+# Constant name → module attribute map (for apply_model_id_overrides)
+# ---------------------------------------------------------------------------
+
+_CONST_MAP: dict[str, str] = {
+    "grok.scout": "SCOUT",
+    "grok.coder": "CODER",
+    "grok.thinker": "THINKER",
+    "grok.reasoner": "REASONER",
+    "grok.debate": "DEBATE",
+    "grok.standard": "STANDARD",
+    "gemini.scout": "GEMINI_SCOUT",
+    "gemini.coder": "GEMINI_CODER",
+    "gemini.thinker": "GEMINI_THINKER",
+    "gemini.reasoner": "GEMINI_REASONER",
+    "codex.scout": "CODEX_SCOUT",
+    "codex.coder": "CODEX_CODER",
+    "codex.thinker": "CODEX_THINKER",
+    "codex.reasoner": "CODEX_REASONER",
+    "codex.debate": "CODEX_DEBATE",
+}
+
+
+def apply_model_id_overrides(overrides: dict[str, str]) -> None:
+    """Patch module-level ModelDef constants with configured IDs.
+
+    Resolution order: env var > config.toml > hardcoded default.
+    Must be called once during ``load_config()`` before any model is used.
+
+    Args:
+        overrides: mapping of ``"{provider}.{tier}"`` → new model ID string.
+    """
+    module = sys.modules[__name__]
+    patched: list[str] = []
+    for key, new_id in overrides.items():
+        const_name = _CONST_MAP.get(key.lower())
+        if const_name is None:
+            continue
+        old_def: ModelDef = getattr(module, const_name)
+        if old_def.id != new_id:
+            setattr(module, const_name, replace(old_def, id=new_id))
+            patched.append(f"{const_name}: {old_def.id!r} → {new_id!r}")
+    if patched:
+        _rebuild_lookup_dicts()
+
+
+def _rebuild_lookup_dicts() -> None:
+    """Rebuild tier-lookup dicts after ID overrides."""
+    module = sys.modules[__name__]
+    grok_models = [
+        module.SCOUT, module.CODER, module.THINKER,
+        module.REASONER, module.DEBATE, module.STANDARD,
+    ]
+    gemini_models = [
+        module.GEMINI_SCOUT, module.GEMINI_CODER,
+        module.GEMINI_THINKER, module.GEMINI_REASONER,
+    ]
+    codex_models = [
+        module.CODEX_SCOUT, module.CODEX_CODER, module.CODEX_THINKER,
+        module.CODEX_REASONER, module.CODEX_DEBATE,
+    ]
+    module.MODELS = grok_models + gemini_models + codex_models  # type: ignore[attr-defined]
+    module._GROK_BY_TIER = {m.tier: m for m in grok_models}  # type: ignore[attr-defined]
+    module._GEMINI_BY_TIER = {m.tier: m for m in gemini_models}  # type: ignore[attr-defined]
+    module._CODEX_BY_TIER = {m.tier: m for m in codex_models}  # type: ignore[attr-defined]
+    module._TIER_MAPS = {  # type: ignore[attr-defined]
+        Provider.GROK: module._GROK_BY_TIER,
+        Provider.GEMINI: module._GEMINI_BY_TIER,
+        Provider.CODEX: module._CODEX_BY_TIER,
+    }
+
+
+def get_capability(tier: str, provider: str, capability: str) -> bool:
+    """Return a boolean capability flag for a given model tier + provider.
+
+    Args:
+        tier:        ModelTier constant (e.g. ``ModelTier.CODER``).
+        provider:    Provider constant (e.g. ``Provider.GROK``).
+        capability:  Attribute name on ModelDef (e.g. ``"supports_tools"``).
+
+    Returns:
+        ``False`` if the tier/provider is unknown or capability is unrecognised.
+    """
+    try:
+        m = get_model(tier, provider)
+        return bool(getattr(m, capability, False))
+    except KeyError:
+        return False
+