cat-stack 2.5.1__tar.gz → 2.5.3__tar.gz

{cat_stack-2.5.1 → cat_stack-2.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: cat-stack
-Version: 2.5.1
+Version: 2.5.3
 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.1; extra == 'agent'
+Requires-Dist: cat-claws[claude]>=0.3.3; extra == 'agent'
 Provides-Extra: codex-agent
-Requires-Dist: cat-claws[codex]>=0.3.1; 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,9 @@ 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.
 
 ## Features
 

{cat_stack-2.5.1 → cat_stack-2.5.3}/README.md

@@ -198,7 +198,9 @@ 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.
 
 ## Features
 

{cat_stack-2.5.1 → cat_stack-2.5.3}/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.1"]
-codex-agent = ["cat-claws[codex]>=0.3.1"]
+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.1 → cat_stack-2.5.3}/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.1"
+__version__ = "2.5.3"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-stack"

{cat_stack-2.5.1 → cat_stack-2.5.3}/src/catstack/_providers.py

@@ -735,8 +735,10 @@ PROVIDER_CONFIG = {
 
 
 # Providers that route through complete() with no HTTP endpoint of their own
-# (subscription logins / CLI). Features that build a direct HTTP request
-# (image, PDF) can't use them — guard with a clear error, not a deep crash.
+# (subscription logins / CLI). Features that build a direct HTTP request can't
+# use them — guard with a clear error, not a deep crash. (Images and PDF pages
+# DO work on the cat-claws agent backends: they go through the adapters'
+# images= argument, see _split_agent_content / _call_agent_image.)
 _SUBSCRIPTION_PROVIDERS = ("claude-code", "claude-agent", "codex-agent")
 
 # Agent-SDK backends routed through cat-claws: provider -> (adapter name,
@@ -748,6 +750,64 @@ _AGENT_BACKENDS = {
 }
 
 
+def _split_agent_content(content):
+    """Split one message's content into (text, images) for the cat-claws
+    adapters.
+
+    Plain-string content is text only. Multimodal content is a list of blocks
+    in whichever provider shape the prompt builder produced (Anthropic
+    `image` + base64 `source`, OpenAI `image_url` data URL, Google
+    `inline_data`); text blocks are joined and image blocks become the
+    adapters' ``{"media_type", "data"}`` dicts. Unknown block types are
+    dropped rather than stringified into the prompt.
+    """
+    if not isinstance(content, list):
+        return content, []
+    texts, images = [], []
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        kind = block.get("type")
+        if kind == "text":
+            texts.append(block.get("text", ""))
+        elif kind == "image":
+            src = block.get("source") or {}
+            if src.get("type") == "base64" and src.get("data"):
+                images.append({"media_type": src.get("media_type") or "image/png",
+                               "data": src["data"]})
+        elif kind == "image_url":
+            url = (block.get("image_url") or {}).get("url", "")
+            if url.startswith("data:") and ";base64," in url:
+                header, data = url.split(",", 1)
+                images.append({"media_type": header[5:].split(";", 1)[0] or "image/png",
+                               "data": data})
+        elif kind == "inline_data" and block.get("data"):
+            images.append({"media_type": block.get("mime_type") or "image/png",
+                           "data": block["data"]})
+    for im in images:  # the API wants image/jpeg, not image/jpg
+        if im["media_type"] == "image/jpg":
+            im["media_type"] = "image/jpeg"
+    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)."""
@@ -1272,17 +1332,26 @@ class UnifiedLLMClient:
             )
         import asyncio
 
+        # Multimodal content (image summaries, rendered PDF pages) arrives as
+        # a list of blocks: text goes to the prompt, images to the adapter's
+        # `images=` argument (base.AgentAdapter.one_shot contract).
         system_parts = []
         user_parts = []
+        images = []
         for msg in messages:
+            text, msg_images = _split_agent_content(msg["content"])
             if msg["role"] == "system":
-                system_parts.append(msg["content"])
+                system_parts.append(text)
             elif msg["role"] in ("user", "assistant"):
-                user_parts.append(msg["content"])
+                user_parts.append(text)
+                images.extend(msg_images)
         system_prompt = "\n\n".join(system_parts) if system_parts else None
         user_prompt = "\n\n".join(user_parts)
 
         adapter = get_adapter(adapter_name)
+        # Only pass images when there are some, so text-only calls are
+        # byte-identical to before.
+        image_kwargs = {"images": images} if images else {}
         try:
             return asyncio.run(
                 adapter.one_shot(
@@ -1290,6 +1359,7 @@ class UnifiedLLMClient:
                     system_prompt=system_prompt,
                     model=self.model,
                     thinking_budget=thinking_budget or 0,
+                    **image_kwargs,
                 )
             )
         except Exception as e:

{cat_stack-2.5.1 → cat_stack-2.5.3}/src/catstack/image_functions.py

@@ -154,12 +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."
         )
-    if model_source == "codex-agent":
-        raise ValueError(
-            "Image classification is not yet supported with "
-            "model_source='codex-agent'. Use model_source='claude-agent' (the "
-            "multimodal 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)
 
@@ -677,15 +673,18 @@ Provide the final categorization in the same JSON format:"""
 
         return """{"1":"e"}""", "Max retries exceeded"
 
-    def _call_claude_agent_image(base_text, encoded, media_type):
-        """Image classification via the cat-claws multimodal adapter (Claude
-        subscription, no API key). Returns (reply, error) like _call_anthropic."""
+    def _call_agent_image(base_text, encoded, media_type):
+        """Image classification via a cat-claws multimodal adapter
+        (claude-agent or codex-agent: subscription login, no API key).
+        Returns (reply, error) like _call_anthropic."""
+        from ._providers import _AGENT_BACKENDS
+        adapter_name, install_hint = _AGENT_BACKENDS[model_source]
         try:
             from catclaws._adapters import get_adapter
         except ImportError:
-            return None, ("cat-claws is not installed. Run: pip install cat-stack[agent]")
+            return None, f"cat-claws is not installed. Run: {install_hint}"
         import asyncio
-        adapter = get_adapter("claude")
+        adapter = get_adapter(adapter_name)
         _system = ("You are an image classification engine. Follow the user's "
                    "instructions exactly and reply with only what they ask for.")
         try:
@@ -738,9 +737,11 @@ Provide the final categorization in the same JSON format:"""
             image_content = {"type": "image_url", "image_url": {"url": encoded_image, "detail": "high"}}
             return _call_mistral(prompt, step2_prompt, step3_prompt, step4_prompt, image_content)
 
-        elif model_source == "claude-agent":
+        elif model_source in ("claude-agent", "codex-agent"):
             media_type = f"image/{ext}" if ext else "image/jpeg"
-            return _call_claude_agent_image(base_prompt_text, encoded, media_type)
+            if media_type == "image/jpg":
+                media_type = "image/jpeg"
+            return _call_agent_image(base_prompt_text, encoded, media_type)
 
         else:
             raise ValueError("Unknown source! Choose from OpenAI, Anthropic, Perplexity, Google, xAI, Huggingface, or Mistral")

{cat_stack-2.5.1 → cat_stack-2.5.3}/src/catstack/pdf_functions.py

@@ -399,12 +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."
         )
-    if model_source == "codex-agent":
-        raise ValueError(
-            "PDF classification is not yet supported with "
-            "model_source='codex-agent'. Use model_source='claude-agent' (the "
-            "multimodal 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"}
@@ -1192,23 +1188,27 @@ Provide the final categorization in the same JSON format:"""
 
         return """{"1":"e"}""", "Max retries exceeded"
 
-    def _call_claude_agent_pdf(base_text, encoded_image):
-        """PDF-page classification via the cat-claws multimodal adapter. The page
-        is rendered to an image (PDF-as-images); Claude subscription, no API key.
-        Returns (reply, error)."""
+    def _call_agent_pdf(base_text, encoded_image):
+        """PDF-page classification via a cat-claws adapter (claude-agent or
+        codex-agent: subscription login, no API key). The page is rendered to
+        an image (PDF-as-images); encoded_image=None sends text only (mode
+        "text"). Returns (reply, error)."""
+        from ._providers import _AGENT_BACKENDS
+        adapter_name, install_hint = _AGENT_BACKENDS[model_source]
         try:
             from catclaws._adapters import get_adapter
         except ImportError:
-            return None, ("cat-claws is not installed. Run: pip install cat-stack[agent]")
+            return None, f"cat-claws is not installed. Run: {install_hint}"
         import asyncio
-        adapter = get_adapter("claude")
+        adapter = get_adapter(adapter_name)
         _system = ("You are a document-page classification engine. Follow the "
                    "user's instructions exactly and reply with only what they ask for.")
         try:
             reply, error = asyncio.run(adapter.one_shot(
                 base_text, system_prompt=_system, model=user_model,
                 thinking_budget=thinking_budget or 0,
-                images=[{"media_type": "image/png", "data": encoded_image}],
+                **({"images": [{"media_type": "image/png", "data": encoded_image}]}
+                   if encoded_image else {}),
             ))
             return (None, error) if error else (reply, None)
         except Exception as e:
@@ -1244,6 +1244,8 @@ Provide the final categorization in the same JSON format:"""
                 return _call_openai_text_only(base_prompt_text, step2_prompt, step3_prompt, step4_prompt)
             elif model_source == "mistral":
                 return _call_mistral_text_only(base_prompt_text, step2_prompt, step3_prompt, step4_prompt)
+            elif model_source in ("claude-agent", "codex-agent"):
+                return _call_agent_pdf(base_prompt_text, None)
             else:
                 raise ValueError(f"Unknown source! Choose from OpenAI, Anthropic, Perplexity, Google, xAI, Huggingface, or Mistral")
 
@@ -1293,12 +1295,12 @@ Provide the final categorization in the same JSON format:"""
             prompt_data = _build_prompt_google_pdf(encoded_pdf, base_prompt_text)
             return _call_google(prompt_data, step2_prompt, step3_prompt, step4_prompt, base_prompt_text)
 
-        elif model_source == "claude-agent":
+        elif model_source in ("claude-agent", "codex-agent"):
             image_bytes, is_valid = _extract_page_as_image_bytes(pdf_path, page_index)
             if not is_valid:
                 return None, "Failed to render PDF page to image"
             encoded_image = _encode_bytes_to_base64(image_bytes)
-            return _call_claude_agent_pdf(base_prompt_text, encoded_image)
+            return _call_agent_pdf(base_prompt_text, encoded_image)
 
         # Handle providers requiring image conversion
         else:

{cat_stack-2.5.1 → cat_stack-2.5.3}/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:
@@ -3863,6 +3866,17 @@ multi_class_ensemble = classify_ensemble
 # Summarization helpers
 # =============================================================================
 
+def _format_item_errors(errors: dict, multi_model: bool) -> str:
+    """One row's failure reasons for the `error_message` column: the bare
+    message for a single model, "model: message" pairs for an ensemble.
+    Empty string when the row had no errors."""
+    if not errors:
+        return ""
+    if not multi_model:
+        return "; ".join(str(e) for e in errors.values())
+    return "; ".join(f"{m}: {e}" for m, e in errors.items())
+
+
 def _save_partial_summarize_results(all_results, model_configs, model_names, is_pdf_mode, filename, save_directory):
     """Save partial summarization results to CSV for safety/incremental saves."""
     rows = []
@@ -3895,6 +3909,7 @@ def _save_partial_summarize_results(all_results, model_configs, model_names, is_
             ) else "partial"
         else:
             row["processing_status"] = "success"
+        row["error_message"] = _format_item_errors(entry["errors"], len(model_configs) > 1)
 
         rows.append(row)
 
@@ -4511,6 +4526,9 @@ def summarize_ensemble(
 
             if error and error != "skipped":
                 still_failed.append((idx, model_name))
+                # Keep the latest reason so the output reports what the
+                # final attempt actually hit.
+                all_results[idx]["errors"][model_name] = error
             else:
                 # Update the stored result
                 all_results[idx]["model_results"][model_name] = json_result
@@ -4631,10 +4649,20 @@ def summarize_ensemble(
         else:
             row["processing_status"] = "success"
 
+        # Why a row failed: previously collected per item but never written
+        # out, so failures were silent (status "error", no reason).
+        row["error_message"] = _format_item_errors(entry["errors"], len(model_configs) > 1)
+
         rows.append(row)
 
     df = pd.DataFrame(rows)
 
+    n_failed = int((df["error_message"] != "").sum()) if "error_message" in df else 0
+    if n_failed:
+        first = df.loc[df["error_message"] != "", "error_message"].iloc[0]
+        print(f"\n[CatLLM] WARNING: {n_failed} of {len(df)} item(s) had errors "
+              f"(see the error_message column). First error: {first}")
+
     # Save to file if requested
     if filename:
         save_path = os.path.join(save_directory, filename) if save_directory else filename