cat-stack 2.5.2__tar.gz → 2.5.4__tar.gz

{cat_stack-2.5.2 → cat_stack-2.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cat-stack
-Version: 2.5.2
+Version: 2.5.4
 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
@@ -24,9 +24,9 @@ Requires-Dist: pandas
 Requires-Dist: requests
 Requires-Dist: tqdm
 Provides-Extra: agent
-Requires-Dist: cat-claws[claude]>=0.3.2; extra == 'agent'
+Requires-Dist: cat-claws[claude]>=0.3.3; extra == 'agent'
 Provides-Extra: codex-agent
-Requires-Dist: cat-claws[codex]>=0.3.2; extra == 'codex-agent'
+Requires-Dist: cat-claws[codex]>=0.3.3; extra == 'codex-agent'
 Provides-Extra: docx
 Requires-Dist: python-docx>=1.0.0; extra == 'docx'
 Provides-Extra: embeddings
@@ -239,7 +239,7 @@ OpenAI, Anthropic, Google (Gemini), Mistral, Perplexity, xAI (Grok), HuggingFace
 
 All providers use the same `(model_name, provider, api_key)` tuple format. Provider is auto-detected from model name if omitted.
 
-**Subscription backends (no API key).** Three `model_source` values authenticate through a chat subscription instead of a metered key — leave `api_key` unset: `"claude-agent"` (Claude subscription via the Agent SDK; `pip install "cat-stack[agent]"`), `"claude-code"` (the Claude Code CLI, if installed — no extra needed), and `"codex-agent"` (ChatGPT subscription; `pip install "cat-stack[codex-agent]"`). Classification, extraction, exploration, and summarization all route through them.
+**Subscription backends (no API key).** Three `model_source` values authenticate through a chat subscription instead of a metered key — leave `api_key` unset: `"claude-agent"` (Claude subscription via the Agent SDK; `pip install "cat-stack[agent]"`), `"claude-code"` (the Claude Code CLI, if installed — no extra needed), and `"codex-agent"` (ChatGPT subscription; `pip install "cat-stack[codex-agent]"`). Classification, extraction, exploration, and summarization all route through them, including images and PDF pages on the two agent backends. They use the agent CLI's own sign-in (separate from the Claude desktop app's): runs check it up front and, if you're signed out, open a single browser window to sign in once, then continue. See the [cat-claws README](https://github.com/chrissoria/cat-agent#signing-in-once).
 
 **Reproducibility note:** the same nominal model can behave differently across access routes. In a seed-matched benchmark (Claude Sonnet 5, temperature 0), extraction through the Agent SDK produced more varied label phrasings than the direct API (89% vs. 74% unique raw labels), while final consolidated taxonomies were equivalent. If raw label counts matter to your analysis, record the access route alongside the model version.
 

{cat_stack-2.5.2 → cat_stack-2.5.4}/README.md

@@ -198,7 +198,7 @@ OpenAI, Anthropic, Google (Gemini), Mistral, Perplexity, xAI (Grok), HuggingFace
 
 All providers use the same `(model_name, provider, api_key)` tuple format. Provider is auto-detected from model name if omitted.
 
-**Subscription backends (no API key).** Three `model_source` values authenticate through a chat subscription instead of a metered key — leave `api_key` unset: `"claude-agent"` (Claude subscription via the Agent SDK; `pip install "cat-stack[agent]"`), `"claude-code"` (the Claude Code CLI, if installed — no extra needed), and `"codex-agent"` (ChatGPT subscription; `pip install "cat-stack[codex-agent]"`). Classification, extraction, exploration, and summarization all route through them.
+**Subscription backends (no API key).** Three `model_source` values authenticate through a chat subscription instead of a metered key — leave `api_key` unset: `"claude-agent"` (Claude subscription via the Agent SDK; `pip install "cat-stack[agent]"`), `"claude-code"` (the Claude Code CLI, if installed — no extra needed), and `"codex-agent"` (ChatGPT subscription; `pip install "cat-stack[codex-agent]"`). Classification, extraction, exploration, and summarization all route through them, including images and PDF pages on the two agent backends. They use the agent CLI's own sign-in (separate from the Claude desktop app's): runs check it up front and, if you're signed out, open a single browser window to sign in once, then continue. See the [cat-claws README](https://github.com/chrissoria/cat-agent#signing-in-once).
 
 **Reproducibility note:** the same nominal model can behave differently across access routes. In a seed-matched benchmark (Claude Sonnet 5, temperature 0), extraction through the Agent SDK produced more varied label phrasings than the direct API (89% vs. 74% unique raw labels), while final consolidated taxonomies were equivalent. If raw label counts matter to your analysis, record the access route alongside the model version.
 

{cat_stack-2.5.2 → cat_stack-2.5.4}/pyproject.toml

@@ -42,8 +42,8 @@ embeddings = ["sentence-transformers>=2.2.0"]
 # `agent` keeps its historical meaning (the Claude backend) so every shipped
 # install hint stays true; `codex-agent` matches the provider string so the
 # error-message hint is copy-pasteable.
-agent = ["cat-claws[claude]>=0.3.2"]
-codex-agent = ["cat-claws[codex]>=0.3.2"]
+agent = ["cat-claws[claude]>=0.3.3"]
+codex-agent = ["cat-claws[codex]>=0.3.3"]
 
 [project.urls]
 Documentation = "https://github.com/chrissoria/cat-stack#readme"

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

{cat_stack-2.5.2 → cat_stack-2.5.4}/src/catstack/_providers.py

@@ -790,6 +790,24 @@ def _split_agent_content(content):
     return "\n\n".join(t for t in texts if t), images
 
 
+def _require_agent_sign_in(provider):
+    """Preflight for the cat-claws subscription backends: stop before any row
+    runs when the agent CLI is signed out, instead of every row failing on
+    "not logged in". cat-claws >= 0.3.3 checks with a cheap status call (no
+    model call); if signed out it opens ONE browser sign-in automatically and
+    continues, or, where no browser can open, raises NotSignedInError with
+    instructions worded for the Claude app or a terminal. No-op for other
+    providers, and when cat-claws is missing or older.
+    """
+    if provider not in _AGENT_BACKENDS:
+        return
+    try:
+        from catclaws import ensure_signed_in
+    except ImportError:
+        return
+    ensure_signed_in(_AGENT_BACKENDS[provider][0])
+
+
 def _require_http_provider(model_source, feature):
     """Raise a clear error when an HTTP-only feature is used with a
     subscription/CLI provider (claude-code / claude-agent / codex-agent)."""

{cat_stack-2.5.2 → cat_stack-2.5.4}/src/catstack/image_functions.py

@@ -154,6 +154,8 @@ def image_multi_class(
             "(the text-only CLI shim). Use model_source='claude-agent' (the cat-claws "
             "subscription backend) or an API-key provider."
         )
+    from ._providers import _require_agent_sign_in
+    _require_agent_sign_in(model_source)
 
     image_files = _load_image_files(image_input)
 

{cat_stack-2.5.2 → cat_stack-2.5.4}/src/catstack/pdf_functions.py

@@ -399,6 +399,8 @@ def pdf_multi_class(
             "(the text-only CLI shim). Use model_source='claude-agent' (the cat-claws "
             "subscription backend) or an API-key provider."
         )
+    from ._providers import _require_agent_sign_in
+    _require_agent_sign_in(model_source)
 
     # Providers with native PDF support (only used in image/both modes)
     native_pdf_providers = {"anthropic", "google"}

{cat_stack-2.5.2 → cat_stack-2.5.4}/src/catstack/text_functions_ensemble.py

@@ -53,6 +53,7 @@ from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import Optional, Callable, Union
 
 from ._utils import _extract_balanced_json
+from ._providers import _require_agent_sign_in
 from .text_functions import (
     UnifiedLLMClient,
     detect_provider,
@@ -684,6 +685,7 @@ def prepare_model_configs(
                     "Install: pip install cat-stack[agent]\n"
                     + "="*60
                 )
+            _require_agent_sign_in(detected_provider)
         elif detected_provider == "codex-agent":
             try:
                 import catclaws  # noqa: F401
@@ -696,6 +698,7 @@ def prepare_model_configs(
                     'Install: pip install "cat-stack[codex-agent]"\n'
                     + "="*60
                 )
+            _require_agent_sign_in(detected_provider)
         else:
             # Validate API key exists for cloud providers
             if not api_key:
@@ -1487,6 +1490,53 @@ def _extract_json_for_summary(reply: str) -> str:
     return '{"summary": ""}'
 
 
+_FENCE_RE = re.compile(r"^\s*```(?:json)?\s*|\s*```\s*$", re.IGNORECASE)
+_THINK_RE = re.compile(r"<think>.*?</think>", re.DOTALL)
+# `"summary": "` ... last `"` ... then only closing braces / a fence
+_LENIENT_SUMMARY_RE = re.compile(r'"summary"\s*:\s*"(.*)"\s*\}*\s*(?:```)?\s*$', re.DOTALL)
+
+
+def _parse_summary_reply(reply) -> tuple:
+    """Read a summary out of a model reply as tolerantly as is safe.
+
+    Returns ``(json_str, error)``: ``json_str`` is a ``{"summary": ...}``
+    object and ``error`` is None, or ``error`` explains why no summary could
+    be read (so the row is retried and the reason reaches `error_message`,
+    instead of the row failing silently as it used to).
+
+    Tried in order:
+      1. strict: the first JSON object in the reply (code fences and
+         <think> blocks are fine);
+      2. lenient: a `"summary": "..."` object that is not valid JSON, most
+         often unescaped double quotes or raw newlines inside the text
+         (common with quoted category labels or non-English text);
+      3. prose: a reply with no JSON object at all is taken as the summary
+         itself (the model answered in plain text).
+    """
+    if reply is None or not str(reply).strip():
+        return '{"summary": ""}', "the model returned an empty reply"
+    text = _THINK_RE.sub("", str(reply)).strip()
+
+    json_str = _extract_json_for_summary(text)
+    ok, _ = extract_summary_from_json(json_str)
+    if ok:
+        return json_str, None
+
+    m = _LENIENT_SUMMARY_RE.search(text)
+    if m:
+        value = m.group(1).replace('\\"', '"').replace("\\n", "\n").strip()
+        if value:
+            return json.dumps({"summary": value}, ensure_ascii=False), None
+
+    if "{" not in text:
+        prose = _FENCE_RE.sub("", text).strip()
+        if prose:
+            return json.dumps({"summary": prose}, ensure_ascii=False), None
+
+    snippet = " ".join(text.split())[:200]
+    return '{"summary": ""}', f"could not read a summary from the model's reply: {snippet!r}"
+
+
 def extract_summary_from_json(json_str: str) -> tuple:
     """
     Extract summary from JSON response.
@@ -4227,10 +4277,10 @@ def summarize_ensemble(
                 if error:
                     return (model_name, '{"summary": ""}', error)
 
-                # Extract JSON from response
-                json_str = _extract_json_for_summary(response)
-
-                return (model_name, json_str, None)
+                # Read the summary; an unreadable reply is an error (retried,
+                # reported), never a silent empty summary
+                json_str, parse_error = _parse_summary_reply(response)
+                return (model_name, json_str, parse_error)
 
             except Exception as e:
                 error_msg = str(e)
@@ -4291,8 +4341,8 @@ def summarize_ensemble(
                 if error:
                     return (model_name, '{"summary": ""}', error)
 
-                json_str = _extract_json_for_summary(response)
-                return (model_name, json_str, None)
+                json_str, parse_error = _parse_summary_reply(response)
+                return (model_name, json_str, parse_error)
 
             except Exception as e:
                 return (model_name, '{"summary": ""}', str(e))
@@ -4343,10 +4393,10 @@ def summarize_ensemble(
                 if error:
                     return (model_name, '{"summary": ""}', error)
 
-                # Extract JSON from response
-                json_str = _extract_json_for_summary(response)
-
-                return (model_name, json_str, None)
+                # Read the summary; an unreadable reply is an error (retried,
+                # reported), never a silent empty summary
+                json_str, parse_error = _parse_summary_reply(response)
+                return (model_name, json_str, parse_error)
 
             except Exception as e:
                 error_msg = str(e)
@@ -4732,7 +4782,7 @@ Provide your answer in JSON format: {{"summary": "your synthesized summary"}}"""
             max_retries=max_retries,
         )
 
-        json_str = _extract_json_for_summary(response)
+        json_str, _ = _parse_summary_reply(response)
         is_valid, summary = extract_summary_from_json(json_str)
 
         if is_valid: