split-stack 0.2.0__py3-none-any.whl

split_stack/model_guide.py

@@ -0,0 +1,273 @@
+"""Model guide: map agent hints and installed models to routing tiers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from split_stack.community_picks import (
+    community_index_for_model,
+    community_note_for_model,
+    recommended_models_for_tier,
+    vram_tier_for_profile,
+)
+from split_stack.hints import list_hints
+from split_stack.model_registry import load_registry, resolve_discovered_models
+from split_stack.routing import route_prompt
+from split_stack.tiering import assign_tiers, describe_tiers
+
+# Example prompts per hint — same spirit as compare POC steps.
+HINT_EXAMPLES: dict[str, str] = {
+    "lookup": "what is JWT in one sentence?",
+    "explain": "compare session cookies vs JWT for a small SaaS API",
+    "design": "design a webhook retry strategy with idempotency keys",
+    "code": "refactor this auth module for unit tests",
+    "reason": "prove this token expiry policy step by step",
+}
+
+TIER_LABELS: dict[str, str] = {
+    "simple": "Simple — fast, cheap steps",
+    "medium": "Medium — summarise and compare",
+    "complex": "Complex — design and heavy generation",
+    "reasoning": "Reasoning — proofs and step-by-step logic",
+    "code": "Code — implement, refactor, debug",
+}
+
+FAMILY_BEST_FOR: dict[str, str] = {
+    "gemma": "Lookup and quick answers; smallest Gemma tag in your stack",
+    "qwen": "General spine — explain on 8B, design on 14B+",
+    "llama": "Lightweight lookup on 1B/3B; mid tiers on 8B+",
+    "phi": "Reasoning and careful step-by-step (especially phi4-reasoning)",
+    "deepseek": "Reasoning (R1) or code (coder) specialists",
+    "mistral": "Solid medium-tier general work",
+    "starcoder": "Code-only slot when present",
+}
+
+
+@dataclass(frozen=True)
+class HintRoute:
+    hint_id: str
+    label: str
+    summary: str
+    tier: str
+    model: str
+    example_prompt: str
+
+
+@dataclass(frozen=True)
+class ModelCard:
+    name: str
+    family: str | None
+    weight: int
+    vram_gb: int | None
+    tier_slots: tuple[str, ...]
+    hints: tuple[str, ...]
+    best_for: str
+    in_stack: bool
+    vram_ok: bool
+    community_note: str | None = None
+    community_hints: tuple[str, ...] = ()
+    installed: bool = True
+    duplicate_locations: tuple[str, ...] = ()
+    status: str = "installed"
+
+
+@dataclass(frozen=True)
+class ModelGuide:
+    stack: tuple[str, ...]
+    tiers: dict[str, str | None]
+    tier_labels: dict[str, str]
+    hint_routes: tuple[HintRoute, ...]
+    models: tuple[ModelCard, ...]
+    vram_tier: str | None = None
+    audit: dict[str, object] | None = None
+    missing_recommended: tuple[str, ...] = ()
+
+
+def _tier_slots_for_model(name: str, tiers: dict[str, str | None]) -> list[str]:
+    slots: list[str] = []
+    for key, value in tiers.items():
+        if value == name:
+            slots.append(key)
+    return slots
+
+
+def _hints_for_model(name: str, hint_routes: tuple[HintRoute, ...]) -> list[str]:
+    return [item.hint_id for item in hint_routes if item.model == name]
+
+
+def _best_for_text(
+    *,
+    name: str,
+    family: str | None,
+    tier_slots: list[str],
+    in_stack: bool,
+    community_note: str | None,
+    community_hints: tuple[str, ...],
+    installed: bool,
+) -> str:
+    parts: list[str] = []
+    if community_note:
+        parts.append(community_note)
+    elif community_hints:
+        parts.append(f"Community pick for: {', '.join(community_hints)}")
+    if not installed:
+        return parts[0] if parts else "Recommended by community — not installed yet"
+
+    lowered = name.lower()
+    if "reasoning" in lowered or "deepseek-r1" in lowered:
+        parts.append("Reasoning steps — proofs and step-by-step logic")
+    elif any(token in lowered for token in ("coder", "codellama", "starcoder")):
+        parts.append("Code steps — refactor, debug, implement")
+    elif family and family in FAMILY_BEST_FOR and not parts:
+        parts.append(FAMILY_BEST_FOR[family])
+
+    if not in_stack:
+        suffix = "Installed but not in your active stack"
+        return f"{parts[0]} — {suffix}" if parts else suffix
+    if "simple" in tier_slots:
+        parts.append("Routed for lookup hints")
+    elif "medium" in tier_slots and "complex" not in tier_slots:
+        parts.append("Routed for explain hints")
+    elif "complex" in tier_slots:
+        parts.append("Routed for design/code hints")
+    elif "reasoning" in tier_slots:
+        parts.append("Routed for reason hints")
+    return " · ".join(dict.fromkeys(p for p in parts if p))
+
+
+def build_model_guide(
+    stack: list[str],
+    *,
+    pool: list[str] | None = None,
+    config_path: str | None = None,
+    profile: str = "workstation_12gb",
+) -> ModelGuide:
+    """Build hint routes for the active stack and cards for all models in pool."""
+    if not stack:
+        raise ValueError("stack must contain at least one model")
+
+    registry = load_registry(config_path)
+    vram_tier = vram_tier_for_profile(profile, config_path=config_path)
+    from split_stack.discovery import audit_model_folders, model_locations_by_tag
+
+    locations = model_locations_by_tag()
+    audit = audit_model_folders()
+    recommended = recommended_models_for_tier(vram_tier=vram_tier, config_path=config_path)
+    tiers_map = assign_tiers(stack, registry=registry)
+    tiers = describe_tiers(tiers_map)
+
+    hint_routes: list[HintRoute] = []
+    for item in list_hints():
+        hint_id = item["id"]
+        example = HINT_EXAMPLES.get(hint_id, item["summary"])
+        tier, model = route_prompt(example, tiers_map, hint=hint_id)
+        hint_routes.append(
+            HintRoute(
+                hint_id=hint_id,
+                label=item["label"],
+                summary=item["summary"],
+                tier=tier.value,
+                model=model,
+                example_prompt=example,
+            )
+        )
+    hint_routes_tuple = tuple(hint_routes)
+
+    catalog = pool if pool is not None else stack
+    resolved = resolve_discovered_models(sorted(set(catalog)), registry=registry)
+    stack_set = set(stack)
+    seen_names: set[str] = set()
+
+    full_tiers = describe_tiers(assign_tiers(list(catalog), registry=registry)) if len(catalog) >= 2 else tiers
+
+    cards: list[ModelCard] = []
+    for item in resolved:
+        seen_names.add(item.name)
+        in_stack = item.name in stack_set
+        tier_slots = _tier_slots_for_model(item.name, tiers if in_stack else full_tiers)
+        route_hints = _hints_for_model(item.name, hint_routes_tuple) if in_stack else []
+        comm_hints = community_index_for_model(item.name, vram_tier=vram_tier, config_path=config_path)
+        comm_note = community_note_for_model(item.name, vram_tier=vram_tier, config_path=config_path)
+        locs = locations.get(item.name, ())
+        cards.append(
+            ModelCard(
+                name=item.name,
+                family=item.family,
+                weight=item.weight,
+                vram_gb=item.vram_gb,
+                tier_slots=tuple(tier_slots),
+                hints=tuple(route_hints),
+                best_for=_best_for_text(
+                    name=item.name,
+                    family=item.family,
+                    tier_slots=tier_slots,
+                    in_stack=in_stack,
+                    community_note=comm_note,
+                    community_hints=comm_hints,
+                    installed=True,
+                ),
+                in_stack=in_stack,
+                vram_ok=item.vram_ok,
+                community_note=comm_note,
+                community_hints=comm_hints,
+                installed=True,
+                duplicate_locations=tuple(locs) if len(locs) > 1 else (),
+                status="duplicate" if len(locs) > 1 else "installed",
+            )
+        )
+
+    installed_lower = {name.lower() for name in seen_names}
+    missing: list[str] = []
+    for model_name, note in recommended.items():
+        if model_name.lower() in installed_lower:
+            continue
+        if any(model_name.lower() in name or name.startswith(model_name.lower()) for name in installed_lower):
+            continue
+        missing.append(model_name)
+        comm_hints = community_index_for_model(model_name, vram_tier=vram_tier, config_path=config_path)
+        cards.append(
+            ModelCard(
+                name=model_name,
+                family=model_name.split(":")[0],
+                weight=0,
+                vram_gb=None,
+                tier_slots=(),
+                hints=(),
+                best_for=_best_for_text(
+                    name=model_name,
+                    family=model_name.split(":")[0],
+                    tier_slots=[],
+                    in_stack=False,
+                    community_note=note,
+                    community_hints=comm_hints,
+                    installed=False,
+                ),
+                in_stack=False,
+                vram_ok=True,
+                community_note=note,
+                community_hints=comm_hints,
+                installed=False,
+                status="recommended",
+            )
+        )
+
+    cards.sort(
+        key=lambda card: (
+            card.status != "installed",
+            card.status == "recommended",
+            not card.in_stack,
+            card.weight,
+            card.name,
+        )
+    )
+
+    return ModelGuide(
+        stack=tuple(stack),
+        tiers=tiers,
+        tier_labels=dict(TIER_LABELS),
+        hint_routes=hint_routes_tuple,
+        models=tuple(cards),
+        vram_tier=vram_tier,
+        audit=audit,
+        missing_recommended=tuple(missing),
+    )

split_stack/model_registry.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_ASSUMED_VRAM_GB = 12
+DEFAULT_DEPLOYMENT_PROFILE = "workstation_12gb"
+
+
+@dataclass(frozen=True)
+class DeploymentProfileSpec:
+    name: str
+    assumed_vram_gb: int | None
+    apply_vram_filter: bool
+    description: str
+
+
+DEPLOYMENT_PROFILES: dict[str, DeploymentProfileSpec] = {
+    "workstation_8gb": DeploymentProfileSpec(
+        name="workstation_8gb",
+        assumed_vram_gb=8,
+        apply_vram_filter=True,
+        description="8 GB GPU workstation preset",
+    ),
+    "workstation_12gb": DeploymentProfileSpec(
+        name="workstation_12gb",
+        assumed_vram_gb=12,
+        apply_vram_filter=True,
+        description="12 GB GPU workstation preset (default)",
+    ),
+    "workstation_16gb": DeploymentProfileSpec(
+        name="workstation_16gb",
+        assumed_vram_gb=16,
+        apply_vram_filter=True,
+        description="16 GB GPU workstation preset",
+    ),
+    "workstation_24gb": DeploymentProfileSpec(
+        name="workstation_24gb",
+        assumed_vram_gb=24,
+        apply_vram_filter=True,
+        description="24 GB GPU workstation preset (4090, 3090 class)",
+    ),
+    "workstation_32gb": DeploymentProfileSpec(
+        name="workstation_32gb",
+        assumed_vram_gb=32,
+        apply_vram_filter=True,
+        description="32 GB GPU workstation preset (5090 class; top single-GPU tier)",
+    ),
+    "datacenter": DeploymentProfileSpec(
+        name="datacenter",
+        assumed_vram_gb=None,
+        apply_vram_filter=False,
+        description="Private inference fleet; custom model catalog, no VRAM filter",
+    ),
+}
+
+_PROFILE_ALIASES: dict[str, str] = {
+    "workstation": DEFAULT_DEPLOYMENT_PROFILE,
+    "8gb": "workstation_8gb",
+    "12gb": "workstation_12gb",
+    "16gb": "workstation_16gb",
+    "24gb": "workstation_24gb",
+    "32gb": "workstation_32gb",
+}
+
+_BUILTIN_RAW: list[dict[str, object]] = [
+    {"match": "gemma4:e4b", "weight": 4000, "vram_gb": 4, "family": "gemma"},
+    {"match": "gemma4:12b", "weight": 12000, "vram_gb": 10, "family": "gemma"},
+    {"match": "gemma4:26b-a4b", "weight": 26000, "vram_gb": 20, "family": "gemma"},
+    {"match": "gemma4:26b", "weight": 26000, "vram_gb": 22, "family": "gemma"},
+    {"match": "gemma4:31b", "weight": 31000, "vram_gb": 28, "family": "gemma"},
+    {"match": "gemma3:4b", "weight": 4000, "vram_gb": 4, "family": "gemma"},
+    {"match": "gemma3:12b", "weight": 12000, "vram_gb": 10, "family": "gemma"},
+    {"match": "qwen3:4b", "weight": 4000, "vram_gb": 4, "family": "qwen"},
+    {"match": "qwen3:8b", "weight": 8000, "vram_gb": 6, "family": "qwen"},
+    {"match": "qwen3:14b", "weight": 14000, "vram_gb": 10, "family": "qwen"},
+    {"match": "qwen3:30b", "weight": 30000, "vram_gb": 20, "family": "qwen"},
+    {"match": "qwen3:30b-a3b", "weight": 30000, "vram_gb": 20, "family": "qwen"},
+    {"match": "llama3.2:1b", "weight": 1000, "vram_gb": 2, "family": "llama"},
+    {"match": "llama3.2:3b", "weight": 3000, "vram_gb": 3, "family": "llama"},
+    {"match": "llama3.1:8b", "weight": 8000, "vram_gb": 6, "family": "llama"},
+    {"match": "llama3.1:70b", "weight": 70000, "vram_gb": 48, "family": "llama"},
+    {"match": "mistral:7b", "weight": 7000, "vram_gb": 5, "family": "mistral"},
+    {"match": "mistral-nemo", "weight": 12000, "vram_gb": 8, "family": "mistral"},
+    {"match": "phi3:mini", "weight": 3800, "vram_gb": 4, "family": "phi"},
+    {"match": "phi4", "weight": 14000, "vram_gb": 10, "family": "phi"},
+    {"match": "phi4-reasoning", "weight": 14000, "vram_gb": 10, "family": "phi"},
+    {"match": "deepseek-coder:6.7b", "weight": 7000, "vram_gb": 6, "family": "deepseek"},
+    {"match": "deepseek-r1", "weight": 14000, "vram_gb": 10, "family": "deepseek"},
+    {"match": "deepseek-coder", "weight": 7000, "vram_gb": 6, "family": "deepseek"},
+    {"match": "codellama", "weight": 7000, "vram_gb": 6, "family": "llama"},
+    {"match": "starcoder2", "weight": 7000, "vram_gb": 6, "family": "starcoder"},
+    {"match": ":e4b", "weight": 4000, "vram_gb": 4, "family": "gemma"},
+    {"match": ":e2b", "weight": 2000, "vram_gb": 3, "family": "gemma"},
+]
+
+
+@dataclass(frozen=True)
+class ModelEntry:
+    match: str
+    weight: int
+    vram_gb: int | None = None
+    family: str | None = None
+
+
+@dataclass(frozen=True)
+class ModelRegistry:
+    profile: str
+    assumed_vram_gb: int | None
+    apply_vram_filter: bool
+    entries: tuple[ModelEntry, ...]
+
+
+@dataclass(frozen=True)
+class ResolvedModel:
+    name: str
+    weight: int
+    vram_gb: int | None
+    family: str | None
+    vram_ok: bool
+    source: str
+    quant_mode: str | None = None
+
+
+def _entries_from_raw(raw: list[dict[str, object]]) -> tuple[ModelEntry, ...]:
+    return tuple(
+        ModelEntry(
+            match=str(item["match"]),
+            weight=int(item["weight"]),  # type: ignore[arg-type]
+            vram_gb=int(item["vram_gb"]) if item.get("vram_gb") is not None else None,
+            family=str(item["family"]) if item.get("family") else None,
+        )
+        for item in raw
+    )
+
+
+def normalize_deployment_profile(name: str | None) -> str:
+    if not name:
+        return DEFAULT_DEPLOYMENT_PROFILE
+    lowered = name.strip().lower()
+    if lowered in DEPLOYMENT_PROFILES:
+        return lowered
+    if lowered in _PROFILE_ALIASES:
+        return _PROFILE_ALIASES[lowered]
+    valid = ", ".join(sorted(DEPLOYMENT_PROFILES))
+    raise ValueError(f"Unknown deployment profile '{name}'. Valid profiles: {valid}")
+
+
+def list_deployment_profiles() -> tuple[DeploymentProfileSpec, ...]:
+    return tuple(DEPLOYMENT_PROFILES[name] for name in sorted(DEPLOYMENT_PROFILES))
+
+
+def _default_registry() -> ModelRegistry:
+    spec = DEPLOYMENT_PROFILES[DEFAULT_DEPLOYMENT_PROFILE]
+    return ModelRegistry(
+        profile=spec.name,
+        assumed_vram_gb=spec.assumed_vram_gb,
+        apply_vram_filter=spec.apply_vram_filter,
+        entries=_entries_from_raw(_BUILTIN_RAW),
+    )
+
+
+def _registry_from_payload(
+    payload: dict[str, object],
+    *,
+    profile_override: str | None = None,
+) -> ModelRegistry:
+    profile_name = normalize_deployment_profile(
+        profile_override
+        or str(payload.get("deployment_profile") or payload.get("profile") or "")
+        or None
+    )
+    spec = DEPLOYMENT_PROFILES[profile_name]
+    entries_raw = payload.get("models")
+    entries = _entries_from_raw(list(entries_raw)) if entries_raw else _entries_from_raw(_BUILTIN_RAW)
+    if spec.apply_vram_filter:
+        if profile_override:
+            assumed_vram_gb = spec.assumed_vram_gb
+        else:
+            assumed = payload.get("assumed_vram_gb")
+            assumed_vram_gb = int(assumed) if assumed is not None else spec.assumed_vram_gb
+    else:
+        assumed_vram_gb = None
+    return ModelRegistry(
+        profile=profile_name,
+        assumed_vram_gb=assumed_vram_gb,
+        apply_vram_filter=spec.apply_vram_filter,
+        entries=entries,
+    )
+
+
+def config_search_paths(explicit: str | None = None) -> list[Path]:
+    paths: list[Path] = []
+    if explicit:
+        paths.append(Path(explicit))
+    env_path = os.environ.get("SPLIT_STACK_MODELS_CONFIG")
+    if env_path:
+        paths.append(Path(env_path))
+    paths.extend(
+        [
+            Path.cwd() / "split-stack.models.json",
+            Path.home() / ".config" / "split-stack" / "models.json",
+        ]
+    )
+    return paths
+
+
+def load_registry(
+    config_path: str | None = None,
+    *,
+    profile: str | None = None,
+) -> ModelRegistry:
+    for path in config_search_paths(config_path):
+        if path.is_file():
+            payload = json.loads(path.read_text(encoding="utf-8-sig"))
+            return _registry_from_payload(payload, profile_override=profile)
+    if profile:
+        spec = DEPLOYMENT_PROFILES[normalize_deployment_profile(profile)]
+        base = _default_registry()
+        return ModelRegistry(
+            profile=spec.name,
+            assumed_vram_gb=spec.assumed_vram_gb,
+            apply_vram_filter=spec.apply_vram_filter,
+            entries=base.entries,
+        )
+    return _default_registry()
+
+
+def _heuristic_weight(name: str) -> int:
+    lowered = name.lower()
+    match = re.search(r":(\d+)b", lowered)
+    if match:
+        return int(match.group(1)) * 1000
+    match = re.search(r":e(\d+)b", lowered)
+    if match:
+        return int(match.group(1)) * 1000
+    if "70b" in lowered:
+        return 70000
+    if "30b" in lowered or "32b" in lowered or "34b" in lowered:
+        return 30000
+    return 1000
+
+
+def infer_model_profile(
+    name: str,
+    registry: ModelRegistry | None = None,
+    *,
+    quant_mode: str | None = None,
+) -> ResolvedModel:
+    reg = registry or _default_registry()
+    lowered = name.lower()
+    best: ModelEntry | None = None
+    best_len = -1
+    for entry in reg.entries:
+        token = entry.match.lower()
+        if token in lowered and len(token) > best_len:
+            best = entry
+            best_len = len(token)
+    if best is not None:
+        vram_gb = best.vram_gb
+        source = "registry"
+        weight = best.weight
+        family = best.family
+    else:
+        source = "heuristic"
+        weight = _heuristic_weight(name)
+        family = _guess_family(name)
+        vram_gb = max(3, weight // 1000)
+    from split_stack.quantization import adjust_vram_for_quant, normalize_quant_mode
+
+    mode = normalize_quant_mode(quant_mode)
+    effective_vram = adjust_vram_for_quant(name, vram_gb, mode)
+    if not reg.apply_vram_filter or reg.assumed_vram_gb is None:
+        vram_ok = True
+    else:
+        vram_ok = effective_vram is None or effective_vram <= reg.assumed_vram_gb
+    return ResolvedModel(
+        name=name,
+        weight=weight,
+        vram_gb=effective_vram,
+        family=family,
+        vram_ok=vram_ok,
+        source=source,
+        quant_mode=mode if mode != "default" else None,
+    )
+
+
+def _guess_family(name: str) -> str | None:
+    lowered = name.lower()
+    for family in ("qwen", "gemma", "llama", "mistral", "phi", "deepseek"):
+        if family in lowered:
+            return family
+    return None
+
+
+def resolve_discovered_models(
+    model_names: list[str],
+    *,
+    registry: ModelRegistry | None = None,
+    only_vram_ok: bool = False,
+    quant_mode: str | None = None,
+) -> list[ResolvedModel]:
+    reg = registry or _default_registry()
+    resolved = [infer_model_profile(name, reg, quant_mode=quant_mode) for name in model_names]
+    if only_vram_ok:
+        resolved = [item for item in resolved if item.vram_ok]
+    return sorted(resolved, key=lambda item: item.weight)
+
+
+def model_weight(name: str, registry: ModelRegistry | None = None) -> int:
+    return infer_model_profile(name, registry).weight

split_stack/models.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ComplexityTier(str, Enum):
+    SIMPLE = "simple"
+    MEDIUM = "medium"
+    COMPLEX = "complex"
+    REASONING = "reasoning"
+
+
+class StepKind(str, Enum):
+    LOOKUP = "lookup"
+    EXPLAIN = "explain"
+    DESIGN = "design"
+    CODE = "code"
+    REASON = "reason"
+    # Deprecated aliases (still parse)
+    WORK = "work"
+    BUILD = "build"
+
+
+@dataclass(frozen=True)
+class TierMap:
+    simple: str
+    medium: str
+    complex: str
+    reasoning: str
+    code: str | None = None
+
+    def for_tier(self, tier: ComplexityTier) -> str:
+        lookup = {
+            ComplexityTier.SIMPLE: self.simple,
+            ComplexityTier.MEDIUM: self.medium,
+            ComplexityTier.COMPLEX: self.complex,
+            ComplexityTier.REASONING: self.reasoning,
+        }
+        return lookup[tier]
+
+
+@dataclass(frozen=True)
+class RouteDecision:
+    """Full routing outcome for logging, CLI explain, and agent-loop telemetry."""
+
+    tier: ComplexityTier
+    model: str
+    hint: str | None
+    step_kind: str | None
+    tier_source: str
+    model_source: str
+    reasons: tuple[str, ...]
+    tiers: dict[str, str | None]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "tier": self.tier.value,
+            "model": self.model,
+            "hint": self.hint,
+            "step_kind": self.step_kind,
+            "tier_source": self.tier_source,
+            "model_source": self.model_source,
+            "reasons": list(self.reasons),
+            "tiers": self.tiers,
+        }
+
+    def as_tuple(self) -> tuple[ComplexityTier, str]:
+        return self.tier, self.model
+
+
+@dataclass(frozen=True)
+class StackAdvice:
+    cursor_model: str
+    prose_path: str
+    local_path: str
+    warn_cursor_override: bool

split_stack/ollama_errors.py

@@ -0,0 +1,30 @@
+"""Actionable error messages for Ollama HTTP failures."""
+
+from __future__ import annotations
+
+
+def format_ollama_error(
+    exc: BaseException,
+    *,
+    model: str,
+    base_url: str = "http://127.0.0.1:11434",
+) -> str:
+    """Turn requests/Ollama failures into short fix hints."""
+    try:
+        import requests
+    except ImportError:
+        return str(exc)
+
+    if isinstance(exc, requests.Timeout):
+        return f"Ollama request timed out for model '{model}' at {base_url}."
+
+    if isinstance(exc, requests.ConnectionError):
+        return f"Ollama not reachable at {base_url}. Start Ollama first."
+
+    if isinstance(exc, requests.HTTPError) and exc.response is not None:
+        status = exc.response.status_code
+        if status == 404:
+            return f"Model '{model}' not found. Run: ollama pull {model}"
+        return f"Ollama HTTP {status} for model '{model}': {exc.response.reason}"
+
+    return str(exc)