misterdev 0.2.0__py3-none-any.whl

misterdev/llm/client/embeddings.py

@@ -0,0 +1,121 @@
+import importlib.util
+from typing import List
+
+from misterdev.config import get_section_setting, get_setting
+from misterdev.logging_setup import setup_logger
+
+from .providers import _deny_unless_training_allowed, _openrouter_sdk
+
+logger = setup_logger(__name__)
+
+
+class OpenRouterEmbeddingClient:
+    """Embedding client over OpenRouter's OpenAI-compatible embeddings endpoint."""
+
+    def __init__(self, config: dict, model: str):
+        llm_config = config.get("llm", {})
+        self.client, self.api_key = _openrouter_sdk(llm_config)
+        self.model = model
+        self.dimensions = get_section_setting("llm", llm_config, "embedding_dimensions")
+        self.data_collection = _deny_unless_training_allowed(llm_config)
+
+    def embed(self, texts: List[str]) -> List[List[float]]:
+        """Return one vector per input text, in input order."""
+        kwargs = {
+            "model": self.model,
+            "input": texts,
+            "extra_body": {"provider": {"data_collection": self.data_collection}},
+        }
+        if self.dimensions:
+            kwargs["dimensions"] = self.dimensions
+        response = self.client.embeddings.create(**kwargs)
+        ordered = sorted(response.data, key=lambda d: d.index)
+        return [list(d.embedding) for d in ordered]
+
+
+class LocalEmbeddingClient:
+    """Embedding client backed by a local fastembed model (offline, no API key).
+
+    The model is downloaded once and cached by fastembed, then runs on CPU via
+    ONNX. Loading is lazy (first ``embed`` call) so merely constructing the
+    client is cheap and failure (e.g. fastembed not installed) surfaces where
+    the factory can fall back gracefully.
+    """
+
+    def __init__(self, config: dict):
+        llm_config = config.get("llm", {})
+        self.model = (
+            get_section_setting("llm", llm_config, "local_embedding_model")
+            or "BAAI/bge-small-en-v1.5"
+        )
+        self._embedder = None
+
+    def _ensure(self):
+        if self._embedder is None:
+            from fastembed import TextEmbedding
+
+            self._embedder = TextEmbedding(model_name=self.model)
+        return self._embedder
+
+    def embed(self, texts: List[str]) -> List[List[float]]:
+        """Return one vector per input text, in input order."""
+        embedder = self._ensure()
+        return [list(vec) for vec in embedder.embed(list(texts))]
+
+
+def _create_local_embedding_client(config: dict):
+    try:
+        return LocalEmbeddingClient(config)
+    except Exception as e:
+        logger.warning(f"Local embedding client unavailable: {e}")
+        return None
+
+
+def _create_openrouter_embedding_client(config: dict):
+    if get_setting(config, "llm", "provider") != "openrouter":
+        return None
+    from misterdev.core.economics.embeddings import pick_embedding_model
+
+    model = pick_embedding_model(
+        get_setting(config, "llm", "embedding_model"),
+        prefer=get_setting(config, "llm", "embedding_prefer"),
+    )
+    if not model:
+        return None
+    try:
+        return OpenRouterEmbeddingClient(config, model)
+    except Exception as e:
+        logger.warning(f"Embedding client unavailable: {e}")
+        return None
+
+
+def create_embedding_client(config: dict):
+    """Build an embedding client, or None when embeddings are unavailable.
+
+    Backend (llm.embedding_backend): "local" forces fastembed; "openrouter"
+    forces the API; "none" disables dense ranking; "auto" prefers a local
+    fastembed model when the extra is installed (free, offline, never blocked by
+    a provider data policy) and falls back to the OpenRouter API embedder only
+    when local isn't available. Any setup failure returns None, so retrieval
+    degrades to lexical-only rather than breaking.
+    """
+    backend = get_setting(config, "llm", "embedding_backend")
+    if backend == "none":
+        return None
+    if backend == "local":
+        return _create_local_embedding_client(config)
+    if backend == "openrouter":
+        return _create_openrouter_embedding_client(config)
+    # auto
+    if get_setting(config, "llm", "provider") == "openrouter":
+        # Prefer a LOCAL fastembed model when the extra is installed: it is free,
+        # offline, and — unlike an OpenRouter embedding model under
+        # data_collection=deny — never blocked by a provider data policy (that
+        # block silently dropped both emathy runs to lexical-only ranking). When
+        # fastembed isn't installed, keep the API embedder (no regression).
+        if importlib.util.find_spec("fastembed") is not None:
+            local = _create_local_embedding_client(config)
+            if local is not None:
+                return local
+        return _create_openrouter_embedding_client(config)
+    return _create_local_embedding_client(config)

misterdev/llm/client/errors.py

@@ -0,0 +1,134 @@
+from typing import Optional
+
+
+class BudgetExceededError(Exception):
+    pass
+
+
+class LLMCallError(Exception):
+    def __init__(self, message: str, retryable: bool = False):
+        super().__init__(message)
+        self.retryable = retryable
+
+
+# HTTP status codes that denote a transient failure worth retrying / failing
+# over. The 4xx members are the standard retryable ones (request timeout,
+# conflict, too-early, rate limit); any other 4xx is a hard client error.
+RETRYABLE_STATUS_CODES = frozenset({408, 409, 425, 429, 500, 502, 503, 504, 529})
+
+# Exception class names (across the openai / anthropic / httpx SDKs) that always
+# denote a transient failure, regardless of how the message happens to be
+# phrased. Matched by bare class name so neither SDK must be importable here.
+RETRYABLE_EXCEPTION_NAMES = frozenset(
+    {
+        "RateLimitError",
+        "APITimeoutError",
+        "APIConnectionError",
+        "APIConnectionTimeoutError",
+        "InternalServerError",
+        "ServiceUnavailableError",
+        "Timeout",
+        "TimeoutError",
+        "ConnectionError",
+        "ConnectTimeout",
+        "ReadTimeout",
+    }
+)
+
+# Last-resort substring signals for plain exceptions that carry neither a status
+# code nor a recognizable type (e.g. a provider that raises RuntimeError with a
+# descriptive message). Checked only after the structured signals above.
+RETRYABLE_ERROR_MARKERS = (
+    "rate limit",
+    "too many requests",
+    "timeout",
+    "timed out",
+    "temporarily unavailable",
+    "overloaded",
+    "connection",
+    "try again",
+    "429",
+    "500",
+    "502",
+    "503",
+    "504",
+    "529",
+)
+
+
+def _error_status_code(error: Exception) -> Optional[int]:
+    """Best-effort HTTP status code from a provider exception, or None.
+
+    Covers the openai/anthropic ``status_code`` attribute and the httpx-style
+    nested ``response.status_code``. ``bool`` is excluded so a stray ``True``
+    isn't read as code 1.
+    """
+    for attr in ("status_code", "http_status"):
+        val = getattr(error, attr, None)
+        if isinstance(val, bool):
+            continue
+        if isinstance(val, int):
+            return val
+        if isinstance(val, str) and val.isdigit():
+            return int(val)
+    resp = getattr(error, "response", None)
+    sc = getattr(resp, "status_code", None)
+    if isinstance(sc, int) and not isinstance(sc, bool):
+        return sc
+    return None
+
+
+def _is_retryable_error(error: Exception) -> bool:
+    """Classify an exception as transient (retry / fail over) or terminal.
+
+    Structured signals win: an explicit HTTP status code or a known transient
+    exception type is authoritative, so a hard 4xx (e.g. 400/401/404) is never
+    retried even if its message text coincidentally contains a retryable marker.
+    Only when no structured signal is present do we fall back to substrings.
+    """
+    code = _error_status_code(error)
+    if code is not None:
+        if code in RETRYABLE_STATUS_CODES:
+            return True
+        if 400 <= code < 500:
+            return False
+        if code >= 500:
+            return True
+    if type(error).__name__ in RETRYABLE_EXCEPTION_NAMES:
+        return True
+    text = str(error).lower()
+    return any(marker in text for marker in RETRYABLE_ERROR_MARKERS)
+
+
+def _is_out_of_credits(error: Exception) -> bool:
+    """True when a provider rejects the call for lack of funds (HTTP 402).
+
+    This is terminal and account-wide — retrying or failing over to another
+    model cannot fix it — so it is surfaced as budget exhaustion, not a generic
+    call error. Detected by the 402 status code, with a message fallback for
+    providers that only carry it in the text.
+    """
+    if _error_status_code(error) == 402:
+        return True
+    text = str(error).lower()
+    return "insufficient credit" in text or (
+        "402" in text and ("credit" in text or "payment" in text)
+    )
+
+
+def _api_error(provider: str, error: Exception) -> Exception:
+    """Wrap a provider exception for the caller to raise.
+
+    An out-of-credits (402) response becomes a ``BudgetExceededError`` so the
+    run halts gracefully through the existing budget-halt path with an
+    actionable message, instead of crashing with a stack trace. Everything else
+    is an ``LLMCallError`` with retryability classified.
+    """
+    if _is_out_of_credits(error):
+        return BudgetExceededError(
+            f"{provider} out of credits (HTTP 402): add credits to continue "
+            "(https://openrouter.ai/settings/credits)"
+        )
+    return LLMCallError(
+        f"{provider} API error: {error}", retryable=_is_retryable_error(error)
+    )