cat-stack 0.3.0__tar.gz → 1.0.0__tar.gz

{cat_stack-0.3.0 → cat_stack-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-stack
-Version: 0.3.0
+Version: 1.0.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
@@ -100,6 +100,41 @@ cat.classify(
 )
 ```
 
+#### Inline prompt tuning
+
+Add `prompt_tune=True` to automatically optimize the classification prompt before the full run. A browser UI opens for you to correct a small sample, then the optimized prompt is used for all remaining items.
+
+```python
+cat.classify(
+    input_data=df["text"],
+    categories=["Cat A", "Cat B", "Cat C"],
+    models=[("gpt-4o", "openai", key)],
+    prompt_tune=15,       # tune on 15 random items, then classify all
+    tune_iterations=3,    # max attempts per category (default 3)
+)
+```
+
+### `prompt_tune()`
+Standalone automatic prompt optimization. Iteratively refines classification prompts using user feedback — classify a sample, correct mistakes in the browser, and let the LLM generate targeted per-category instructions.
+
+```python
+result = cat.prompt_tune(
+    input_data=df["text"],
+    categories=["Cat A", "Cat B", "Cat C"],
+    api_key="your-key",
+    sample_size=15,
+    max_iterations=3,
+)
+
+# Use the optimized prompt for classification
+cat.classify(
+    input_data=df["text"],
+    categories=["Cat A", "Cat B", "Cat C"],
+    api_key="your-key",
+    system_prompt=result["system_prompt"],
+)
+```
+
 ### `extract()`
 Discover categories from a corpus using LLM-driven exploration.
 
@@ -141,11 +176,13 @@ All providers use the same `(model_name, provider, api_key)` tuple format. Provi
 
 ## Features
 
+- **Automatic prompt optimization** (`prompt_tune`) — correct a small sample in a browser UI, and the system generates per-category instructions that improve accuracy
 - **Multi-model ensemble** with consensus voting and agreement scores
 - **Batch API support** for OpenAI, Anthropic, Google, Mistral, and xAI
 - **Prompt strategies**: Chain-of-Thought, Chain-of-Verification, step-back prompting, few-shot examples
 - **Text, image, and PDF** input auto-detection
 - **Embedding similarity** tiebreaker for ensemble consensus ties
+- **Pilot test** — validate classifications on a small sample before committing to the full run
 
 ## License
 

{cat_stack-0.3.0 → cat_stack-1.0.0}/README.md

@@ -61,6 +61,41 @@ cat.classify(
 )
 ```
 
+#### Inline prompt tuning
+
+Add `prompt_tune=True` to automatically optimize the classification prompt before the full run. A browser UI opens for you to correct a small sample, then the optimized prompt is used for all remaining items.
+
+```python
+cat.classify(
+    input_data=df["text"],
+    categories=["Cat A", "Cat B", "Cat C"],
+    models=[("gpt-4o", "openai", key)],
+    prompt_tune=15,       # tune on 15 random items, then classify all
+    tune_iterations=3,    # max attempts per category (default 3)
+)
+```
+
+### `prompt_tune()`
+Standalone automatic prompt optimization. Iteratively refines classification prompts using user feedback — classify a sample, correct mistakes in the browser, and let the LLM generate targeted per-category instructions.
+
+```python
+result = cat.prompt_tune(
+    input_data=df["text"],
+    categories=["Cat A", "Cat B", "Cat C"],
+    api_key="your-key",
+    sample_size=15,
+    max_iterations=3,
+)
+
+# Use the optimized prompt for classification
+cat.classify(
+    input_data=df["text"],
+    categories=["Cat A", "Cat B", "Cat C"],
+    api_key="your-key",
+    system_prompt=result["system_prompt"],
+)
+```
+
 ### `extract()`
 Discover categories from a corpus using LLM-driven exploration.
 
@@ -102,11 +137,13 @@ All providers use the same `(model_name, provider, api_key)` tuple format. Provi
 
 ## Features
 
+- **Automatic prompt optimization** (`prompt_tune`) — correct a small sample in a browser UI, and the system generates per-category instructions that improve accuracy
 - **Multi-model ensemble** with consensus voting and agreement scores
 - **Batch API support** for OpenAI, Anthropic, Google, Mistral, and xAI
 - **Prompt strategies**: Chain-of-Thought, Chain-of-Verification, step-back prompting, few-shot examples
 - **Text, image, and PDF** input auto-detection
 - **Embedding similarity** tiebreaker for ensemble consensus ties
+- **Pilot test** — validate classifications on a small sample before committing to the full run
 
 ## License
 

{cat_stack-0.3.0 → cat_stack-1.0.0}/src/cat_stack/__about__.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: 2025-present Christopher Soria <chrissoria@berkeley.edu>
 #
 # SPDX-License-Identifier: GPL-3.0-or-later
-__version__ = "0.3.0"
+__version__ = "1.0.0"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-stack"

{cat_stack-0.3.0 → cat_stack-1.0.0}/src/cat_stack/classify.py

@@ -100,6 +100,10 @@ def classify(
     categories_per_call: int = None,
     pilot_test: Union[bool, int] = False,
     system_prompt: str = "",
+    prompt_tune: Union[bool, int] = False,
+    tune_iterations: int = 3,
+    tune_ui: str = "browser",
+    tune_optimize: str = "balanced",
 ):
     """
     Unified classification function for text, image, and PDF inputs.
@@ -242,6 +246,17 @@ def classify(
             classification prompt. Use prompt_tune() to generate an optimized
             instruction from labeled examples. Takes precedence over
             context_prompt when provided. Default "".
+        prompt_tune (bool or int): Run automatic prompt optimization before the
+            full classification. Classifies a small sample, opens a browser UI
+            for corrections, then generates an optimized system_prompt.
+            - False (default): Skip prompt tuning.
+            - True: Tune on 10 random items.
+            - int: Tune on that many random items.
+            Overrides system_prompt if provided.
+        tune_iterations (int): Max optimization attempts per category. Default 3.
+        tune_ui (str): Review UI for prompt tuning — "browser" or "terminal".
+        tune_optimize (str): Metric to optimize — "balanced", "precision",
+            or "sensitivity". Default "balanced".
 
     Returns:
         pd.DataFrame: Results with classification columns.
@@ -400,6 +415,37 @@ def classify(
         if pilot_result is None or not pilot_result["proceed"]:
             return None
 
+    # =========================================================================
+    # Prompt tuning — optimize system_prompt before full classification
+    # =========================================================================
+    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
+
+        tune_result = _prompt_tune(
+            input_data=input_data,
+            categories=categories,
+            models=models,
+            description=description,
+            survey_question=survey_question,
+            sample_size=tune_sample_size,
+            max_iterations=tune_iterations,
+            multi_label=multi_label,
+            creativity=creativity,
+            use_json_schema=use_json_schema,
+            consensus_threshold=consensus_threshold,
+            max_retries=max_retries,
+            input_mode=input_mode,
+            ui=tune_ui,
+            optimize=tune_optimize,
+            add_other=False,  # already handled above
+        )
+
+        if tune_result["system_prompt"]:
+            system_prompt = tune_result["system_prompt"]
+            print(f"\n[CatLLM] Using optimized prompt from prompt_tune.\n")
+
     # =========================================================================
     # Validate categories_per_call
     # =========================================================================

{cat_stack-0.3.0 → cat_stack-1.0.0}/src/cat_stack/summarize.py

@@ -31,6 +31,7 @@ def summarize(
     api_key: str = None,
     description: str = "",
     instructions: str = "",
+    format: str = "paragraph",
     max_length: int = None,
     focus: str = None,
     user_model: str = "gpt-4o",
@@ -76,7 +77,15 @@ def summarize(
             - PDF: directory path, single PDF path, or list of PDF paths
         api_key (str): API key for the model provider (single-model mode)
         description (str): Description of what the content contains (provides context)
-        instructions (str): Specific summarization instructions (e.g., "bullet points")
+        instructions (str): Specific summarization instructions. When used with
+            format, these are appended as additional instructions. Default "".
+        format (str): Output format for the summary. Default "paragraph".
+            - "paragraph": Flowing prose summary (default)
+            - "bullets": Bullet-point list of key points
+            - "one-liner": Single-sentence summary
+            - "structured": Labeled sections (What, Who, Why, Impact)
+            - "report": Comprehensive full-page report with Overview, Background,
+              Key Provisions, Stakeholders/Impact, and Implementation sections
         max_length (int): Maximum summary length in words
         focus (str): What to focus on (e.g., "main arguments", "emotional content")
         user_model (str): Model to use (default "gpt-4o")
@@ -179,6 +188,75 @@ def summarize(
         ...     ],
         ... )
     """
+    # =========================================================================
+    # Resolve format → instructions + max_length defaults
+    # =========================================================================
+    _FORMAT_PRESETS = {
+        "paragraph": {
+            "instructions": "Write a concise summary in paragraph form.",
+            "max_length": None,
+        },
+        "bullets": {
+            "instructions": (
+                "Summarize as a bullet-point list. Each bullet should capture "
+                "one key point. Use '- ' prefix for each bullet."
+            ),
+            "max_length": None,
+        },
+        "one-liner": {
+            "instructions": "Summarize in a single sentence.",
+            "max_length": 40,
+        },
+        "structured": {
+            "instructions": (
+                "Summarize using these labeled sections:\n"
+                "- What: What does this do or say?\n"
+                "- Who: Who is affected or involved?\n"
+                "- Why: What is the motivation or purpose?\n"
+                "- Impact: What are the key consequences or effects?"
+            ),
+            "max_length": None,
+        },
+        "report": {
+            "instructions": (
+                "Write a comprehensive full-page report covering the following sections. "
+                "Use clear headings and be thorough.\n\n"
+                "## Overview\n"
+                "A brief executive summary (2-3 sentences).\n\n"
+                "## Background and Context\n"
+                "What is the background? What problem or situation prompted this? "
+                "Include relevant history and prior actions.\n\n"
+                "## Key Provisions\n"
+                "Detail the main provisions, requirements, or arguments. "
+                "Be specific about numbers, dates, names, and conditions.\n\n"
+                "## Stakeholders and Impact\n"
+                "Who is affected? What are the expected consequences? "
+                "Include both intended effects and potential concerns.\n\n"
+                "## Implementation\n"
+                "How will this be implemented? What is the timeline? "
+                "Are there enforcement mechanisms or milestones?"
+            ),
+            "max_length": 800,
+        },
+    }
+
+    format_lower = format.lower() if format else "paragraph"
+    if format_lower not in _FORMAT_PRESETS:
+        valid = ", ".join(f'"{k}"' for k in _FORMAT_PRESETS)
+        raise ValueError(f"format must be one of {valid}, got '{format}'")
+
+    preset = _FORMAT_PRESETS[format_lower]
+
+    # Format instructions are prepended to any user-provided instructions
+    if not instructions:
+        instructions = preset["instructions"]
+    else:
+        instructions = f"{preset['instructions']}\n\nAdditional instructions: {instructions}"
+
+    # Use format's max_length as default only if user didn't specify one
+    if max_length is None and preset["max_length"] is not None:
+        max_length = preset["max_length"]
+
     # Map mode to pdf_mode
     pdf_mode = mode if mode in ("image", "text", "both") else "image"
 

{cat_stack-0.3.0 → cat_stack-1.0.0}/src/cat_stack/text_functions_ensemble.py

@@ -3756,7 +3756,7 @@ def summarize_ensemble(
                         max_retries=max_retries,
                     )
                 else:
-                    response, _err = client.complete(
+                    response, error = client.complete(
                         messages=messages,
                         json_schema=json_schema,
                         creativity=creativity,
@@ -3764,6 +3764,9 @@ def summarize_ensemble(
                         max_retries=max_retries,
                     )
 
+                if error:
+                    return (model_name, '{"summary": ""}', error)
+
                 # Extract JSON from response
                 json_str = extract_json(response)
 
@@ -3806,7 +3809,7 @@ def summarize_ensemble(
                 # Resolve thinking_budget for this provider
                 effective_thinking = thinking_budget if cfg["provider"] in ("google", "openai", "anthropic", "huggingface", "huggingface-together") else None
 
-                response, _err = client.complete(
+                response, error = client.complete(
                     messages=messages,
                     json_schema=json_schema,
                     creativity=creativity,
@@ -3814,6 +3817,9 @@ def summarize_ensemble(
                     max_retries=max_retries,
                 )
 
+                if error:
+                    return (model_name, '{"summary": ""}', error)
+
                 # Extract JSON from response
                 json_str = extract_json(response)