cat-stack 1.6.4__tar.gz → 1.6.6__tar.gz

{cat_stack-1.6.4 → cat_stack-1.6.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-stack
-Version: 1.6.4
+Version: 1.6.6
 Summary: Domain-agnostic text, image, PDF, and DOCX classification engine powered by LLMs
 Project-URL: Documentation, https://github.com/chrissoria/cat-stack#readme
 Project-URL: Issues, https://github.com/chrissoria/cat-stack/issues
@@ -193,6 +193,15 @@ All providers use the same `(model_name, provider, api_key)` tuple format. Provi
   as `success`)
 - **Embedding similarity** tiebreaker for ensemble consensus ties
 - **Pilot test** — validate classifications on a small sample before committing to the full run
+- **Provider-conditional HTTP timeouts** — cloud providers use a tight
+  120 s per-request timeout (catches genuine hangs without waiting too
+  long on transient API blips), and the Ollama provider uses a wider
+  600 s per-request / 1200 s cumulative budget (accommodates the long
+  per-row tails that emerge when running 14B+ models on memory-
+  constrained hardware like 16 GB Macs). Power users can override per
+  client: `UnifiedLLMClient(provider, key, model, request_timeout=900,
+  max_total_wait=1800)`, or set a process-wide override with
+  `catstack._providers.set_session_timeouts(request_timeout=..., max_total_wait=...)`
 
 ## Future work / contributions welcome
 

{cat_stack-1.6.4 → cat_stack-1.6.6}/README.md

@@ -157,6 +157,15 @@ All providers use the same `(model_name, provider, api_key)` tuple format. Provi
   as `success`)
 - **Embedding similarity** tiebreaker for ensemble consensus ties
 - **Pilot test** — validate classifications on a small sample before committing to the full run
+- **Provider-conditional HTTP timeouts** — cloud providers use a tight
+  120 s per-request timeout (catches genuine hangs without waiting too
+  long on transient API blips), and the Ollama provider uses a wider
+  600 s per-request / 1200 s cumulative budget (accommodates the long
+  per-row tails that emerge when running 14B+ models on memory-
+  constrained hardware like 16 GB Macs). Power users can override per
+  client: `UnifiedLLMClient(provider, key, model, request_timeout=900,
+  max_total_wait=1800)`, or set a process-wide override with
+  `catstack._providers.set_session_timeouts(request_timeout=..., max_total_wait=...)`
 
 ## Future work / contributions welcome
 

{cat_stack-1.6.4 → cat_stack-1.6.6}/src/catstack/__about__.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: 2025-present Christopher Soria <chrissoria@berkeley.edu>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
-__version__ = "1.6.4"
+__version__ = "1.6.6"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-stack"

{cat_stack-1.6.4 → cat_stack-1.6.6}/src/catstack/_providers.py

@@ -19,6 +19,52 @@ import requests
 # short enough that batch ensembles don't stall for half an hour."
 _MAX_TOTAL_WAIT_SECONDS = 300.0
 
+# Per-HTTP-request timeout, in seconds. For cloud providers (OpenAI,
+# Anthropic, Google, …) inference is usually 1-10 seconds, so 120 s is
+# a generous ceiling that catches genuine hangs.
+#
+# Local Ollama is a different regime: on memory-constrained hardware
+# (e.g., 16 GB M1 Pro running a 14 B-class model), individual rows can
+# take 2-4+ minutes under thermal/memory pressure. cat-stack 1.6.4
+# logged frequent spurious "Request timeout" failures in those
+# conditions even when Ollama was about to produce valid output.
+# `_OLLAMA_REQUEST_TIMEOUT` and `_OLLAMA_MAX_TOTAL_WAIT_SECONDS` give
+# the Ollama path a much longer window. Surfaced during the small-tier
+# paper run, 2026-06-04.
+_REQUEST_TIMEOUT = 120.0          # cloud providers
+_OLLAMA_REQUEST_TIMEOUT = 600.0   # local Ollama — 5x cloud, accommodates slow-row tails
+_OLLAMA_MAX_TOTAL_WAIT_SECONDS = 1200.0  # 4x cloud, since per-call timeout is also 5x
+
+
+# Session-level user override. Set non-None at the start of a `classify()`
+# call to override the conditional defaults for ALL UnifiedLLMClient
+# instances constructed during that call without per-site arg threading.
+# Single-process scope; safe under cat-stack's intra-call parallelism
+# (per-call sets/resets bracket all workers).
+_session_request_timeout: float = None
+_session_max_total_wait: float = None
+
+
+def set_session_timeouts(request_timeout: float = None, max_total_wait: float = None):
+    """Set the session-level HTTP-timeout overrides. Pass None to clear."""
+    global _session_request_timeout, _session_max_total_wait
+    _session_request_timeout = request_timeout
+    _session_max_total_wait = max_total_wait
+
+
+def _request_timeout_for(provider: str) -> float:
+    """Per-request HTTP timeout. Session override wins over provider default."""
+    if _session_request_timeout is not None:
+        return _session_request_timeout
+    return _OLLAMA_REQUEST_TIMEOUT if provider == "ollama" else _REQUEST_TIMEOUT
+
+
+def _max_total_wait_for(provider: str) -> float:
+    """Per-call cumulative-wait cap. Session override wins."""
+    if _session_max_total_wait is not None:
+        return _session_max_total_wait
+    return _OLLAMA_MAX_TOTAL_WAIT_SECONDS if provider == "ollama" else _MAX_TOTAL_WAIT_SECONDS
+
 
 # ---------------------------------------------------------------------------
 # OpenAI reasoning_effort: per-model-family off-equivalent value.
@@ -79,6 +125,64 @@ _HF_NEEDS_ENABLE_THINKING_OFF = (
 def _hf_model_needs_enable_thinking_off(model: str) -> bool:
     return any(model.startswith(p) for p in _HF_NEEDS_ENABLE_THINKING_OFF)
 
+
+# ---------------------------------------------------------------------------
+# Ollama reasoning control: per-model-family parameter format for the
+# top-level `think` field on chat / generate requests.
+#
+# Ollama standardized on a single API field name (`think`) but the value
+# type differs per model family — gpt-oss takes an enum, most others take
+# a boolean. See https://docs.ollama.com/capabilities/thinking.
+#
+# Coverage philosophy: list every Ollama reasoning model family we know of
+# AND that uses the `think` field. Reasoning models that gate via other
+# mechanisms (system prompts, chat-template flags) are explicitly noted in
+# the "NOT in registry" comment below and handled elsewhere — adding them
+# here would silently inject a no-op `think` field, which Ollama may
+# accept but won't honor, leading to surprising behavior.
+#
+# Entries are checked longest-prefix-first by `_ollama_think_value()`, so
+# put more-specific prefixes earlier when adding (e.g. `qwen3-coder` before
+# `qwen3` if they differ).
+#
+#   Registry tuple: (model prefix, value-format, low_value, high_value)
+#
+# Models in registry — `think` field works:
+#   gpt-oss          — enum: "low" / "medium" / "high"  (cannot fully disable)
+#   qwen3 / qwen3.*  — bool: True / False               (covers -thinking variants too)
+#   qwq              — bool: True / False               (Qwen QwQ — preceded Qwen3)
+#   deepseek-r1      — bool: True / False               (covers -distill variants)
+#
+# Models NOT in registry — different mechanism, do NOT add here:
+#   magistral        — controlled via system prompt (Mistral Magistral)
+#   exaone-deep      — uses Modelfile-baked reasoning, no API toggle exposed
+#   marco-o1         — uses chat-template wrappers, not `think` field
+#
+# Models with NO reasoning (so `think` should not appear at all):
+#   gemma2/3, llama3.x/4.x, mistral, mistral-nemo, qwen2.5 (non-QwQ),
+#   phi3/4, granite, olmo, codestral, …
+# These are NOT added; the registry's None-return for unmatched prefixes
+# correctly omits the `think` field for them.
+# ---------------------------------------------------------------------------
+_OLLAMA_REASONING_MODELS = (
+    ("gpt-oss",      "enum", "low", "high"),
+    ("qwen3",        "bool", False, True),  # covers qwen3.*, qwen3-*, -thinking-* variants
+    ("qwq",          "bool", False, True),
+    ("deepseek-r1",  "bool", False, True),  # covers -distill-qwen, -distill-llama, etc.
+)
+
+
+def _ollama_think_value(model: str, thinking_budget):
+    """Map cat-stack's thinking_budget to the right Ollama `think` value for
+    this model family. Returns None if the model isn't in the
+    reasoning-capable registry (no `think` field should be set)."""
+    if thinking_budget is None:
+        return None
+    for prefix, fmt, low_val, high_val in _OLLAMA_REASONING_MODELS:
+        if model.startswith(prefix):
+            return low_val if thinking_budget == 0 else high_val
+    return None
+
 __all__ = [
     # Main client
     "UnifiedLLMClient",
@@ -274,10 +378,27 @@ PROVIDER_CONFIG = {
 class UnifiedLLMClient:
     """A unified client for calling various LLM providers via HTTP."""
 
-    def __init__(self, provider: str, api_key: str, model: str):
+    def __init__(self, provider: str, api_key: str, model: str,
+                 request_timeout: float = None,
+                 max_total_wait: float = None):
+        """
+        Args:
+            request_timeout (float | None): Override the per-HTTP-request
+                timeout (seconds). When None, uses the provider-conditional
+                default: 120 s for cloud providers, 600 s for Ollama.
+                Pass an explicit float to override per call site.
+            max_total_wait (float | None): Override the per-call cumulative
+                retry budget (seconds). When None, uses provider-conditional
+                default: 300 s for cloud, 1200 s for Ollama.
+        """
         self.provider = _normalize_provider(provider)
         self.api_key = api_key
         self.model = model
+        # User-level overrides for HTTP timeouts. None means "use the
+        # provider-conditional default" (see _request_timeout_for /
+        # _max_total_wait_for at module level).
+        self._request_timeout_override = request_timeout
+        self._max_total_wait_override = max_total_wait
 
         # Lazy HuggingFace router fallback — start with None and only
         # populate when we either (a) have an explicit router suffix, or
@@ -394,6 +515,12 @@ class UnifiedLLMClient:
         elif self.provider in ("huggingface", "huggingface-together"):
             # HuggingFace needs thinking_budget to disable thinking on models that reason by default
             return self._build_openai_payload(messages, json_schema, creativity, force_json, thinking_budget)
+        elif self.provider == "ollama":
+            # Ollama threads thinking_budget to its top-level `think` field for
+            # reasoning-capable models (gpt-oss accepts low/medium/high; others
+            # accept booleans). Without this, gpt-oss family models emit long
+            # <think> blocks by default that bloat per-row generation 3-5x.
+            return self._build_openai_payload(messages, json_schema, creativity, force_json, thinking_budget)
         else:
             # Other OpenAI-compatible providers (xai, mistral, etc.)
             return self._build_openai_payload(messages, json_schema, creativity, force_json)
@@ -469,6 +596,19 @@ class UnifiedLLMClient:
         elif creativity is not None:
             payload["temperature"] = creativity
 
+        # Ollama: per-model-family reasoning control via the top-level
+        # `think` field. gpt-oss expects an enum ("low"/"medium"/"high");
+        # qwen3/deepseek-r1 expect a boolean. Models not in the
+        # `_OLLAMA_REASONING_MODELS` registry don't support reasoning and
+        # get no `think` field (would be a no-op at best, validator-
+        # confusing at worst). Without this, Ollama-served gpt-oss
+        # produces long `<think>` blocks by default that bloat per-row
+        # generation 3-5x.
+        if self.provider == "ollama":
+            think_value = _ollama_think_value(self.model, thinking_budget)
+            if think_value is not None:
+                payload["think"] = think_value
+
         # HuggingFace: disable thinking on model families whose chat
         # template honors `enable_thinking` (Qwen3-family). Other HF-routed
         # models don't need the kwarg, and strict-validator backends
@@ -755,8 +895,20 @@ class UnifiedLLMClient:
             payload.pop("response_format")
 
         # Track cumulative wait so a long string of transient errors can't
-        # block the call indefinitely. See _MAX_TOTAL_WAIT_SECONDS.
+        # block the call indefinitely. Timeouts are provider-conditional by
+        # default; user overrides on the client instance (set at __init__)
+        # take precedence.
         start = time.monotonic()
+        request_timeout = (
+            self._request_timeout_override
+            if self._request_timeout_override is not None
+            else _request_timeout_for(self.provider)
+        )
+        max_total_wait = (
+            self._max_total_wait_override
+            if self._max_total_wait_override is not None
+            else _max_total_wait_for(self.provider)
+        )
         # Per-call flag: have we already tried stripping response_format on a
         # transient error this call? Only strip once per call so we don't
         # mutate payload on every retry tick.
@@ -769,7 +921,7 @@ class UnifiedLLMClient:
                     endpoint,
                     headers=headers,
                     json=payload,
-                    timeout=120,
+                    timeout=request_timeout,
                 )
 
                 # Check for HTTP errors
@@ -854,7 +1006,7 @@ class UnifiedLLMClient:
                     if wait_time is None:
                         wait_time = _backoff_with_jitter(initial_delay, attempt, multiplier=5.0)
                     elapsed = time.monotonic() - start
-                    if attempt < max_retries - 1 and elapsed + wait_time <= _MAX_TOTAL_WAIT_SECONDS:
+                    if attempt < max_retries - 1 and elapsed + wait_time <= max_total_wait:
                         # Name the throttling provider/model so multi-model
                         # ensemble runs can attribute the slowdown.
                         print(f"[{self.provider}/{self.model}] Rate limited. Waiting {wait_time:.1f}s...")
@@ -894,7 +1046,7 @@ class UnifiedLLMClient:
                     if wait_time is None:
                         wait_time = _backoff_with_jitter(initial_delay, attempt)
                     elapsed = time.monotonic() - start
-                    if attempt < max_retries - 1 and elapsed + wait_time <= _MAX_TOTAL_WAIT_SECONDS:
+                    if attempt < max_retries - 1 and elapsed + wait_time <= max_total_wait:
                         # Name the failing provider/model — same rationale as
                         # the 429 handler above.
                         print(f"[{self.provider}/{self.model}] Server error {response.status_code}. Retrying in {wait_time:.1f}s...")
@@ -911,7 +1063,7 @@ class UnifiedLLMClient:
             except requests.exceptions.Timeout:
                 wait_time = _backoff_with_jitter(initial_delay, attempt)
                 elapsed = time.monotonic() - start
-                if attempt < max_retries - 1 and elapsed + wait_time <= _MAX_TOTAL_WAIT_SECONDS:
+                if attempt < max_retries - 1 and elapsed + wait_time <= max_total_wait:
                     print(f"Request timeout. Retrying in {wait_time:.1f}s...")
                     time.sleep(wait_time)
                 else:
@@ -920,7 +1072,7 @@ class UnifiedLLMClient:
             except requests.exceptions.RequestException as e:
                 wait_time = _backoff_with_jitter(initial_delay, attempt)
                 elapsed = time.monotonic() - start
-                if attempt < max_retries - 1 and elapsed + wait_time <= _MAX_TOTAL_WAIT_SECONDS:
+                if attempt < max_retries - 1 and elapsed + wait_time <= max_total_wait:
                     print(f"Request error: {e}. Retrying in {wait_time:.1f}s...")
                     time.sleep(wait_time)
                 else:

{cat_stack-1.6.4 → cat_stack-1.6.6}/src/catstack/text_functions_ensemble.py

@@ -3043,7 +3043,7 @@ Categorize text responses {cove_categorize}:
                         messages=messages,
                         json_schema=json_schemas[cfg["model"]],
                         creativity=effective_creativity,
-                        thinking_budget=thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together") else None,
+                        thinking_budget=thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together", "ollama") else None,
                         max_retries=max_retries,
                     )
 
@@ -3100,7 +3100,7 @@ Categorize text responses {cove_categorize}:
                         messages=messages,
                         json_schema=json_schemas[cfg["model"]],
                         creativity=effective_creativity,
-                        thinking_budget=thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together") else None,
+                        thinking_budget=thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together", "ollama") else None,
                         max_retries=max_retries,
                     )
 
@@ -3184,7 +3184,7 @@ Categorize text responses {cove_categorize}:
                             messages=_retry_messages,
                             json_schema=json_schemas[cfg["model"]],
                             creativity=effective_creativity,
-                            thinking_budget=thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together") else None,
+                            thinking_budget=thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together", "ollama") else None,
                             max_retries=max_retries,
                         )