cat-stack 1.0.18__tar.gz → 1.0.22__tar.gz

{cat_stack-1.0.18 → cat_stack-1.0.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cat-stack
-Version: 1.0.18
+Version: 1.0.22
 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
@@ -73,7 +73,7 @@ Installing `cat-llm` pulls in all of the above.
 ## Quick Start
 
 ```python
-import cat_stack as cat
+import catstack as cat
 
 # Classify text into predefined categories
 result = cat.classify(

{cat_stack-1.0.18 → cat_stack-1.0.22}/README.md

@@ -36,7 +36,7 @@ Installing `cat-llm` pulls in all of the above.
 ## Quick Start
 
 ```python
-import cat_stack as cat
+import catstack as cat
 
 # Classify text into predefined categories
 result = cat.classify(

{cat_stack-1.0.18 → cat_stack-1.0.22}/pyproject.toml

@@ -43,38 +43,40 @@ Issues = "https://github.com/chrissoria/cat-stack/issues"
 Source = "https://github.com/chrissoria/cat-stack"
 
 [tool.hatch.version]
-path = "src/cat_stack/__about__.py"
+path = "src/catstack/__about__.py"
 
 [tool.hatch.envs.types]
 extra-dependencies = [
   "mypy>=1.0.0",
 ]
 [tool.hatch.envs.types.scripts]
-check = "mypy --install-types --non-interactive {args:src/cat_stack tests}"
+check = "mypy --install-types --non-interactive {args:src/catstack tests}"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/cat_stack"]
+packages = ["src/catstack", "src/cat_stack"]
 include = [
-    "src/cat_stack/**/*.py",
-    "src/cat_stack/images/*",
+    "src/catstack/**/*.py",
+    "src/catstack/images/*",
+    "src/cat_stack/__init__.py",
 ]
 
 [tool.hatch.build.targets.sdist]
 include = [
-    "src/cat_stack/**/*.py",
-    "src/cat_stack/images/*",
+    "src/catstack/**/*.py",
+    "src/catstack/images/*",
+    "src/cat_stack/__init__.py",
 ]
 
 [tool.coverage.run]
-source_pkgs = ["cat_stack", "tests"]
+source_pkgs = ["catstack", "tests"]
 branch = true
 parallel = true
 omit = [
-  "src/cat_stack/__about__.py",
+  "src/catstack/__about__.py",
 ]
 
 [tool.coverage.paths]
-cat_stack = ["src/cat_stack", "*/cat-stack/src/cat_stack"]
+catstack = ["src/catstack", "*/cat-stack/src/catstack"]
 tests = ["tests", "*/cat-stack/tests"]
 
 [tool.coverage.report]

cat_stack-1.0.22/src/cat_stack/__init__.py

@@ -0,0 +1,18 @@
+"""Back-compat alias for `catstack`.
+
+The canonical import name is `catstack`. `cat_stack` is retained so existing
+code continues to work; prefer `catstack` in new code.
+"""
+import importlib
+import sys
+
+_canonical = "catstack"
+_real = importlib.import_module(_canonical)
+
+sys.modules[__name__] = _real
+
+_src_prefix = _canonical + "."
+_dst_prefix = __name__ + "."
+for _name in list(sys.modules):
+    if _name.startswith(_src_prefix):
+        sys.modules[_dst_prefix + _name[len(_src_prefix):]] = sys.modules[_name]

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/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.0.18"
+__version__ = "1.0.22"
 __author__ = "Chris Soria"
 __email__ = "chrissoria@berkeley.edu"
 __title__ = "cat-stack"

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/_formatter.py

@@ -42,6 +42,56 @@ def _check_dependencies():
         )
 
 
+def _ensure_dependencies(verbose: bool = True) -> bool:
+    """Ensure formatter Python dependencies are installed.
+
+    Tries to import torch/transformers/accelerate. If any are missing,
+    auto-installs them via pip after printing a clear warning about the
+    download size (~1.5 GB total). Returns True on success, False on
+    install failure.
+    """
+    try:
+        import torch  # noqa: F401
+        import transformers  # noqa: F401
+        import accelerate  # noqa: F401
+        return True
+    except ImportError:
+        pass
+
+    if verbose:
+        print(
+            "\n[CatLLM] JSON formatter dependencies (transformers, torch, "
+            "accelerate)\n"
+            "  are not installed in this Python environment. Installing now\n"
+            "  (~1.5 GB download; one-time). To skip this and disable the\n"
+            "  formatter, pass json_formatter=False."
+        )
+
+    import subprocess
+    try:
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--quiet",
+             "transformers", "torch", "accelerate", "sentencepiece"]
+        )
+    except subprocess.CalledProcessError as e:
+        if verbose:
+            print(
+                f"[CatLLM] Failed to install formatter dependencies ({e}).\n"
+                "  Install manually: pip install 'cat-llm[formatter]'"
+            )
+        return False
+
+    # Verify import works now
+    try:
+        import torch  # noqa: F401
+        import transformers  # noqa: F401
+        return True
+    except ImportError as e:
+        if verbose:
+            print(f"[CatLLM] Formatter deps installed but import failed: {e}")
+        return False
+
+
 def _is_model_cached() -> bool:
     """Check if the merged model is already in the HuggingFace cache."""
     try:
@@ -54,31 +104,29 @@ def _is_model_cached() -> bool:
 
 def ensure_formatter_available() -> bool:
     """
-    Ensure the formatter model is available, prompting to download if needed.
+    Ensure the formatter model and its Python dependencies are available.
+
+    Auto-installs deps (transformers/torch/accelerate, ~1.5 GB) on first use
+    and auto-downloads the formatter model (~1 GB) from HuggingFace on first
+    use. Both events print a clear warning to the console; neither prompts
+    interactively, so this function is safe to call from Rscript / non-TTY
+    sessions.
 
     Returns:
-        True if the formatter is ready to use, False if user declined download.
+        True if the formatter is ready to use, False on install failure.
     """
-    _check_dependencies()
+    if not _ensure_dependencies():
+        return False
 
     if _is_model_cached():
         return True
 
     print(
-        "\n[CatLLM] The JSON formatter model (~1GB) will be downloaded from\n"
+        "\n[CatLLM] Downloading JSON formatter model (~1 GB) from\n"
         f"  HuggingFace Hub ({_MERGED_MODEL_REPO}).\n"
         "  This is a one-time download — the model is cached locally after."
     )
-    try:
-        answer = input("  Continue? (Y/n): ").strip().lower()
-    except (EOFError, KeyboardInterrupt):
-        answer = "n"
-
-    if answer in ("", "y", "yes"):
-        return True
-    else:
-        print("  -> JSON formatter disabled for this run.\n")
-        return False
+    return True  # actual download happens in load_formatter()
 
 
 def load_formatter(device=None):

cat_stack-1.0.22/src/catstack/_prompts.py

@@ -0,0 +1,205 @@
+"""
+Domain-keyed prompt registry.
+
+cat-stack's extract() and explore() pipelines use two LLM prompts: a
+*first-pass* per-chunk extraction prompt and a *second-pass* semantic
+*merge* prompt. The wording of each is domain-shaped — survey responses
+read differently than social-media posts or academic papers.
+
+This module centralises every variant in one place. Domain-specific
+sub-packages (cat-survey, cat-vader, cat-ademic, cat-pol, cat-web) call
+catstack.extract/explore with `domain="<key>"` to select the appropriate
+variant. The default is `"neutral"`, which contains no domain-shaped
+language so direct catstack callers get generic prompts.
+
+A domain only needs to override the slots that genuinely differ from
+neutral; unspecified slots fall back to neutral via `get_prompt`.
+
+Template placeholders:
+
+  first_pass — {categories_per_chunk} {specificity} {context}
+               {focus_text} {items_blob}
+  merge      — {context} {max_categories} {name_instruction}
+               {seed_with_counts}
+"""
+
+# Generic, domain-neutral templates. Used directly when the caller does
+# not pass a domain, and used as the fallback for any slot a domain does
+# not override.
+_NEUTRAL_FIRST_PASS = (
+    'Identify {categories_per_chunk} {specificity} categories present in '
+    'the following texts about: "{context}".{focus_text} '
+    "Items are separated by semicolons. "
+    "Items are within triple backticks: ```{items_blob}``` "
+    "Number your categories from 1 through {categories_per_chunk} and "
+    "provide concise labels only (no descriptions)."
+)
+
+_NEUTRAL_MERGE = """
+You are consolidating categories extracted from a collection of texts about: "{context}"
+
+Task: Reduce to {max_categories} categories.
+
+Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct concept or theme. Categories that describe the same concept using different words or from different angles belong in the same cluster. For example, a category about "battery life" and a category about "charge duration" likely belong together if they reflect the same underlying concept.
+
+Step 2 — Label: For each cluster, choose the single label that best captures the shared meaning. {name_instruction}
+
+Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
+
+Categories (sorted by extraction frequency):
+{seed_with_counts}
+
+Return ONLY a numbered list of {max_categories} categories. Each line must follow this exact format:
+N. Category Label (such as example 1, example 2, example 3)
+
+Example:
+1. Financial Pressures (such as rising costs, budget constraints, or loss of income)
+2. Location or Environment (such as moving to a new city, neighborhood quality, or proximity to amenities)
+""".strip()
+
+
+# Survey: the historical cat-stack prompt, verbatim. "respondent" /
+# "reason" language preserved.
+_SURVEY_FIRST_PASS = (
+    'Identify {categories_per_chunk} {specificity} categories of responses '
+    'to the question "{context}" in the following list of responses.{focus_text} '
+    "Responses are separated by semicolons. "
+    "Responses are within triple backticks: ```{items_blob}``` "
+    "Number your categories from 1 through {categories_per_chunk} and "
+    "provide concise labels only (no descriptions)."
+)
+
+_SURVEY_MERGE = """
+You are consolidating categories extracted from survey responses to: "{context}"
+
+Task: Reduce to {max_categories} categories.
+
+Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct reason a respondent might give. Categories that describe the same reason using different words or from different angles belong in the same cluster. For example, a category about relationship quality and a category about emotional closeness likely belong together if they reflect the same underlying reason.
+
+Step 2 — Label: For each cluster, choose the single label that best captures the shared meaning. {name_instruction}
+
+Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
+
+Categories (sorted by extraction frequency):
+{seed_with_counts}
+
+Return ONLY a numbered list of {max_categories} categories. Each line must follow this exact format:
+N. Category Label (such as example 1, example 2, example 3)
+
+Example:
+1. Financial Pressures (such as rising rent, job loss, or inability to afford housing)
+2. Proximity to Family (such as moving closer to parents, children, or extended relatives)
+""".strip()
+
+
+_SOCIAL_MERGE = """
+You are consolidating categories extracted from social-media posts about: "{context}"
+
+Task: Reduce to {max_categories} categories.
+
+Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct topic, sentiment, or behaviour expressed in the posts. Categories that describe the same underlying message using different wording, slang, or hashtags belong in the same cluster. For example, a category about "product praise" and a category about "positive recommendation" likely belong together if they reflect the same underlying sentiment.
+
+Step 2 — Label: For each cluster, choose the single label that best captures the shared meaning. {name_instruction}
+
+Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
+
+Categories (sorted by extraction frequency):
+{seed_with_counts}
+
+Return ONLY a numbered list of {max_categories} categories.
+""".strip()
+
+
+_ACADEMIC_MERGE = """
+You are consolidating categories extracted from academic texts about: "{context}"
+
+Task: Reduce to {max_categories} categories.
+
+Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct research theme, method, or finding. Categories that describe the same scholarly concept using different terminology or framings belong in the same cluster. For example, a category about "longitudinal cohort analysis" and a category about "panel data study design" likely belong together if they reflect the same underlying research approach.
+
+Step 2 — Label: For each cluster, choose the single label that best captures the shared meaning. {name_instruction}
+
+Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
+
+Categories (sorted by extraction frequency):
+{seed_with_counts}
+
+Return ONLY a numbered list of {max_categories} categories.
+""".strip()
+
+
+_POLICY_MERGE = """
+You are consolidating categories extracted from policy documents about: "{context}"
+
+Task: Reduce to {max_categories} categories.
+
+Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct policy area, provision, or government action. Categories that describe the same provision using different statutory language or framings belong in the same cluster. For example, a category about "Medicaid eligibility expansion" and a category about "low-income healthcare coverage extension" likely belong together if they reflect the same underlying policy mechanism.
+
+Step 2 — Label: For each cluster, choose the single label that best captures the policy area or provision. {name_instruction}
+
+Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
+
+Categories (sorted by extraction frequency):
+{seed_with_counts}
+
+Return ONLY a numbered list of {max_categories} categories.
+""".strip()
+
+
+_WEB_MERGE = """
+You are consolidating categories extracted from web content about: "{context}"
+
+Task: Reduce to {max_categories} categories.
+
+Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct topic, claim, or content type. Categories that describe the same web content using different headlines or framings belong in the same cluster. For example, a category about "product reviews" and a category about "consumer evaluations" likely belong together if they reflect the same underlying content type.
+
+Step 2 — Label: For each cluster, choose the single label that best captures the shared meaning. {name_instruction}
+
+Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
+
+Categories (sorted by extraction frequency):
+{seed_with_counts}
+
+Return ONLY a numbered list of {max_categories} categories.
+""".strip()
+
+
+PROMPTS = {
+    "neutral": {
+        "first_pass": _NEUTRAL_FIRST_PASS,
+        "merge":      _NEUTRAL_MERGE,
+    },
+    "survey": {
+        "first_pass": _SURVEY_FIRST_PASS,
+        "merge":      _SURVEY_MERGE,
+    },
+    "social": {
+        # first_pass inherits from neutral
+        "merge": _SOCIAL_MERGE,
+    },
+    "academic": {
+        "merge": _ACADEMIC_MERGE,
+    },
+    "policy": {
+        "merge": _POLICY_MERGE,
+    },
+    "web": {
+        "merge": _WEB_MERGE,
+    },
+}
+
+
+def get_prompt(domain: str, slot: str) -> str:
+    """Look up a prompt slot for a domain, falling back to 'neutral'.
+
+    Args:
+        domain: A key in PROMPTS (e.g. "neutral", "survey", "social",
+            "academic", "policy", "web"). Unknown domains fall through
+            to neutral.
+        slot:   "first_pass" or "merge".
+
+    Returns:
+        The template string, with f-string-style {placeholder} markers
+        that the caller fills via str.format(**kwargs).
+    """
+    return PROMPTS.get(domain, {}).get(slot) or PROMPTS["neutral"][slot]

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/_utils.py

@@ -50,9 +50,9 @@ def _clean_label(label: str) -> str:
         "Emotional Support: 3"                     -> "Emotional Support"
         "emotional support"                         -> "emotional support"
     """
-    label = label.replace("**", "")              # remove bold markers
-    label = re.sub(r"\s*\([^)]*\)", "", label)   # remove parenthetical notes
-    label = re.sub(r"\s*:\s*\d+\s*$", "", label) # remove trailing ": N" counts
+    label = label.replace("**", "")                        # remove bold markers
+    label = re.sub(r"\s*\(\s*\d+\s*\)", "", label)        # remove count-only parens like "(3)"
+    label = re.sub(r"\s*:\s*\d+\s*$", "", label)          # remove trailing ": N" counts
     return label.strip()
 
 

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/classify.py

@@ -7,7 +7,7 @@ supporting both single-model and multi-model (ensemble) classification.
 
 import math
 import warnings
-from typing import Union, Callable
+from typing import Union, Callable, Optional
 
 __all__ = [
     # Main entry point
@@ -91,7 +91,7 @@ def classify(
     auto_download: bool = False,
     add_other = "prompt",
     check_verbosity: bool = True,
-    json_formatter: bool = False,
+    json_formatter: Optional[bool] = None,
     embeddings: bool = False,
     category_descriptions: dict = None,
     embedding_tiebreaker: bool = False,
@@ -532,19 +532,51 @@ def classify(
         print()
 
     # =========================================================================
-    # JSON formatter fallback (opt-in)
+    # JSON formatter fallback
     # =========================================================================
+    # Auto-enable when Ollama (or any local model with colon-tag syntax) is in
+    # use, since small local models more often emit malformed classification
+    # JSON. Pass json_formatter=False explicitly to opt out.
+    def _uses_ollama_provider():
+        ms = (model_source or "").lower()
+        if ms == "ollama":
+            return True
+        if models:
+            for m in models:
+                provider = None
+                if isinstance(m, (list, tuple)) and len(m) >= 2:
+                    provider = m[1]
+                elif isinstance(m, dict):
+                    provider = m.get("provider")
+                if provider and str(provider).lower() == "ollama":
+                    return True
+        return False
+
+    if json_formatter is None:
+        json_formatter = _uses_ollama_provider()
+        if json_formatter:
+            print(
+                "\n[CatLLM] Ollama detected — auto-enabling JSON formatter fallback\n"
+                "  (small local models more often emit malformed JSON).\n"
+                "  Pass json_formatter=False to opt out."
+            )
+
+    # The formatter MODEL is loaded lazily on the first parse failure (saves
+    # ~1 GB RAM + load time when no rows actually need rescuing). The dep
+    # check + cache verification still run upfront -- that's the fast part
+    # and lets us cleanly disable the formatter if deps can't be installed.
     _formatter_state = None
     if json_formatter:
         try:
             from ._formatter import ensure_formatter_available, load_formatter
 
             if ensure_formatter_available():
-                fmt_model, fmt_tokenizer, fmt_device = load_formatter()
                 _formatter_state = {
-                    "model": fmt_model,
-                    "tokenizer": fmt_tokenizer,
-                    "device": fmt_device,
+                    "model": None,
+                    "tokenizer": None,
+                    "device": None,
+                    "_loaded": False,
+                    "_loader": load_formatter,
                 }
             else:
                 json_formatter = False

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/explore.py

@@ -34,6 +34,7 @@ def explore(
     chunk_delay: float = 0.0,
     auto_download: bool = False,
     max_workers: int = 1,
+    domain: str = "neutral",
 ):
     """
     Explore categories in text data, returning the raw extracted list.
@@ -107,6 +108,7 @@ def explore(
         chunk_delay=chunk_delay,
         auto_download=auto_download,
         max_workers=max_workers,
+        domain=domain,
     )
 
     if filename:

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/extract.py

@@ -60,6 +60,7 @@ def extract(
     chunk_delay: float = 0.0,
     auto_download: bool = False,
     input_mode=None,
+    domain: str = "neutral",
 ):
     """
     Unified category extraction function for text, image, and PDF inputs.
@@ -175,6 +176,7 @@ def extract(
             progress_callback=progress_callback,
             chunk_delay=chunk_delay,
             auto_download=auto_download,
+            domain=domain,
         )
 
     elif input_type == "image":

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/text_functions.py

@@ -73,6 +73,7 @@ from ._providers import (
     OLLAMA_MODEL_SIZES,
 )
 from ._utils import _clean_label
+from ._prompts import get_prompt
 
 
 # =============================================================================
@@ -525,6 +526,7 @@ def explore_common_categories(
     chunk_delay: float = 0.0,
     auto_download: bool = False,
     max_workers: int = 1,
+    domain: str = "neutral",
     # Legacy parameter names for backward compatibility
     user_model: str = None,
     model_source: str = None,
@@ -687,13 +689,16 @@ def explore_common_categories(
     else:
         system_content = "You are a helpful assistant that extracts categories from text responses."
 
+    first_pass_template = get_prompt(domain, "first_pass")
+
     def make_prompt(responses_blob: str) -> str:
         focus_text = f" Focus specifically on {focus}." if focus else ""
-        return (
-            f'Identify {categories_per_chunk} {specificity} categories of responses to the question "{survey_question}" '
-            f"in the following list of responses.{focus_text} Responses are separated by semicolons. "
-            f"Responses are within triple backticks: ```{responses_blob}``` "
-            f"Number your categories from 1 through {categories_per_chunk} and provide concise labels only (no descriptions)."
+        return first_pass_template.format(
+            categories_per_chunk=categories_per_chunk,
+            specificity=specificity,
+            context=survey_question,
+            focus_text=focus_text,
+            items_blob=responses_blob,
         )
 
     # Parse numbered list
@@ -849,31 +854,24 @@ def explore_common_categories(
 
     if specificity == "specific":
         name_instruction = (
-            "Prefer specific, descriptive labels over vague ones. "
-            "Each category name SHOULD include a brief clarifying phrase using "
-            "'such as' or parenthetical examples where helpful."
+            "Use specific, descriptive labels. "
+            "Each category name MUST include a clarifying phrase using "
+            "'such as' or parenthetical examples."
         )
     else:
         name_instruction = (
-            "Prefer specific, descriptive labels over vague ones."
+            "Prefer specific, descriptive labels over vague ones. "
+            "Each category name SHOULD include a brief clarifying phrase using "
+            "'such as' or parenthetical examples where helpful."
         )
 
-    second_prompt = f"""
-You are consolidating categories extracted from survey responses to: "{survey_context}"
-
-Task: Reduce to {max_categories} categories.
-
-Step 1 — Cluster: Group the categories below into clusters where each cluster represents ONE distinct reason a respondent might give. Categories that describe the same reason using different words or from different angles belong in the same cluster. For example, a category about relationship quality and a category about emotional closeness likely belong together if they reflect the same underlying reason.
-
-Step 2 — Label: For each cluster, choose the single label that best captures the shared meaning. {name_instruction}
-
-Step 3 — Rank: Sum the frequency counts within each cluster. Output the top {max_categories} clusters by total count.
-
-Categories (sorted by extraction frequency):
-{seed_with_counts}
-
-Return ONLY a numbered list of {max_categories} categories.
-""".strip()
+    merge_template = get_prompt(domain, "merge")
+    second_prompt = merge_template.format(
+        context=survey_context,
+        max_categories=max_categories,
+        name_instruction=name_instruction,
+        seed_with_counts=seed_with_counts,
+    )
 
     # Second pass call
     reply2, error2 = client.complete(

{cat_stack-1.0.18/src/cat_stack → cat_stack-1.0.22/src/catstack}/text_functions_ensemble.py

@@ -2657,6 +2657,10 @@ Categorize text responses {cove_categorize}:
     def _try_formatter_fallback(json_result, raw_reply, chunk_categories=None):
         """Try the JSON formatter if extract_json produced invalid output.
 
+        Lazily loads the formatter model into RAM the first time this helper
+        is invoked with a real failure -- saves ~1 GB RAM + load time when
+        every row parses cleanly on the first try.
+
         Args:
             chunk_categories: When called from chunked classification, the
                 actual chunk category list (not the full list). Needed so the
@@ -2669,6 +2673,19 @@ Categorize text responses {cove_categorize}:
         is_valid, _ = validate_classification_json(json_result, n)
         if is_valid:
             return json_result
+
+        # Lazy load on first need
+        if not formatter_state.get("_loaded"):
+            print(
+                "\n[CatLLM] First malformed-JSON row encountered -- loading\n"
+                "  JSON formatter model into RAM now (one-time per session)."
+            )
+            fmt_model, fmt_tokenizer, fmt_device = formatter_state["_loader"]()
+            formatter_state["model"] = fmt_model
+            formatter_state["tokenizer"] = fmt_tokenizer
+            formatter_state["device"] = fmt_device
+            formatter_state["_loaded"] = True
+
         from ._formatter import run_formatter
         fixed_output = run_formatter(
             raw_reply, cats,