cat-stack 2.2.0__tar.gz → 2.4.0__tar.gz

{cat_stack-2.2.0 → cat_stack-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-stack
-Version: 2.2.0
+Version: 2.4.0
 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
@@ -19,11 +19,14 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Requires-Python: >=3.8
+Requires-Dist: jellyfish
 Requires-Dist: pandas
 Requires-Dist: requests
 Requires-Dist: tqdm
 Provides-Extra: agent
-Requires-Dist: cat-claws>=0.1.0; extra == 'agent'
+Requires-Dist: cat-claws[claude]>=0.3.0; extra == 'agent'
+Provides-Extra: codex-agent
+Requires-Dist: cat-claws[codex]>=0.3.0; extra == 'codex-agent'
 Provides-Extra: docx
 Requires-Dist: python-docx>=1.0.0; extra == 'docx'
 Provides-Extra: embeddings

{cat_stack-2.2.0 → cat_stack-2.4.0}/pyproject.toml

@@ -28,6 +28,10 @@ dependencies = [
   "pandas",
   "tqdm",
   "requests",
+  # collapse_themes.py imports jellyfish at module top (and catstack/__init__
+  # imports collapse_themes eagerly), so every fresh install needs it —
+  # undeclared, it broke `import catstack` in clean environments.
+  "jellyfish",
 ]
 
 [project.optional-dependencies]
@@ -35,7 +39,11 @@ pdf = ["PyMuPDF>=1.23.0"]
 docx = ["python-docx>=1.0.0"]
 formatter = ["torch>=2.0.0", "transformers>=4.40.0", "accelerate>=0.27.0"]
 embeddings = ["sentence-transformers>=2.2.0"]
-agent = ["cat-claws>=0.1.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.0"]
+codex-agent = ["cat-claws[codex]>=0.3.0"]
 
 [project.urls]
 Documentation = "https://github.com/chrissoria/cat-stack#readme"

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

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/_batch.py

@@ -65,7 +65,7 @@ BATCH_ENDPOINTS = {
     },
 }
 
-UNSUPPORTED_BATCH_PROVIDERS = {"huggingface", "huggingface-together", "perplexity", "ollama", "claude-code", "claude-agent"}
+UNSUPPORTED_BATCH_PROVIDERS = {"huggingface", "huggingface-together", "perplexity", "ollama", "claude-code", "claude-agent", "codex-agent"}
 
 # Terminal states per provider
 _TERMINAL_STATES = {
@@ -928,11 +928,17 @@ def _run_one_sync_model(
             system_prompt=prompt_params.get("system_prompt", ""),
         )
         try:
+            # Pass thinking_budget through unchanged (including explicit 0 =
+            # "reasoning off") — apply_model_params translates 0 into each
+            # provider's off form, exactly like the non-batch sync path, and
+            # complete() has the 400 strip-and-retry net for providers that
+            # reject it. Nullifying 0 here left Qwen3/Ollama-family rows in
+            # the batch sync fallback reasoning at provider default.
             raw, err = client.complete(
                 messages=messages,
                 json_schema=json_schema,
                 creativity=creativity,
-                thinking_budget=thinking_budget if thinking_budget and thinking_budget > 0 else None,
+                thinking_budget=thinking_budget,
             )
             if err:
                 item_results[idx] = (None, err)

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/_chunked.py

@@ -48,6 +48,7 @@ def run_chunked_classification(
     thinking_budget,
     max_retries,
     multi_label,
+    system_prompt="",
     categories_per_call,
     add_unified_other=False,
     formatter_fallback_fn,
@@ -149,6 +150,7 @@ Categorize text responses {cove_categorize}:
             thinking_budget=thinking_budget,
             max_retries=max_retries,
             multi_label=multi_label,
+            system_prompt=system_prompt,
             formatter_fallback_fn=formatter_fallback_fn,
             is_pdf_mode=is_pdf_mode,
             is_image_mode=is_image_mode,
@@ -228,6 +230,7 @@ def _run_single_chunk_call(
     thinking_budget,
     max_retries,
     multi_label,
+    system_prompt="",
     formatter_fallback_fn,
     is_pdf_mode,
     is_image_mode,
@@ -366,7 +369,7 @@ def _run_single_chunk_call(
         response_text = item
 
         if cfg["use_two_step"]:  # Ollama
-            json_result, error = ollama_two_step_classify(
+            json_result, _step1_raw, error = ollama_two_step_classify(
                 client=client,
                 response_text=response_text,
                 categories=chunk_cats,
@@ -390,6 +393,7 @@ def _run_single_chunk_call(
                 stepback_insights=stepback_insights,
                 model_name=cfg["model"],
                 multi_label=multi_label,
+                system_prompt=system_prompt,
             )
             reply, error = client.complete(
                 messages=messages,

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/_providers.py

@@ -726,22 +726,35 @@ PROVIDER_CONFIG = {
         "auth_header": None,
         "auth_prefix": "",
     },
+    "codex-agent": {
+        "endpoint": None,  # Uses the cat-claws SDK adapter, not HTTP
+        "auth_header": None,
+        "auth_prefix": "",
+    },
 }
 
 
 # Providers that route through complete() with no HTTP endpoint of their own
-# (Claude subscription / CLI). Features that build a direct HTTP request
+# (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_PROVIDERS = ("claude-code", "claude-agent")
+_SUBSCRIPTION_PROVIDERS = ("claude-code", "claude-agent", "codex-agent")
+
+# Agent-SDK backends routed through cat-claws: provider -> (adapter name,
+# install hint). Both run on subscription logins (no API key); the hint names
+# the cat-stack extra that pulls the matching cat-claws SDK extra.
+_AGENT_BACKENDS = {
+    "claude-agent": ("claude", "pip install cat-stack[agent]"),
+    "codex-agent": ("codex", 'pip install "cat-stack[codex-agent]"'),
+}
 
 
 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)."""
+    subscription/CLI provider (claude-code / claude-agent / codex-agent)."""
     if model_source in _SUBSCRIPTION_PROVIDERS:
         raise ValueError(
             f"{feature} is not supported with model_source='{model_source}'. "
-            "The Claude subscription/CLI backend supports text classification, "
+            "The subscription/CLI backends support text classification, "
             "extraction, and summarization, but not " + feature.lower() + ". "
             "Use an API-key provider (e.g. model_source='anthropic') instead."
         )
@@ -1229,29 +1242,33 @@ class UnifiedLLMClient:
             # contract that callers depend on.
             return None, f"Claude CLI subprocess failed: {e} (prompt may be too large for argv)"
 
-    def _call_claude_agent(
+    def _call_agent_backend(
         self,
         messages: list,
         thinking_budget: int = None,
     ) -> tuple[str, str | None]:
-        """Route one completion through the cat-claws SDK adapter.
+        """Route one completion through a cat-claws SDK adapter (the
+        `claude-agent` and `codex-agent` providers — see _AGENT_BACKENDS).
 
-        Like `_call_claude_cli`, this runs on the user's Claude subscription
-        (no API key) and returns the same (text, error) contract. cat-claws is
-        an optional dependency (the `[agent]` extra); a missing install
-        degrades to a clear install hint rather than an ImportError traceback.
+        Like `_call_claude_cli`, these run on the user's subscription login
+        (no API key) and return the same (text, error) contract. cat-claws is
+        an optional dependency; a missing install degrades to a clear install
+        hint rather than an ImportError traceback. One shared body, table-
+        driven: near-duplicate provider branches are how the image-CoVe
+        silent no-op happened.
 
         The adapter is async. complete() is sync and may run inside ensemble
         worker threads, so we drive one sealed call per invocation with
         asyncio.run (a fresh loop per call) - never a shared/module-global
         loop. Message flattening mirrors _call_claude_cli exactly.
         """
+        adapter_name, install_hint = _AGENT_BACKENDS[self.provider]
         try:
             from catclaws._adapters import get_adapter
         except ImportError:
             return None, (
                 "cat-claws is not installed. Install it to use "
-                "model_source='claude-agent': pip install cat-stack[agent]"
+                f"model_source='{self.provider}': {install_hint}"
             )
         import asyncio
 
@@ -1265,7 +1282,7 @@ class UnifiedLLMClient:
         system_prompt = "\n\n".join(system_parts) if system_parts else None
         user_prompt = "\n\n".join(user_parts)
 
-        adapter = get_adapter("claude")
+        adapter = get_adapter(adapter_name)
         try:
             return asyncio.run(
                 adapter.one_shot(
@@ -1321,8 +1338,8 @@ class UnifiedLLMClient:
         if self.provider == "claude-code":
             return self._call_claude_cli(messages, max_retries=max_retries, initial_delay=initial_delay)
 
-        if self.provider == "claude-agent":
-            return self._call_claude_agent(messages, thinking_budget=thinking_budget)
+        if self.provider in _AGENT_BACKENDS:
+            return self._call_agent_backend(messages, thinking_budget=thinking_budget)
 
         headers = self._get_headers()
         payload = self._build_payload(messages, json_schema, creativity, thinking_budget=thinking_budget, force_json=force_json)
@@ -1818,6 +1835,8 @@ def _detect_model_source(user_model, model_source):
         return "claude-code"
     if model_source and model_source.lower() == "claude-agent":
         return "claude-agent"
+    if model_source and model_source.lower() == "codex-agent":
+        return "codex-agent"
     return detect_provider(user_model, provider=model_source)
 
 

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/_tiebreaker.py

@@ -89,15 +89,20 @@ def _find_confident_and_tied_rows(all_results, category_key, threshold):
         positive_count = sum(votes)
         positive_rate = positive_count / num_models
 
-        # Check for true tie: positive_rate == threshold exactly
-        if abs(positive_rate - threshold) < 1e-9:
-            tied.append(row_idx)
-        elif positive_rate == 1.0:
+        # Unanimous rows are confident by definition and must be bucketed
+        # BEFORE the tie test: with consensus_threshold="unanimous" (the
+        # classify() default, threshold=1.0) every all-positive row sits
+        # exactly at the threshold, and testing ties first classified them
+        # all as "tied" — leaving zero confident rows to build centroids from.
+        if positive_rate == 1.0:
             # All models agree positive
             confident_pos.append(row_idx)
         elif positive_rate == 0.0:
             # All models agree negative
             confident_neg.append(row_idx)
+        # Check for true tie: positive_rate == threshold exactly
+        elif abs(positive_rate - threshold) < 1e-9:
+            tied.append(row_idx)
 
     return confident_pos, confident_neg, tied
 

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/_utils.py

@@ -249,6 +249,14 @@ def ollama_two_step_classify(
     Returns:
         tuple: (json_string, error_message or None)
     """
+    # Lazy import — extract_json lives in text_functions (which imports this
+    # module at its top, so a module-level import here would be circular).
+    # Without it this function raised NameError on every successful Step 2.
+    # NOTE: text_functions.ollama_two_step_classify is the maintained copy
+    # (3-tuple return, exposes the step-1 raw reply); this 2-tuple variant is
+    # kept only so the _utils export keeps working.
+    from .text_functions import extract_json
+
     num_categories = len(categories)
     survey_context = f"Context: {survey_question}." if survey_question else ""
 
@@ -376,6 +384,7 @@ def _get_stepback_insight(model_source, stepback, api_key, user_model, creativit
         "mistral": get_stepback_insight_mistral,
         "claude-code": get_stepback_insight_via_complete,
         "claude-agent": get_stepback_insight_via_complete,
+        "codex-agent": get_stepback_insight_via_complete,
     }
 
     func = stepback_functions.get(model_source)

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/_wrapper_helpers.py

@@ -143,7 +143,10 @@ def parse_kwargs_string(s: Optional[str]) -> Dict[str, Any]:
             buf.append(ch)
             if ch == quote_char:
                 quote_char = None
-        elif ch in ('"', "'"):
+        elif ch in ('"', "'") and (not buf or buf[-1] in " =,([{"):
+            # Open a quote only at a value boundary — an apostrophe inside
+            # unquoted prose ("don't", "it's") must not start a "string"
+            # that swallows every following top-level comma and key=val pair.
             quote_char = ch
             buf.append(ch)
         elif ch in "([{":

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/calls/image_CoVe.py

@@ -7,38 +7,59 @@ def image_chain_of_verification_openai(
     step2_prompt,
     step3_prompt,
     step4_prompt,
-    client,
+    client,  # Deprecated, kept for backward compatibility
     user_model,
     creativity,
     remove_numbering,
-    image_content
+    image_content,
+    api_key=None,
+    base_url=None,
 ):
     """
-    Execute Chain of Verification (CoVe) process for images with OpenAI.
-    The image is included in verification steps for accurate assessment.
+    Execute Chain of Verification (CoVe) process for images with OpenAI-compatible
+    providers. The image is included in verification steps for accurate assessment.
     Returns the verified reply or initial reply if error occurs.
 
+    Uses direct HTTP requests instead of the OpenAI SDK so the function works for
+    any OpenAI-compatible provider (OpenAI, Perplexity, HuggingFace, xAI, ...) given
+    the right `base_url`.
+
     Args:
-        image_content: The image content in OpenAI format (list with image_url dict)
+        image_content: The image content in OpenAI format (image_url dict)
+        api_key: Bearer token for the provider.
+        base_url: Provider root URL (e.g. https://api.openai.com/v1). Defaults to OpenAI.
     """
-    try:
+    import requests
+
+    if api_key is None:
+        return initial_reply
+
+    endpoint = (base_url or "https://api.openai.com/v1").rstrip("/") + "/chat/completions"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+    }
+
+    def make_openai_request(messages, json_mode=False):
+        payload = {"model": user_model, "messages": messages}
         # Sampling params via the shared shaper (skips temperature for OpenAI
-        # reasoning models, which reject non-default values). Computed once,
-        # reused across the 3 steps.
+        # reasoning models, which reject non-default values).
         from cat_stack._providers import apply_model_params
-        _params = apply_model_params({}, "openai", user_model, creativity=creativity)
+        apply_model_params(payload, "openai", user_model, creativity=creativity)
+        if json_mode:
+            payload["response_format"] = {"type": "json_object"}
+        response = requests.post(endpoint, headers=headers, json=payload, timeout=120)
+        response.raise_for_status()
+        result = response.json()
+        return result["choices"][0]["message"]["content"]
 
+    try:
         # STEP 2: Generate verification questions (text only - questions about the categorization)
         step2_filled = step2_prompt.replace('<<INITIAL_REPLY>>', initial_reply)
-
-        verification_response = client.chat.completions.create(
-            model=user_model,
-            messages=[{'role': 'user', 'content': step2_filled}],
-            **_params
+        verification_questions = make_openai_request(
+            [{'role': 'user', 'content': step2_filled}]
         )
 
-        verification_questions = verification_response.choices[0].message.content
-
         # STEP 3: Answer verification questions WITH the image
         questions_list = [
             remove_numbering(q)
@@ -46,50 +67,33 @@ def image_chain_of_verification_openai(
             if q.strip()
         ]
         verification_qa = []
-
         for question in questions_list:
             step3_filled = step3_prompt.replace('<<QUESTION>>', question)
-
-            # Include image in the verification question
             message_content = [
                 {"type": "text", "text": step3_filled},
                 image_content
             ]
-
-            answer_response = client.chat.completions.create(
-                model=user_model,
-                messages=[{'role': 'user', 'content': message_content}],
-                **_params
+            answer = make_openai_request(
+                [{'role': 'user', 'content': message_content}]
             )
-
-            answer = answer_response.choices[0].message.content
             verification_qa.append(f"Q: {question}\nA: {answer}")
 
         # STEP 4: Final corrected categorization WITH the image
         verification_qa_text = "\n\n".join(verification_qa)
-
         step4_filled = (step4_prompt
             .replace('<<INITIAL_REPLY>>', initial_reply)
             .replace('<<VERIFICATION_QA>>', verification_qa_text))
-
-        # Include image in final categorization
         final_message_content = [
             {"type": "text", "text": step4_filled},
             image_content
         ]
-
-        final_response = client.chat.completions.create(
-            model=user_model,
-            messages=[{'role': 'user', 'content': final_message_content}],
-            response_format={"type": "json_object"},
-            **_params
+        verified_reply = make_openai_request(
+            [{'role': 'user', 'content': final_message_content}],
+            json_mode=True,
         )
-
-        verified_reply = final_response.choices[0].message.content
-
         return verified_reply
 
-    except Exception as e:
+    except Exception:
         return initial_reply
 
 
@@ -318,37 +322,54 @@ def image_chain_of_verification_mistral(
     step2_prompt,
     step3_prompt,
     step4_prompt,
-    client,
+    client,  # Deprecated, kept for backward compatibility
     user_model,
     creativity,
     remove_numbering,
-    image_content
+    image_content,
+    api_key=None,
 ):
     """
     Execute Chain of Verification (CoVe) process for images with Mistral AI.
     The image is included in verification steps for accurate assessment.
     Returns the verified reply or initial reply if error occurs.
 
+    Uses direct HTTP requests instead of the mistralai SDK.
+
     Args:
         image_content: The image content in Mistral format (dict with image_url)
+        api_key: Mistral API key.
     """
-    try:
-        # Sampling params via the shared shaper. Computed once, reused
-        # across the 3 steps.
+    import requests
+
+    if api_key is None:
+        return initial_reply
+
+    endpoint = "https://api.mistral.ai/v1/chat/completions"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+    }
+
+    def make_mistral_request(messages, json_mode=False):
+        payload = {"model": user_model, "messages": messages}
+        # Sampling params via the shared shaper.
         from cat_stack._providers import apply_model_params
-        _params = apply_model_params({}, "mistral", user_model, creativity=creativity)
+        apply_model_params(payload, "mistral", user_model, creativity=creativity)
+        if json_mode:
+            payload["response_format"] = {"type": "json_object"}
+        response = requests.post(endpoint, headers=headers, json=payload, timeout=120)
+        response.raise_for_status()
+        result = response.json()
+        return result["choices"][0]["message"]["content"]
 
+    try:
         # STEP 2: Generate verification questions (text only)
         step2_filled = step2_prompt.replace('<<INITIAL_REPLY>>', initial_reply)
-
-        verification_response = client.chat.complete(
-            model=user_model,
-            messages=[{'role': 'user', 'content': step2_filled}],
-            **_params
+        verification_questions = make_mistral_request(
+            [{'role': 'user', 'content': step2_filled}]
         )
 
-        verification_questions = verification_response.choices[0].message.content
-
         # STEP 3: Answer verification questions WITH the image
         questions_list = [
             remove_numbering(q)
@@ -356,48 +377,31 @@ def image_chain_of_verification_mistral(
             if q.strip()
         ]
         verification_qa = []
-
         for question in questions_list:
             step3_filled = step3_prompt.replace('<<QUESTION>>', question)
-
-            # Include image in the verification question
             message_content = [
                 {"type": "text", "text": step3_filled},
                 image_content
             ]
-
-            answer_response = client.chat.complete(
-                model=user_model,
-                messages=[{'role': 'user', 'content': message_content}],
-                **_params
+            answer = make_mistral_request(
+                [{'role': 'user', 'content': message_content}]
             )
-
-            answer = answer_response.choices[0].message.content
             verification_qa.append(f"Q: {question}\nA: {answer}")
 
         # STEP 4: Final corrected categorization WITH the image
         verification_qa_text = "\n\n".join(verification_qa)
-
         step4_filled = (step4_prompt
             .replace('<<INITIAL_REPLY>>', initial_reply)
             .replace('<<VERIFICATION_QA>>', verification_qa_text))
-
-        # Include image in final categorization
         final_message_content = [
             {"type": "text", "text": step4_filled},
             image_content
         ]
-
-        final_response = client.chat.complete(
-            model=user_model,
-            messages=[{'role': 'user', 'content': final_message_content}],
-            response_format={"type": "json_object"},
-            **_params
+        verified_reply = make_mistral_request(
+            [{'role': 'user', 'content': final_message_content}],
+            json_mode=True,
         )
-
-        verified_reply = final_response.choices[0].message.content
-
         return verified_reply
 
-    except Exception as e:
+    except Exception:
         return initial_reply

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/calls/stepback.py

@@ -199,8 +199,9 @@ def get_stepback_insight_via_complete(
 ):
     """Stepback insight via the central UnifiedLLMClient.complete().
 
-    For providers with no direct HTTP endpoint (claude-agent / claude-code),
-    which route through complete() rather than a provider-specific requests.post.
+    For providers with no direct HTTP endpoint (claude-agent / codex-agent /
+    claude-code), which route through complete() rather than a
+    provider-specific requests.post.
     Returns (insight_text, True) on success, (None, False) otherwise.
     """
     from cat_stack._providers import UnifiedLLMClient

{cat_stack-2.2.0 → cat_stack-2.4.0}/src/catstack/classify.py

@@ -483,6 +483,7 @@ def classify(
     if check_verbosity and categories and categories != "auto":
         # Extract API key and provider from first model entry
         first_entry = models[0]
+        check_model = first_entry[0] if len(first_entry) >= 1 else None
         check_key = first_entry[2] if len(first_entry) >= 3 else None
         check_source = first_entry[1] if len(first_entry) >= 2 else "auto"
 
@@ -491,6 +492,7 @@ def classify(
                 verbosity = check_category_verbosity(
                     categories,
                     api_key=check_key,
+                    user_model=check_model,
                     model_source=check_source,
                 )
                 lacking = [r for r in verbosity if not r["is_verbose"]]
@@ -530,7 +532,9 @@ def classify(
     if pilot_test and categories and categories != "auto":
         from ._pilot_test import run_pilot_test
 
-        pilot_sample_size = pilot_test if isinstance(pilot_test, int) else 10
+        # bool is an int subclass — pilot_test=True must mean "10 items",
+        # not a sample of size 1
+        pilot_sample_size = pilot_test if isinstance(pilot_test, int) and not isinstance(pilot_test, bool) else 10
 
         # Build kwargs that mirror what classify() passes to classify_ensemble
         _pilot_ensemble_kwargs = dict(
@@ -564,6 +568,9 @@ def classify(
             consensus_threshold=consensus_threshold,
             multi_label=multi_label,
             input_mode=input_mode,
+            system_prompt=system_prompt,
+            two_step_classify=two_step_classify,
+            categories_per_call=categories_per_call,
         )
 
         pilot_result = run_pilot_test(
@@ -584,7 +591,9 @@ def classify(
     if prompt_tune and categories and categories != "auto":
         from .prompt_tune import prompt_tune as _prompt_tune
 
-        tune_sample_size = prompt_tune if isinstance(prompt_tune, int) else 10
+        # bool is an int subclass — prompt_tune=True must mean "10 items",
+        # not a sample of size 1
+        tune_sample_size = prompt_tune if isinstance(prompt_tune, int) and not isinstance(prompt_tune, bool) else 10
 
         tune_result = _prompt_tune(
             input_data=input_data,
@@ -916,8 +925,19 @@ def classify(
         from ._batch import UNSUPPORTED_BATCH_PROVIDERS, run_batch_classify
         from .text_functions_ensemble import prepare_json_schemas, prepare_model_configs
 
+        # Guard: batch mode can't auto-discover categories (that happens in
+        # classify_ensemble, which batch mode bypasses) — without this,
+        # enumerate("auto") would silently classify into the four one-letter
+        # categories "a", "u", "t", "o".
+        if categories == "auto":
+            raise ValueError(
+                "categories='auto' is not supported with batch_mode=True. "
+                "Discover categories first (e.g. with cat_stack.explore()) and pass "
+                "the resulting list, or set batch_mode=False."
+            )
+
         # Guard: text input only (auto-detect)
-        from .text_functions_ensemble import _detect_input_type
+        from .text_functions_ensemble import _convert_docx_to_text, _detect_input_type
         detected_type = _detect_input_type(input_data)
         if detected_type in ("pdf", "image"):
             if input_mode == "text":
@@ -929,6 +949,12 @@ def classify(
                 f"batch_mode=True only supports text input, but detected input type is '{detected_type}'. "
                 "Set batch_mode=False for PDF/image classification."
             )
+        if detected_type == "docx":
+            # Mirror the sync path (classify_ensemble): convert to text first.
+            print("Converting DOCX files to text...")
+            input_data = _convert_docx_to_text(input_data)
+            if isinstance(input_data, str):
+                input_data = [input_data]
 
         # Warn if embedding_tiebreaker was provided (not supported in batch mode yet)
         if _embedding_tiebreaker_state is not None:
@@ -974,7 +1000,7 @@ def classify(
                 "stepback_insights": {},
                 "system_prompt": system_prompt,
                 "json_schema": json_schemas[cfg["model"]],
-                "creativity": creativity,
+                "creativity": cfg["creativity"] if cfg["creativity"] is not None else creativity,
                 "thinking_budget": thinking_budget,
                 "multi_label": multi_label,
             }