marketmyna 0.2.0__py3-none-any.whl

marketmyna/llm/litellm_backend.py

@@ -0,0 +1,197 @@
+"""LiteLLM-backed GenerationBackend.
+
+litellm itself is imported lazily, inside generate(), not at module
+scope - this backend's class definition, backend_id and capabilities
+must stay importable even when litellm isn't installed (e.g. this
+sandbox), so callers that never actually invoke generate() (config
+listing, backend_registry resolution, tests) don't crash on import.
+
+litellm reaches every provider - OpenAI, Anthropic, Gemini, and local
+Ollama alike - through one model-string convention (e.g. "gpt-4o-mini",
+"claude-3-5-sonnet-20241022", "ollama/qwen3:8b"), which is why there is
+no separate "Ollama backend" class here, matching daily_stock_analysis's
+own design: Ollama is just a litellm model string plus llm_api_base
+pointed at the local server.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional
+
+from .protocol import (
+    GenerationCapabilities,
+    GenerationConfig,
+    GenerationError,
+    GenerationErrorCode,
+    GenerationResult,
+)
+
+# How providers say a model is gone (retired, renamed, or not offered to this
+# key): Gemini "no longer available to new users" / "is not found for API
+# version", Groq / OpenAI "model_not_found", "decommissioned", ...
+_MODEL_GONE = (
+    "no longer available", "model_not_found", "model not found", "does not exist", "decommissioned",
+    "has been deprecated", "is deprecated", "is not found for api version", "not supported for generatecontent",
+    "unknown model", "invalid model", "no endpoints found", "is not a valid model",
+)
+
+
+def model_unavailable(exception_name: str, message: str) -> bool:
+    """True when an error says the model itself is unusable, not the key,
+    a quota or the network."""
+    name, message = exception_name.lower(), message.lower()
+    if any(phrase in message for phrase in _MODEL_GONE):
+        return True
+    return "notfound" in name and "model" in message
+
+
+class LiteLLMGenerationBackend:
+    backend_id = "litellm"
+    capabilities = GenerationCapabilities(
+        supports_json=True,
+        supports_tools=True,
+        supports_stream=False,  # not implemented in this phase, see protocol.py
+        supports_vision=False,
+        supports_health_check=False,
+        supports_smoke_test=False,
+    )
+
+    def __init__(self, config):
+        self._model = getattr(config, "llm_model", None)
+        self._api_base = getattr(config, "llm_api_base", None)
+        self._api_key = getattr(config, "llm_api_key", None)
+        self._default_timeout = getattr(config, "llm_timeout_seconds", 60.0)
+        self._default_max_tokens = getattr(config, "llm_max_tokens", 2048)
+        self._default_temperature = getattr(config, "llm_temperature", 0.7)
+
+    def generate(
+        self,
+        prompt: str,
+        generation_config: GenerationConfig,
+        *,
+        system_prompt: Optional[str] = None,
+        stream: bool = False,
+        stream_progress_callback: Optional[Callable[[str], None]] = None,
+    ) -> GenerationResult:
+        if stream:
+            raise GenerationError(
+                GenerationErrorCode.INVALID_RESPONSE,
+                "LiteLLMGenerationBackend does not implement streaming yet",
+                stage="generate",
+                retryable=False,
+                fallbackable=False,
+                backend=self.backend_id,
+            )
+
+        model = generation_config.model or self._model
+        if not model:
+            raise GenerationError(
+                GenerationErrorCode.BACKEND_NOT_CONFIGURED,
+                "No llm_model configured",
+                stage="setup",
+                retryable=False,
+                fallbackable=False,
+                backend=self.backend_id,
+            )
+
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": prompt})
+
+        try:
+            import litellm
+        except ImportError as exc:
+            raise GenerationError(
+                GenerationErrorCode.BACKEND_NOT_CONFIGURED,
+                "litellm is not installed",
+                stage="setup",
+                retryable=False,
+                fallbackable=False,
+                backend=self.backend_id,
+                details={"import_error": str(exc)},
+            ) from exc
+
+        try:
+            response = litellm.completion(
+                model=model,
+                messages=messages,
+                api_base=self._api_base,
+                api_key=self._api_key,
+                timeout=generation_config.timeout or self._default_timeout,
+                max_tokens=generation_config.max_tokens or self._default_max_tokens,
+                temperature=(
+                    generation_config.temperature
+                    if generation_config.temperature is not None
+                    else self._default_temperature
+                ),
+            )
+        except Exception as exc:  # noqa: BLE001 - normalized into GenerationError below
+            raise self._wrap_exception(exc, model)
+
+        return self._to_result(response, model)
+
+    def _wrap_exception(self, exc: Exception, model: str) -> GenerationError:
+        name = type(exc).__name__.lower()
+        message = str(exc).lower()
+
+        if "timeout" in name or "timeout" in message:
+            code, retryable = GenerationErrorCode.TIMEOUT, True
+        elif "rate" in name or "rate limit" in message or "429" in message:
+            code, retryable = GenerationErrorCode.RATE_LIMITED, True
+        elif model_unavailable(name, message):
+            code, retryable = GenerationErrorCode.MODEL_UNAVAILABLE, False
+        elif "auth" in name or "api key" in message or "401" in message or "403" in message:
+            code, retryable = GenerationErrorCode.AUTH_FAILED, False
+        elif "connection" in name or "connect" in message:
+            code, retryable = GenerationErrorCode.UNKNOWN, True
+        else:
+            code, retryable = GenerationErrorCode.UNKNOWN, False
+
+        return GenerationError(
+            code,
+            str(exc),
+            stage="call",
+            retryable=retryable,
+            fallbackable=True,
+            backend=self.backend_id,
+            provider=model.split("/")[0] if "/" in model else None,
+            details={"exception_type": type(exc).__name__},
+        )
+
+    def _to_result(self, response, model: str) -> GenerationResult:
+        try:
+            choice = response.choices[0]
+            text = choice.message.content or ""
+        except (AttributeError, IndexError) as exc:
+            raise GenerationError(
+                GenerationErrorCode.INVALID_RESPONSE,
+                "litellm response missing choices[0].message.content",
+                stage="parse",
+                retryable=False,
+                fallbackable=True,
+                backend=self.backend_id,
+                details={"raw_type": type(response).__name__},
+            ) from exc
+
+        usage = {}
+        raw_usage = getattr(response, "usage", None)
+        if raw_usage is not None:
+            usage = {
+                "prompt_tokens": getattr(raw_usage, "prompt_tokens", None),
+                "completion_tokens": getattr(raw_usage, "completion_tokens", None),
+                "total_tokens": getattr(raw_usage, "total_tokens", None),
+            }
+
+        provider = model.split("/")[0] if "/" in model else "unknown"
+        response_model = getattr(response, "model", None) or model
+
+        return GenerationResult(
+            text=text,
+            model=response_model,
+            provider=provider,
+            backend=self.backend_id,
+            usage=usage,
+            raw=response,
+            diagnostics={},
+        )

marketmyna/llm/model_catalog.py

@@ -0,0 +1,166 @@
+"""Picks models from a provider's live model list instead of hard-coded
+names that go stale when providers retire models.
+
+- recommend(provider, ids): the model to suggest for a new key or a fresh
+  setup - a fast, cheap, capable one (e.g. the newest stable Gemini Flash).
+- suggest_replacement(model, ids): when `model` has been retired, the closest
+  current model of the same family and tier (Flash -> newer Flash, never Pro,
+  so costs don't jump), else recommend().
+
+Preferences below are name *patterns*, not versions, so a new release
+(gemini-4-flash, gpt-6-mini) is picked up without a code change. Ids are
+bare provider ids ("gemini-3-flash"); callers add the litellm prefix.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Optional
+
+# Per provider, best first. Within a pattern the newest stable version wins.
+# Aliases the provider keeps pointing at its current model come first where
+# they exist: a listed but closed model (Gemini lists 2.5 Flash, yet refuses it
+# to new keys) can't be told apart from a working one by the list alone.
+PREFERRED_PATTERNS: dict[str, list[str]] = {
+    "gemini": [r"gemini-flash-latest", r"gemini-[\d.]+-flash", r"gemini-[\d.]+-flash-preview(-[\w-]+)?",
+               r"gemini-flash-lite-latest", r"gemini-[\d.]+-flash-lite"],
+    "groq": [r"openai/gpt-oss-120b", r"llama-[\d.]+-\d+b-versatile", r"meta-llama/llama-[\d.]+-.*instruct",
+             r"openai/gpt-oss-20b", r"llama-[\d.]+-\d+b-instant"],
+    "openai": [r"gpt-[\d.]+-mini", r"gpt-4o-mini"],
+    "anthropic": [r"claude-haiku-[\d-]+", r"claude-[\d-]+-haiku(-\d+)?", r"claude-sonnet-[\d-]+"],
+    "mistral": [r"mistral-small-latest", r"mistral-medium-latest", r"mistral-large-latest"],
+    "deepseek": [r"deepseek-chat"],
+    "cerebras": [r"gpt-oss-120b", r"llama-[\d.]+-70b", r"qwen-[\d.]+-\d+b(-[\w-]+)?", r"llama[\d.]+-\d+b"],
+    "nvidia_nim": [r"openai/gpt-oss-120b", r"meta/llama-[\d.]+-70b-instruct", r"meta/llama-[\d.]+-\d+b-instruct"],
+    "openrouter": [r"openai/gpt-[\d.]+-mini", r"google/gemini-[\d.]+-flash", r"anthropic/claude-haiku-[\d.-]+"],
+}
+
+# Words that tell a model's size/price tier; a replacement keeps the same set.
+TIER_WORDS = {
+    "lite", "mini", "nano", "flash", "pro", "ultra", "haiku", "sonnet", "opus", "small", "medium", "large",
+    "instant", "versatile", "chat", "reasoner", "turbo", "max", "plus",
+}
+UNSTABLE_WORDS = {"preview", "exp", "experimental", "beta", "alpha"}
+# Not for text generation, even if a provider's list says otherwise.
+NON_TEXT_WORDS = {
+    "tts", "image", "imagen", "embedding", "embed", "live", "audio", "vision", "native", "transcribe",
+    "whisper", "guard", "moderation", "veo", "robotics", "computer", "search", "realtime", "dall",
+}
+
+
+def bare(model: str) -> str:
+    """'gemini/gemini-3-flash' -> 'gemini-3-flash'; OpenRouter / Groq ids keep
+    their own vendor part ('groq/openai/gpt-oss-120b' -> 'openai/gpt-oss-120b')."""
+    return model.split("/", 1)[1] if "/" in model else model
+
+
+def _words(model_id: str) -> list[str]:
+    return [w for w in re.split(r"[^a-z]+", model_id.lower()) if w]
+
+
+def _version(model_id: str) -> tuple[int, ...]:
+    """Numbers in the name, sizes like '70b' and dates left out:
+    'gemini-2.5-flash' -> (2, 5); 'claude-haiku-4-5-20251001' -> (4, 5)."""
+    name = model_id.lower().rsplit("/", 1)[-1]
+    # Numbers after "preview" / "exp" are release dates ("-preview-09-2025").
+    name = re.split(r"[-_.](?:%s)(?:[-_.]|$)" % "|".join(UNSTABLE_WORDS), name)[0]
+    nums = re.findall(r"(?<![a-z])(\d+(?:\.\d+)*)(?![a-z\d])", name)
+    out: list[int] = []
+    for n in nums:
+        if len(n) >= 4:  # a year or date stamp, not a version
+            continue
+        out.extend(int(p) for p in n.split(".") if p)
+    return tuple(out)
+
+
+def _unstable(model_id: str) -> bool:
+    return bool(set(_words(model_id)) & UNSTABLE_WORDS)
+
+
+def is_text_model(model_id: str) -> bool:
+    return not (set(_words(model_id)) & NON_TEXT_WORDS)
+
+
+def _rank_key(model_id: str) -> tuple:
+    # Stable before preview; newer version first; shorter (plain) names first.
+    return (_unstable(model_id), tuple(-v for v in _version(model_id)), len(model_id), model_id)
+
+
+def recommend(provider: str, ids: Iterable[str], exclude: Iterable[str] = ()) -> Optional[str]:
+    """Best model id for `provider` among `ids` (bare ids), or None."""
+    skip = {bare(x) if "/" in x and x.split("/", 1)[0] == provider else x for x in exclude}
+    pool = [i for i in dict.fromkeys(ids) if i and i not in skip and is_text_model(i)]
+    for pattern in PREFERRED_PATTERNS.get(provider, []):
+        rx = re.compile(rf"^{pattern}$", re.I)
+        hits = [i for i in pool if rx.match(i)]
+        if hits:
+            return sorted(hits, key=_rank_key)[0]
+    return None
+
+
+def suggest_replacement(model: str, ids: Iterable[str], exclude: Iterable[str] = ()) -> Optional[str]:
+    """Closest current model to a retired `model` (litellm id), as a litellm id.
+
+    Same family (first word) and the same tier words, never an older version;
+    a concrete newer stable release beats the provider's '-latest' alias,
+    which beats a newer preview. Nothing like it -> recommend() for the
+    provider. None when the list offers nothing usable."""
+    provider = model.split("/", 1)[0] if "/" in model else ""
+    old = bare(model)
+    skip = {old} | {bare(x) for x in exclude}
+    pool = [i for i in dict.fromkeys(ids) if i and i not in skip and is_text_model(i)]
+    words = _words(old)
+    family = words[0] if words else ""
+    tiers = set(words) & TIER_WORDS
+    old_version = _version(old)
+
+    def same_kind(i: str) -> bool:
+        w = _words(i)
+        return bool(w) and w[0] == family and (set(w) & TIER_WORDS) == tiers
+
+    alike = [i for i in pool if same_kind(i)]
+    newer = [i for i in alike if _version(i) and _version(i) > old_version]
+    stable = sorted([i for i in newer if not _unstable(i)], key=_rank_key)
+    alias = sorted([i for i in alike if "latest" in _words(i)], key=len)
+    preview = sorted([i for i in newer if _unstable(i)], key=_rank_key)
+    pick = (stable or alias or preview or [None])[0]
+    if pick is None:
+        pick = recommend(provider, pool) if provider else None
+    if pick is None:
+        return None
+    return f"{provider}/{pick}" if provider else pick
+
+
+def tier_of(model_id: str) -> tuple:
+    """Family and tier: ('gemini', {'flash', 'lite'}); sizes ('70b') count too."""
+    w = _words(model_id.rsplit("/", 1)[-1])
+    return (w[0] if w else "", frozenset(set(w) & TIER_WORDS), _size(model_id))
+
+
+def _size(model_id: str) -> tuple[str, ...]:
+    return tuple(re.findall(r"(?<![a-z\d])(\d+b)(?![a-z])", model_id.lower()))
+
+
+def superseded(ids: Iterable[str]) -> set[str]:
+    """Ids a newer stable release of the same family, tier and size replaces
+    (gemini-2.0-flash when gemini-2.5-flash is listed; a preview once its
+    version is out as stable). Aliases and unversioned ids are never hidden."""
+    pool = [i for i in dict.fromkeys(ids) if i]
+    kinds: dict[str, tuple] = {}
+    for i in pool:
+        w = _words(i)
+        kinds[i] = (w[0] if w else "", frozenset(set(w) & TIER_WORDS), _size(i))
+    out = set()
+    for i in pool:
+        v = _version(i)
+        if not v or "latest" in _words(i):
+            continue
+        for j in pool:
+            if j == i or kinds[j] != kinds[i] or _unstable(j) or not _version(j):
+                continue
+            vj = _version(j)
+            if vj > v or (vj == v and _unstable(i)):
+                out.add(i)
+                break
+    return out
+

marketmyna/llm/model_health.py

@@ -0,0 +1,193 @@
+"""Notices when an AI provider retires a configured model, and keeps AI
+working until someone fixes the setting.
+
+Runtime healing (FailoverGenerationBackend): a call failing with "model
+not found / no longer available" makes the backend ask the provider which
+models the key can use, pick the closest current one
+(model_catalog.suggest_replacement: Flash -> newer Flash, never Pro) and
+retry with it. A working replacement is remembered, so later calls go
+straight to it.
+- Platform models (Settings -> AI): the saved setting is NOT changed;
+  the owner is told once (log + system-error channels) to set it.
+- A user's own key (BYOK): the key's saved model is updated directly.
+
+State is kept in <app_dir>/ai_models.json.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+from marketmyna.core.home import app_home
+
+from .model_catalog import bare, suggest_replacement
+from .store import clean_error, error_kind
+
+logger = logging.getLogger(__name__)
+
+STATE_NAME = "ai_models.json"
+LIST_TTL_SECONDS = 3600.0
+# Replacements tried for one retired model before giving up.
+MAX_TRIES = 3
+
+_lock = threading.Lock()
+_cache: dict[str, tuple[float, dict]] = {}
+_lists: dict[tuple[str, str, Optional[str]], tuple[float, list[str]]] = {}
+
+
+# ---------------------------------------------------------------- state
+def _state_file(config) -> Path:
+    return Path(getattr(config, "app_dir", None) or app_home()) / STATE_NAME
+
+
+def load(config) -> dict:
+    path = _state_file(config)
+    try:
+        mtime = path.stat().st_mtime
+    except OSError:
+        return {"checked_at": None, "models": {}}
+    hit = _cache.get(str(path))
+    if hit and hit[0] == mtime:
+        return json.loads(json.dumps(hit[1]))
+    try:
+        state = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        state = {}
+    state = {"checked_at": state.get("checked_at"), "models": state.get("models") or {}}
+    _cache[str(path)] = (mtime, state)
+    return json.loads(json.dumps(state))
+
+
+def _save(config, state: dict) -> None:
+    path = _state_file(config)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(state, indent=1, sort_keys=True), encoding="utf-8")
+    os.replace(tmp, path)
+    _cache.pop(str(path), None)
+
+
+def _now() -> str:
+    return datetime.now().isoformat(timespec="seconds")
+
+
+def substitute(config, model: str) -> Optional[str]:
+    """The working replacement for a retired platform model, if one was found."""
+    entry = load(config)["models"].get(model) or {}
+    if entry.get("status") == "unavailable" and entry.get("replacement") and entry.get("replacement_ok"):
+        return entry["replacement"]
+    return None
+
+
+# ---------------------------------------------------------------- provider lists
+def available_ids(provider: Optional[str], key: Optional[str], api_base: Optional[str] = None,
+                  fresh: bool = False) -> Optional[list[str]]:
+    """Bare model ids the key can use, or None when the list can't be had."""
+    from .providers import PROVIDER_IDS, list_models
+
+    if not provider or provider not in PROVIDER_IDS:
+        return None
+    if not key and provider not in ("openrouter", "ollama"):
+        return None
+    cache_key = (provider, key or "", api_base)
+    hit = _lists.get(cache_key)
+    if hit and not fresh and time.monotonic() - hit[0] < LIST_TTL_SECONDS:
+        return hit[1]
+    try:
+        ids = [bare(m["id"]) for m in list_models(provider, key, api_base)]
+    except Exception as exc:
+        logger.info("Could not list %s models: %s", provider, clean_error(exc, 200))
+        return None
+    _lists[cache_key] = (time.monotonic(), ids)
+    return ids
+
+
+def find_replacement(model: str, key: Optional[str], api_base: Optional[str], tried: set[str]) -> Optional[str]:
+    from .channels import provider_of
+
+    ids = available_ids(provider_of(model), key, api_base)
+    return suggest_replacement(model, ids, exclude=tried) if ids else None
+
+
+# ---------------------------------------------------------------- runtime healing
+def replaced(config, route, new_model: str, error: Exception) -> None:
+    """A retired route answered with `new_model`: remember it (platform) or
+    save it on the user's key (BYOK)."""
+    if getattr(route, "source", "") == "byok":
+        key_id = getattr(route, "key_id", None)
+        if key_id is not None:
+            try:
+                from ..services.ai_access import update_byok_model
+
+                update_byok_model(config, key_id, new_model)
+            except Exception:
+                logger.exception("Could not save the new model for key %s", key_id)
+        logger.warning("Own-key model %s retired; switched to %s", route.model, new_model)
+        return
+    newly = _mark(config, route.model, status="unavailable", kind=error_kind(error), message=clean_error(error),
+                  replacement=new_model, replacement_ok=True)
+    logger.warning("AI model %s unavailable (%s); using %s until the setting is changed",
+                   route.model, clean_error(error, 120), new_model)
+    if newly:
+        _announce_async(config, route.model, clean_error(error), new_model)
+
+
+def unavailable(config, route, error: Exception) -> None:
+    """A platform route is retired and nothing could replace it."""
+    if getattr(route, "source", "") == "byok":
+        return
+    if _mark(config, route.model, status="unavailable", kind=error_kind(error), message=clean_error(error),
+             replacement=None, replacement_ok=False):
+        _announce_async(config, route.model, clean_error(error), None)
+
+
+def _mark(config, model: str, **fields) -> bool:
+    """Updates one model's entry; True when it just became unavailable."""
+    with _lock:
+        state = load(config)
+        entry = state["models"].get(model) or {}
+        was = entry.get("status")
+        if fields.get("status") == "unavailable" and was == "unavailable" and not fields.get("replacement"):
+            fields.pop("replacement", None)  # keep a replacement found earlier
+            fields.pop("replacement_ok", None)
+        entry.update(fields)
+        entry["checked_at"] = _now()
+        if entry.get("status") == "unavailable":
+            entry.setdefault("since", _now())
+        state["models"][model] = entry
+        _save(config, state)
+        newly = entry.get("status") == "unavailable" and not entry.get("notified")
+        if newly:
+            entry["notified"] = _now()
+            _save(config, state)
+        return newly
+
+
+def _announce_async(config, model: str, message: str, replacement: Optional[str]) -> None:
+    threading.Thread(target=announce, args=(config, model, message, replacement),
+                     name="ai-model-notice", daemon=True).start()
+
+
+def announce(config, model: str, message: str, replacement: Optional[str]) -> None:
+    """Logged and sent to the system-error channels, once per model."""
+    if replacement:
+        text = (f"The AI model {model} is no longer available ({message[:160]}). MarketMyna is using "
+                f"{replacement} instead for now. Set LLM_MODEL to keep it, "
+                "or pick another model.")
+    else:
+        text = (f"The AI model {model} is no longer available ({message[:160]}) and no replacement was found. "
+                "AI features may fail until you add an AI key in Settings → AI keys or set another LLM_MODEL.")
+    logger.warning("%s", text)
+    try:
+        from ..notifiers.dispatcher import NotificationDispatcher
+
+        NotificationDispatcher(config).send_all(text, title="⚠️ MarketMyna AI model retired", purpose="system_error")
+    except Exception:
+        logger.exception("Could not send the retired-model notice")

marketmyna/llm/protocol.py

@@ -0,0 +1,111 @@
+"""GenerationBackend protocol: the swappable interface every LLM backend
+implements, and the result/error shapes they exchange with callers.
+
+Simplified from daily_stock_analysis's own marketmyna/llm/generation_backend.py:
+`response_validator` (schema-validation-with-retry) and `audit_context`
+(HMAC-hashed prompt audit telemetry) are dropped here - both are real
+features but belong to a later hardening pass, not a first LLM backend
+for MarketMyna. `stream`/`stream_progress_callback` are kept in the
+signature (Phase 3b's agent chat endpoint will want streaming) but no
+backend in this phase actually implements streaming yet - passing
+stream=True raises before any call is made, rather than silently
+falling back to non-streaming and surprising a caller expecting chunks.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Optional, Protocol
+
+
+class GenerationErrorCode(Enum):
+    BACKEND_NOT_CONFIGURED = "backend_not_configured"
+    TIMEOUT = "timeout"
+    RATE_LIMITED = "rate_limited"
+    INVALID_RESPONSE = "invalid_response"
+    AUTH_FAILED = "auth_failed"  # the provider rejected the key
+    MODEL_UNAVAILABLE = "model_unavailable"  # retired, renamed, or closed to this key
+    UNKNOWN = "unknown"
+
+
+class GenerationError(Exception):
+    """Structured error every backend raises on failure, so callers (the
+    future agent orchestrator) can decide retryable/fallbackable behavior
+    without parsing exception messages."""
+
+    def __init__(
+        self,
+        error_code: GenerationErrorCode,
+        message: str = "",
+        *,
+        stage: str = "generate",
+        retryable: bool = False,
+        fallbackable: bool = True,
+        backend: Optional[str] = None,
+        provider: Optional[str] = None,
+        details: Optional[dict] = None,
+    ):
+        super().__init__(message or error_code.value)
+        self.error_code = error_code
+        self.stage = stage
+        self.retryable = retryable
+        self.fallbackable = fallbackable
+        self.backend = backend
+        self.provider = provider
+        self.details = details or {}
+
+
+@dataclass
+class GenerationCapabilities:
+    supports_json: bool = False
+    supports_tools: bool = False
+    supports_stream: bool = False
+    supports_vision: bool = False
+    supports_health_check: bool = False
+    supports_smoke_test: bool = False
+
+
+@dataclass
+class GenerationResult:
+    text: str
+    model: str
+    provider: str
+    backend: str
+    usage: dict = field(default_factory=dict)
+    raw: Any = None
+    diagnostics: dict = field(default_factory=dict)
+
+
+@dataclass
+class GenerationConfig:
+    """Per-call generation parameters. A backend applies its own Config-
+    derived defaults (model/timeout/max_tokens/temperature) for any field
+    left None here."""
+
+    model: Optional[str] = None
+    timeout: Optional[float] = None
+    max_tokens: Optional[int] = None
+    temperature: Optional[float] = None
+    # Reuse key in place of the prompt text: answers for the same scope (e.g. one
+    # stock's stage) are shared for the cache's lifetime even as live prices move.
+    cache_scope: Optional[str] = None
+
+
+class GenerationBackend(Protocol):
+    """Every concrete backend (LiteLLM today; a local-CLI subprocess
+    backend later) implements this."""
+
+    backend_id: str
+    capabilities: GenerationCapabilities
+
+    def generate(
+        self,
+        prompt: str,
+        generation_config: GenerationConfig,
+        *,
+        system_prompt: Optional[str] = None,
+        stream: bool = False,
+        stream_progress_callback: Optional[Callable[[str], None]] = None,
+    ) -> GenerationResult:
+        ...