cat-stack 1.3.0__tar.gz → 1.4.1__tar.gz

{cat_stack-1.3.0 → cat_stack-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-stack
-Version: 1.3.0
+Version: 1.4.1
 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.3.0 → cat_stack-1.4.1}/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.3.0"
+__version__ = "1.4.1"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-stack"

{cat_stack-1.3.0 → cat_stack-1.4.1}/src/catstack/__init__.py

@@ -92,6 +92,7 @@ from ._wrapper_helpers import (
     parse_models_string,
     short_label,
     classify_labels,
+    classify_indicators,
 )
 
 # Define public API
@@ -144,4 +145,5 @@ __all__ = [
     "parse_models_string",
     "short_label",
     "classify_labels",
+    "classify_indicators",
 ]

{cat_stack-1.3.0 → cat_stack-1.4.1}/src/catstack/_wrapper_helpers.py

@@ -328,3 +328,101 @@ def classify_labels(
     if return_full:
         return labels_per_row, df
     return labels_per_row
+
+
+def classify_indicators(
+    input_data,
+    categories,
+    *,
+    short_labels: bool = True,
+    return_full: bool = False,
+    **kwargs,
+):
+    """Convenience wrapper around `classify()` returning per-category indicators.
+
+    Like `classify_labels`, but instead of collapsing the wide DataFrame to
+    one assigned label per row, it returns a dict mapping each category to
+    a list of 0/1 indicators of length `len(input_data)`.
+
+    This is the right shape for language wrappers that want one indicator
+    variable per category (Stata's wide mode, future R `as_indicators=TRUE`
+    mode) instead of a single label per row.
+
+    Args:
+        input_data: Same as `classify()`.
+        categories: Same as `classify()` — list of category strings.
+        short_labels: If True (default), use `short_label()` on each
+            category to produce dict keys (`"Positive: defn"` → `"Positive"`).
+            If False, the dict keys are the full category strings.
+        return_full: If True, return `(indicators_dict, df)` so callers also
+            have access to the underlying DataFrame.  Default False.
+        **kwargs: All other kwargs are forwarded to `classify()`.
+
+    Returns:
+        dict[str, list[int]]: keys are category labels (short or full),
+        values are 0/1 lists of length `len(input_data)`.  In ensemble mode
+        the indicators come from the `category_N_consensus` columns; in
+        single-model mode from `category_N`.
+        Or `(dict, df)` tuple if `return_full=True`.
+
+    Raises:
+        RuntimeError: if `classify()` returns a DataFrame that contains
+            neither `category_N` nor `category_N_consensus` columns
+            (centralized schema canary, same trigger as `classify_labels`).
+
+    Example:
+        >>> indicators = classify_indicators(
+        ...     ["I moved for the job and to be near family.",
+        ...      "Lower cost of living was the only reason."],
+        ...     ["Job: career", "Family: relationships", "Cost: affordability"],
+        ...     api_key="...", user_model="gpt-4o-mini",
+        ... )
+        >>> indicators
+        {'Job': [1, 0], 'Family': [1, 0], 'Cost': [0, 1]}
+    """
+    # Reuse classify_labels for the df + centralized schema canary.  We
+    # pass short_labels=False because we want the raw df; we apply our own
+    # short_label() to the dict keys below.
+    _labels, df = classify_labels(
+        input_data,
+        categories,
+        short_labels=False,
+        return_full=True,
+        **kwargs,
+    )
+
+    cols = list(df.columns)
+    indexed: List[Tuple[int, str]] = []
+    for c in cols:
+        m = _CONSENSUS_COL_PAT.match(c)
+        if m:
+            indexed.append((int(m.group(1)), c))
+    if not indexed:
+        for c in cols:
+            m = _SINGLE_COL_PAT.match(c)
+            if m:
+                indexed.append((int(m.group(1)), c))
+    # classify_labels already raised RuntimeError if neither family is
+    # present, so we know `indexed` is non-empty here.
+    indexed.sort(key=lambda t: t[0])
+
+    keys = [short_label(c) if short_labels else c for c in categories]
+
+    out: Dict[str, List[int]] = {}
+    for n, col in indexed:
+        cat_idx = n - 1
+        if not (0 <= cat_idx < len(keys)):
+            continue
+        key = str(keys[cat_idx])
+        series = df[col]
+        values: List[int] = []
+        for v in series:
+            try:
+                values.append(1 if int(v) == 1 else 0)
+            except (ValueError, TypeError):
+                values.append(0)
+        out[key] = values
+
+    if return_full:
+        return out, df
+    return out

{cat_stack-1.3.0 → cat_stack-1.4.1}/src/catstack/classify.py

@@ -84,7 +84,8 @@ def classify(
     parallel: bool = None,
     fail_strategy: str = "partial",
     max_retries: int = 5,
-    batch_retries: int = 2,
+    batch_retries: int = 1,
+    json_retries: int = 2,
     retry_delay: float = 1.0,
     row_delay: float = 0.0,
     pdf_dpi: int = 150,
@@ -183,7 +184,9 @@ def classify(
             (e.g., Ollama on limited hardware) or debugging.
         fail_strategy (str): How to handle failures - "partial" (default) or "strict".
         max_retries (int): Max retries per API call. Default 5.
-        batch_retries (int): Max retries for batch-level failures. Default 2.
+        batch_retries (int): Max retries for batch-level failures. Default 1.
+            Note: composes multiplicatively with json_retries — a row can hit
+            the LLM up to (1 + json_retries) * (1 + batch_retries) times.
         retry_delay (float): Delay between retries in seconds. Default 1.0.
         row_delay (float): Delay in seconds between processing each row. Useful
             when multiple models share the same API provider/key to avoid rate
@@ -407,6 +410,7 @@ def classify(
             fail_strategy=fail_strategy,
             max_retries=max_retries,
             batch_retries=batch_retries,
+            json_retries=json_retries,
             retry_delay=retry_delay,
             row_delay=row_delay,
             auto_download=auto_download,
@@ -849,6 +853,7 @@ def classify(
         fail_strategy=fail_strategy,
         max_retries=max_retries,
         batch_retries=batch_retries,
+        json_retries=json_retries,
         retry_delay=retry_delay,
         row_delay=row_delay,
         auto_download=auto_download,

{cat_stack-1.3.0 → cat_stack-1.4.1}/src/catstack/summarize.py

@@ -55,7 +55,7 @@ def summarize(
     # Robustness parameters
     safety: bool = False,
     max_retries: int = 5,
-    batch_retries: int = 2,
+    batch_retries: int = 1,
     retry_delay: float = 1.0,
     row_delay: float = 0.0,
     fail_strategy: str = "partial",
@@ -131,7 +131,7 @@ def summarize(
         auto_download (bool): Auto-download missing Ollama models. Default False.
         safety (bool): If True, saves progress after each item. Requires filename.
         max_retries (int): Max retries per API call. Default 5.
-        batch_retries (int): Max retries for batch-level failures. Default 2.
+        batch_retries (int): Max retries for batch-level failures. Default 1.
         retry_delay (float): Delay between retries in seconds. Default 1.0.
         row_delay (float): Delay in seconds between processing each row. Default 0.0.
         fail_strategy (str): How to handle failures - "partial" (default) or "strict".

{cat_stack-1.3.0 → cat_stack-1.4.1}/src/catstack/text_functions_ensemble.py

@@ -2277,7 +2277,8 @@ def classify_ensemble(
     fail_strategy: str = "partial",
     safety: bool = False,
     max_retries: int = 5,
-    batch_retries: int = 2,
+    batch_retries: int = 1,
+    json_retries: int = 2,
     retry_delay: float = 1.0,
     row_delay: float = 0.0,
     filename: str = None,
@@ -2368,8 +2369,10 @@ def classify_ensemble(
         max_retries: Maximum retry attempts for each API call (handles rate limits,
             server errors, timeouts). Default 5.
         batch_retries: Maximum retry passes for failed (row, model) pairs after
-            the batch completes. Default 2 means up to 3 total attempts. Set to 0
-            to disable batch-level retries.
+            the batch completes. Default 1 means up to 2 total attempts. Set to 0
+            to disable batch-level retries. Note: composes multiplicatively with
+            json_retries — a row can hit the LLM up to
+            (1 + json_retries) * (1 + batch_retries) times.
         retry_delay: Seconds to wait between batch retry passes.
 
         # Output parameters:
@@ -3009,35 +3012,59 @@ Categorize text responses {cove_categorize}:
                         multi_label=multi_label,
                         system_prompt=system_prompt,
                     )
-                    reply, error = client.complete(
-                        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,
-                        max_retries=max_retries,
-                    )
-                    if error:
-                        json_result = '{"1":"e"}'
-                    else:
+
+                    json_result = '{"1":"e"}'
+                    error = None
+                    _n_cats = len(categories)
+
+                    for _json_attempt in range(json_retries + 1):
+                        # On retries, nudge the model toward plain JSON output
+                        if _json_attempt > 0:
+                            _nudge = "\n\nRespond with ONLY valid JSON, no explanation or additional text."
+                            _last = messages[-1]
+                            _content = _last.get("content", "")
+                            _retry_messages = messages[:-1] + [{**_last, "content": _content + _nudge}]
+                        else:
+                            _retry_messages = messages
+
+                        reply, error = client.complete(
+                            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,
+                            max_retries=max_retries,
+                        )
+
+                        if error:
+                            json_result = '{"1":"e"}'
+                            break  # API-level failure already retried by max_retries
+
                         json_result = extract_json(reply)
-                        json_result = _try_formatter_fallback(json_result, reply)
+                        _json_valid, _ = validate_classification_json(json_result, _n_cats)
 
-                        # Run Chain of Verification if enabled
-                        if chain_of_verification and not error:
-                            step2, step3, step4 = build_cove_prompts(
-                                cove_original_task, response_text
-                            )
-                            json_result = run_chain_of_verification(
-                                client=client,
-                                initial_reply=json_result,
-                                step2_prompt=step2,
-                                step3_prompt=step3,
-                                step4_prompt=step4,
-                                json_schema=json_schemas[cfg["model"]],
-                                creativity=effective_creativity,
-                                max_retries=max_retries,
-                            )
-                            json_result = _try_formatter_fallback(json_result, json_result)
+                        if _json_valid:
+                            break
+
+                        # Final attempt: invoke formatter before giving up
+                        if _json_attempt == json_retries:
+                            json_result = _try_formatter_fallback(json_result, reply)
+
+                    # Run Chain of Verification if enabled
+                    if chain_of_verification and not error:
+                        step2, step3, step4 = build_cove_prompts(
+                            cove_original_task, response_text
+                        )
+                        json_result = run_chain_of_verification(
+                            client=client,
+                            initial_reply=json_result,
+                            step2_prompt=step2,
+                            step3_prompt=step3,
+                            step4_prompt=step4,
+                            json_schema=json_schemas[cfg["model"]],
+                            creativity=effective_creativity,
+                            max_retries=max_retries,
+                        )
+                        json_result = _try_formatter_fallback(json_result, json_result)
 
             return (cfg["sanitized_name"], json_result, error)
 
@@ -3760,7 +3787,7 @@ def summarize_ensemble(
     context_prompt: bool = False,
     step_back_prompt: bool = False,
     max_retries: int = 5,
-    batch_retries: int = 2,
+    batch_retries: int = 1,
     retry_delay: float = 1.0,
     row_delay: float = 0.0,
     fail_strategy: str = "partial",
@@ -3806,7 +3833,7 @@ def summarize_ensemble(
         context_prompt: Add expert context prefix
         step_back_prompt: Enable step-back prompting
         max_retries: Max retries per API call
-        batch_retries: Number of batch retry passes for failed items
+        batch_retries: Number of batch retry passes for failed items (default 1)
         retry_delay: Delay between retries in seconds
         row_delay: Delay in seconds between processing each row (default 0.0)
         fail_strategy: How to handle failures - "partial" (default) or "strict"