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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-stack
-Version: 1.6.6
+Version: 1.6.8
 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

{cat_stack-1.6.6 → cat_stack-1.6.8}/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.6"
+__version__ = "1.6.8"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-stack"

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

@@ -126,6 +126,51 @@ def _hf_model_needs_enable_thinking_off(model: str) -> bool:
     return any(model.startswith(p) for p in _HF_NEEDS_ENABLE_THINKING_OFF)
 
 
+# Router-served models measured (2026-06-12 reasoning audit) to reason by
+# default with NO honored off-switch through the OpenAI-compatible router:
+# the router 400-rejects `chat_template_kwargs.enable_thinking` for their
+# templates, and they expose no reasoning_effort. classify() warns once per
+# client so users know the provider default applies.
+_HF_DEFAULT_REASONING_PREFIXES = (
+    "openai/gpt-oss",
+    "moonshotai/kimi-k2",
+)
+
+
+def _hf_model_reasons_by_default(model: str) -> bool:
+    m = (model or "").lower()
+    return any(m.startswith(p) for p in _HF_DEFAULT_REASONING_PREFIXES)
+
+
+# Module-level: models already warned about uncontrolled reasoning, so the
+# warning fires once per process even though a fresh client is built per row.
+_WARNED_UNCONTROLLED_REASONING: set = set()
+
+
+# ---------------------------------------------------------------------------
+# Anthropic deprecated the `temperature` parameter starting with the Opus 4.7 /
+# 4.8 generation: these models return 400 "`temperature` is deprecated for this
+# model." if it is sent. Older models (opus-4-6, sonnet-4-6, sonnet-4-5, and
+# earlier) still accept it. This mirrors the OpenAI reasoning-model handling
+# above — we skip `temperature` up-front for the known-deprecated prefixes in
+# `_build_anthropic_payload`, and `UnifiedLLMClient.complete()` strips it on a
+# runtime 400 as a safety net for future families not yet in this table.
+#
+# Matched by name prefix; extend the tuple when new temperature-free models
+# ship.
+# ---------------------------------------------------------------------------
+_ANTHROPIC_TEMPERATURE_DEPRECATED = (
+    "claude-opus-4-7",
+    "claude-opus-4-8",
+)
+
+
+def _anthropic_supports_temperature(model: str) -> bool:
+    """False for Anthropic models that reject the `temperature` param."""
+    m = (model or "").lower()
+    return not any(m.startswith(p) for p in _ANTHROPIC_TEMPERATURE_DEPRECATED)
+
+
 # ---------------------------------------------------------------------------
 # Ollama reasoning control: per-model-family parameter format for the
 # top-level `think` field on chat / generate requests.
@@ -521,8 +566,15 @@ class UnifiedLLMClient:
             # 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)
+        elif self.provider == "xai":
+            # v1.6.8: forward the reasoning request. grok-4.3+ hybrids reason
+            # by default (2026-06-12 audit: 214 reasoning tokens on a trivial
+            # probe with no control sent); non-reasoning variants reject
+            # reasoning_effort and are handled by the 400 fallback in
+            # complete(), which caches the rejection on the client.
+            return self._build_openai_payload(messages, json_schema, creativity, force_json, thinking_budget)
         else:
-            # Other OpenAI-compatible providers (xai, mistral, etc.)
+            # Other OpenAI-compatible providers (mistral, etc.)
             return self._build_openai_payload(messages, json_schema, creativity, force_json)
 
     def _build_openai_payload(
@@ -596,6 +648,25 @@ class UnifiedLLMClient:
         elif creativity is not None:
             payload["temperature"] = creativity
 
+        # xAI (v1.6.8): hybrid grok models accept reasoning_effort alongside
+        # temperature. "low" is the lowest tier xAI exposes (no "none" /
+        # "minimal"); explicitly non-reasoning variants 400 on the field —
+        # complete() pops it and caches `_xai_no_reasoning_effort` so later
+        # rows on this client skip the doomed field up front.
+        if (
+            self.provider == "xai"
+            and thinking_budget is not None
+            and not getattr(self, "_xai_no_reasoning_effort", False)
+            # Variants whose name already encodes "non-reasoning" are off by
+            # model choice; sending reasoning_effort to them is not just
+            # redundant but HARMFUL — verified 2026-06-13 that
+            # grok-4-1-fast-non-reasoning returns 0 reasoning tokens with no
+            # field but 207 when sent reasoning_effort="low", i.e. the field
+            # turns reasoning back ON. Leave these alone.
+            and "non-reasoning" not in (self.model or "").lower()
+        ):
+            payload["reasoning_effort"] = "low" if thinking_budget == 0 else "high"
+
         # 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
@@ -624,6 +695,24 @@ class UnifiedLLMClient:
             and _hf_model_needs_enable_thinking_off(self.model)
         ):
             payload["chat_template_kwargs"] = {"enable_thinking": False}
+        elif (
+            self.provider in ("huggingface", "huggingface-together")
+            and thinking_budget == 0
+            and _hf_model_reasons_by_default(self.model)
+            and self.model not in _WARNED_UNCONTROLLED_REASONING
+        ):
+            # v1.6.8: these router-served models reason by default and honor
+            # no off-switch through the router (enable_thinking is
+            # 400-rejected for their templates). Warn once per process (a
+            # fresh client is built per row, so a per-instance flag would
+            # warn every row) so the uniform "reasoning off" request isn't
+            # silently unmet.
+            print(
+                f"\n[CatLLM] WARNING: no effective reasoning control delivered "
+                f"for '{self.model}'; the provider's default reasoning "
+                f"behavior applies. See docs/reasoning-controls.md.\n"
+            )
+            _WARNED_UNCONTROLLED_REASONING.add(self.model)
 
         return payload
 
@@ -660,6 +749,14 @@ class UnifiedLLMClient:
         if system_content:
             payload["system"] = system_content
 
+        # Newer Anthropic models (Opus 4.7+) deprecated `temperature` and 400 if
+        # it is sent. Skip it for those known prefixes, and also honor the flag
+        # cached by complete()'s runtime 400 fallback for future families.
+        _temp_ok = (
+            _anthropic_supports_temperature(self.model)
+            and not getattr(self, "_anthropic_temperature_unsupported", False)
+        )
+
         # Extended thinking for Anthropic (minimum 1024 tokens)
         # When thinking is enabled, temperature must be 1 (Anthropic requirement),
         # so we skip setting temperature from creativity in that case
@@ -669,11 +766,12 @@ class UnifiedLLMClient:
                 "type": "enabled",
                 "budget_tokens": budget,
             }
-            payload["temperature"] = 1
+            if _temp_ok:
+                payload["temperature"] = 1
             # When thinking is enabled, max_tokens must be larger than budget_tokens
             if payload["max_tokens"] <= budget:
                 payload["max_tokens"] = budget + 4096
-        elif creativity is not None:
+        elif creativity is not None and _temp_ok:
             payload["temperature"] = creativity
 
         # Use tool calling for structured output (most reliable for Anthropic)
@@ -726,11 +824,19 @@ class UnifiedLLMClient:
         if creativity is not None:
             payload["generationConfig"]["temperature"] = creativity
 
-        # Add thinking budget for extended thinking (Google-specific)
-        # Must be inside generationConfig, not at top level
-        # Google requires a reasonable minimum budget (enforce 128 tokens minimum)
-        if thinking_budget and thinking_budget > 0:
-            budget = max(thinking_budget, 128)
+        # Reasoning control (Google-specific). Must be inside generationConfig.
+        # v1.6.8: an explicit zero budget is now SENT at thinking_budget = 0.
+        # Previously nothing was sent at 0 and Gemini ran at its provider
+        # default, which the 2026-06-12 audit measured as thinking ON
+        # (~200+ thought tokens on a trivial classification call). Models
+        # that reject 0 (minimum-budget tiers) are handled by the 400
+        # fallback in complete(), which caches the discovered floor on the
+        # client (`_google_thinking_floor`).
+        if thinking_budget is not None:
+            if thinking_budget > 0:
+                budget = max(thinking_budget, 128)
+            else:
+                budget = getattr(self, "_google_thinking_floor", 0)
             payload["generationConfig"]["thinkingConfig"] = {"thinkingBudget": budget}
 
         return payload
@@ -913,6 +1019,10 @@ class UnifiedLLMClient:
         # transient error this call? Only strip once per call so we don't
         # mutate payload on every retry tick.
         stripped_response_format = False
+        # v1.6.8: consecutive-timeout counter + one-shot Google schema drop
+        # (see the Timeout handler below).
+        timeout_count = 0
+        dropped_google_schema = False
 
         for attempt in range(max_retries):
             endpoint = self._get_endpoint()
@@ -986,9 +1096,51 @@ class UnifiedLLMClient:
                             payload["reasoning_effort"] = "low"
                             continue
                         elif current == "low" and "reasoning_effort" in payload:
+                            # Model takes no reasoning_effort at all (e.g.
+                            # xAI's explicitly non-reasoning variants).
+                            # Cache so later rows on this client skip the
+                            # doomed field up front (v1.6.8).
+                            self._xai_no_reasoning_effort = True
                             payload.pop("reasoning_effort")
                             continue
 
+                    # Google (v1.6.8): minimum-budget thinking tiers reject
+                    # thinkingBudget: 0. Fall back to 128 (Google's stated
+                    # minimum) and cache on the client.
+                    if (
+                        self.provider == "google"
+                        and "thinking" in error_text
+                        and ("budget" in error_text or "invalid" in error_text
+                             or "unsupported" in error_text)
+                        and payload.get("generationConfig", {})
+                                   .get("thinkingConfig", {})
+                                   .get("thinkingBudget") == 0
+                    ):
+                        self._google_thinking_floor = 128
+                        payload["generationConfig"]["thinkingConfig"]["thinkingBudget"] = 128
+                        print(f"\n[CatLLM] Model '{self.model}' rejected thinkingBudget=0; "
+                              f"falling back to the minimum (128) and caching for this client.\n")
+                        continue
+
+                    # Anthropic deprecated `temperature` for newer models
+                    # (Opus 4.7+): they 400 with "`temperature` is deprecated
+                    # for this model." Strip it, cache on the client so the
+                    # payload builder skips it for subsequent rows on this
+                    # client, and retry. Safety net for families not yet in
+                    # `_ANTHROPIC_TEMPERATURE_DEPRECATED`.
+                    if (
+                        "temperature" in error_text
+                        and "deprecated" in error_text
+                        and "temperature" in payload
+                    ):
+                        if not getattr(self, '_warned_temperature_deprecated', False):
+                            print(f"\n[CatLLM] Model '{self.model}' deprecated the temperature parameter.")
+                            print(f"  Dropping it and caching for subsequent calls on this client.\n")
+                            self._warned_temperature_deprecated = True
+                        self._anthropic_temperature_unsupported = True
+                        payload.pop("temperature")
+                        continue
+
                     # HuggingFace: try other routers when the current one
                     # rejects the model with a "wrong router" 400.
                     if self._is_hf_wrong_router_400(response.text):
@@ -1061,6 +1213,27 @@ class UnifiedLLMClient:
                 return result, None
 
             except requests.exceptions.Timeout:
+                timeout_count += 1
+                # v1.6.8: Gemini can reproducibly hang on specific inputs
+                # when a strict responseSchema is attached (constrained-
+                # decoding pathology; 2026-06-12 audit — a trivial input
+                # timed out 6/6 attempts WITH the schema and answered
+                # instantly without it). After two consecutive timeouts with
+                # a schema attached, drop the schema once and re-ask: the
+                # prompt still requests JSON and extract_json() parses it
+                # from the free-text response.
+                if (
+                    self.provider == "google"
+                    and timeout_count >= 2
+                    and not dropped_google_schema
+                    and "responseSchema" in payload.get("generationConfig", {})
+                ):
+                    dropped_google_schema = True
+                    payload["generationConfig"].pop("responseSchema", None)
+                    print(f"[CatLLM] Repeated timeouts from '{self.model}' with "
+                          f"responseSchema attached; retrying schema-less "
+                          f"(prompt-based JSON parsing).")
+                    continue
                 wait_time = _backoff_with_jitter(initial_delay, attempt)
                 elapsed = time.monotonic() - start
                 if attempt < max_retries - 1 and elapsed + wait_time <= max_total_wait:

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

@@ -3638,11 +3638,12 @@ def build_output_dataframes(
     # Populate data
     for idx, result in enumerate(all_results):
         combined_data["input_index"].append(idx)
-        # Truncate input_data for readability
+        # Full input_data (whitespace-collapsed). Truncating here breaks
+        # downstream joins against gold-standard files and silently feeds
+        # truncated text to any pipeline that reuses input_data as input.
         raw = result["response"]
         clean = " ".join(str(raw).split())  # collapse whitespace/newlines
-        preview = clean[:100] + "..." if len(clean) > 100 else clean
-        combined_data["input_data"].append(preview)
+        combined_data["input_data"].append(clean)
         aggregated = result["aggregated"]
 
         # Add PDF metadata if present
@@ -4464,7 +4465,13 @@ def summarize_ensemble(
             # synthesis still has *something* to anchor on (prior behavior).
             original_text_for_synthesis = entry.get("page_text") or page_label
         else:
-            # Truncate input_data for readability; add input_index for joining
+            # Truncate input_data for readability; add input_index for joining.
+            # Truncation is intentional HERE (summarize): inputs can be whole
+            # documents/PDF pages, and full text would bloat the output and the
+            # synthesis context. classify()'s writer (build_output_dataframes)
+            # deliberately does NOT truncate — survey-length inputs there are
+            # reused for downstream joins. See repo TODO for the permanent
+            # per-function input_data design (preview + stable join key).
             clean = " ".join(str(item).split())  # collapse whitespace/newlines
             preview = clean[:100] + "..." if len(clean) > 100 else clean
             row = {