cat-claws 0.1.0__py3-none-any.whl

cat_claws-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: cat-claws
+Version: 0.1.0
+Summary: Claude Agent SDK backend for the CatLLM ecosystem — classify text through a Claude subscription instead of per-token API billing.
+Project-URL: Source, https://github.com/chrissoria/cat-agent
+Author-email: Chris Soria <chrissoria@berkeley.edu>
+License-Expression: GPL-3.0-or-later
+Keywords: agent-sdk,classification,claude,llm,survey
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: cat-stack>=2.0.1
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: pandas
+Description-Content-Type: text/markdown
+
+# cat-claws
+
+Agent-CLI backend for the [CatLLM ecosystem](https://github.com/chrissoria/cat-llm):
+classify text through a **Claude subscription** (via the Claude Agent SDK)
+instead of per-token API billing. An OpenAI Codex adapter is planned.
+
+*(Distribution name `cat-claws`; imports as `catclaws`. Source repo:
+[cat-agent](https://github.com/chrissoria/cat-agent).)*
+
+**Status: alpha, under active development.** See `MASTERPLAN.md` for the
+design and step tracker.
+
+## Install
+
+```bash
+pip install cat-claws
+```
+
+## Design in one paragraph
+
+One row = one sealed, fresh-context agent call (no tools, single turn, no
+settings/CLAUDE.md loading), using cat-stack's validated classification
+prompt byte-for-byte. The model answers in JSON; parsing and the wide 0/1
+output matrix reuse cat-stack's existing machinery. Throughput comes from
+concurrent one-shot calls, never from shared conversations or
+corpus-in-one-prompt (which would contaminate rows and break research
+validity).
+
+## Quick start (Phase 1)
+
+```python
+import catclaws
+
+df = catclaws.classify(
+    input_data=["I moved for a new job", "Rent got too expensive"],
+    categories=["Employment", "Cost of living", "Other"],
+    user_model="claude-sonnet-5",   # any model your Claude login can use
+    description="Why did you move?",
+)
+```
+
+Requires [Claude Code](https://code.claude.com/docs) installed and logged in
+(`claude` on PATH). No API key needed.

cat_claws-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+catclaws/__about__.py,sha256=h8ok3JwGMDibSgYDrKRLB7yD8sS3B9k57p9aWIfdaFU,245
+catclaws/__init__.py,sha256=vQf1SLJGPQaMNylx-z7289bYAl3RLqoZ5w8Wf9-tQOI,440
+catclaws/_backend.py,sha256=M_xovqZqihUC0n7w3VwMNZwLcsYM_ZaH2ZS05aOiDkE,1019
+catclaws/classify.py,sha256=msWqW5tAi2WhAu20okAwyKJ1x2il-dqJDHTgKloQulE,7739
+catclaws/_adapters/__init__.py,sha256=6vsSnIcnPlkbJ9yBAXRE7biP_2bKo4RBwUtreROecow,391
+catclaws/_adapters/base.py,sha256=t8FUr1SmTPTYOelTDTunz3tdSMODA29Kl0Kf6MV9az8,2785
+catclaws/_adapters/claude.py,sha256=aOxz51cP7XDLVnEy3Bb7qbhZmGA4kaMNdJVfYxl2Hrw,7748
+cat_claws-0.1.0.dist-info/METADATA,sha256=zggHjN0phVEs-8-UXY2Pf4zg9xYVjJYk5TalLErL32w,2214
+cat_claws-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+cat_claws-0.1.0.dist-info/RECORD,,

cat_claws-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

catclaws/__about__.py

@@ -0,0 +1,6 @@
+# SPDX-FileCopyrightText: 2026-present Christopher Soria <chrissoria@berkeley.edu>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+__version__ = "0.1.0"
+__title__ = "cat-claws"
+__description__ = "Claude Agent SDK backend for the CatLLM ecosystem"

catclaws/__init__.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2026-present Christopher Soria <chrissoria@berkeley.edu>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""cat-claws — agent-CLI backend for the CatLLM ecosystem.
+
+Classify text through a Claude subscription (Claude Agent SDK) instead of
+per-token API billing. See MASTERPLAN.md for design and roadmap.
+"""
+
+from .__about__ import __version__
+from .classify import classify
+
+__all__ = ["classify", "__version__"]

catclaws/_adapters/__init__.py

@@ -0,0 +1,16 @@
+from .base import AgentAdapter
+from .claude import ClaudeAdapter
+
+# Adapter registry — Codex joins here in a later phase.
+ADAPTERS = {
+    "claude": ClaudeAdapter,
+}
+
+
+def get_adapter(name: str) -> AgentAdapter:
+    try:
+        return ADAPTERS[name]()
+    except KeyError:
+        raise ValueError(
+            f"Unknown agent {name!r}. Available: {sorted(ADAPTERS)}"
+        ) from None

catclaws/_adapters/base.py

@@ -0,0 +1,70 @@
+"""AgentAdapter contract.
+
+An adapter turns ONE prompt into ONE answer through an agent CLI, with
+sealed-session semantics baked into the contract:
+
+- fresh context per call (no conversation shared across rows),
+- no tools, single turn, no user/project settings or memory files loaded,
+- a custom system prompt replacing the agent's own scaffolding.
+
+Everything above the adapter (prompt building, JSON parsing, the output
+matrix, concurrency) is agent-agnostic. The Claude adapter is the first
+implementation; an OpenAI Codex adapter (`codex exec`) is planned against
+this same contract.
+"""
+
+import re
+
+# Part of the adapter contract: when a call fails specifically because the
+# subscription hit a usage/rate limit, the returned error string starts with
+# this prefix. classify() keys on it to apply backoff (a plain error does
+# not retry with backoff). Every adapter must use this prefix for rate-limit
+# failures so the backoff logic stays agent-agnostic.
+RATE_LIMIT_PREFIX = "rate-limited: "
+
+# When an adapter knows when the limit resets, it appends this suffix so the
+# caller can tell a transient throttle (retry) from a hard cap hours away
+# (futile to retry — fail fast with a resumable message). Optional: adapters
+# without a reset time simply omit it, and the caller falls back to backoff.
+_RESET_EPOCH_RE = re.compile(r"resets at epoch (\d+)")
+
+
+def is_rate_limited(error: str | None) -> bool:
+    """True if an adapter error string signals a subscription rate limit."""
+    return bool(error) and error.startswith(RATE_LIMIT_PREFIX)
+
+
+def parse_reset_epoch(error: str | None) -> int | None:
+    """Unix epoch when the limit resets, if the adapter included one.
+
+    Matches the ``(resets at epoch N)`` suffix the Claude adapter emits from
+    the SDK's ``RateLimitInfo.resets_at``. Returns None when absent (unknown
+    reset -> caller should fall back to bounded backoff)."""
+    if not error:
+        return None
+    m = _RESET_EPOCH_RE.search(error)
+    return int(m.group(1)) if m else None
+
+
+class AgentAdapter:
+    """One sealed agent call. Implementations are stateless."""
+
+    name: str = "base"
+
+    async def one_shot(
+        self,
+        prompt: str,
+        system_prompt: str | None,
+        model: str,
+        thinking_budget: int = 0,
+    ) -> tuple[str | None, str | None]:
+        """Run one sealed call; return (text, error) — exactly one is None.
+
+        thinking_budget follows cat-stack semantics: 0 disables reasoning,
+        >0 grades into the provider's effort vocabulary.
+
+        Rate-limit failures must return an error string prefixed with
+        ``RATE_LIMIT_PREFIX`` so the caller can back off (see contract note
+        above). All other failures return an ordinary error string.
+        """
+        raise NotImplementedError

catclaws/_adapters/claude.py

@@ -0,0 +1,186 @@
+"""Claude adapter — claude-agent-sdk implementation of AgentAdapter.
+
+Requires Claude Code installed and logged in (`claude` on PATH). Calls run
+through the user's Claude subscription, not an API key.
+"""
+
+from .base import RATE_LIMIT_PREFIX, AgentAdapter
+
+# --- rate-limit detection (pure helpers, unit-tested in tests/test_rate_limit.py) ---
+#
+# The SDK surfaces subscription limits three ways (verified on sdk 0.2.110):
+#   1. a `RateLimitEvent` in the message stream, carrying a `RateLimitInfo`
+#      whose `status`/`overage_status` is one of 'allowed'|'allowed_warning'|
+#      'rejected' — only 'rejected' is an actual block;
+#   2. a `ResultMessage.api_error_status` of 429 (too many requests);
+#   3. as a last resort, rate-limit wording in an error/result string.
+# All three funnel into the RATE_LIMIT_PREFIX error so classify() backs off.
+
+_RATE_LIMIT_TEXT_MARKERS = (
+    "rate limit",
+    "rate-limit",
+    "rate_limit",
+    "usage limit",
+    "too many requests",
+    "quota exceeded",
+    "429",
+)
+
+
+def _looks_rate_limited_text(text) -> bool:
+    """Text fallback: does an error/result string read like a rate limit?"""
+    if not text:
+        return False
+    low = str(text).lower()
+    return any(marker in low for marker in _RATE_LIMIT_TEXT_MARKERS)
+
+
+def _rate_limit_detail(info) -> str | None:
+    """Human detail if the PRIMARY usage window is exhausted, else None.
+
+    Only ``status == "rejected"`` blocks the current request. 'allowed' and
+    'allowed_warning' both let it through (the latter just warns the cap is
+    near). Crucially, ``overage_status`` is NOT a per-request block: a common
+    steady state is ``overage_status='rejected'`` with
+    ``overage_disabled_reason='org_level_disabled'`` — the org simply turned
+    off spillover billing — while ``status='allowed'`` and the call succeeds.
+    Treating overage rejection as a limit falsely fails every call on such
+    accounts (verified live 2026-07-03), so it is deliberately ignored here.
+    """
+    if info is None:
+        return None
+    if getattr(info, "status", None) != "rejected":
+        return None
+    rtype = getattr(info, "rate_limit_type", None) or "usage"
+    resets = getattr(info, "resets_at", None)
+    detail = f"{rtype} limit reached"
+    if resets:
+        detail += f" (resets at epoch {resets})"
+    return detail
+
+
+def _api_status_is_rate_limit(status) -> bool:
+    """HTTP 429 (too many requests) is the rate-limit status."""
+    return status == 429
+
+
+def _finalize(text, result_error, rate_limit_detail):
+    """Turn collected stream state into the (text, error) contract result.
+
+    A real answer always wins: RateLimitEvents are emitted on SUCCESSFUL calls
+    too (they report current utilization), so a present answer with no error
+    means the request went through — never discard it for an informational
+    limit event. Only when there's no answer do limits (retryable via backoff)
+    win over ordinary errors.
+    """
+    if text and not result_error:
+        return text, None
+    if rate_limit_detail:
+        return None, f"{RATE_LIMIT_PREFIX}{rate_limit_detail}"
+    if result_error:
+        if _looks_rate_limited_text(result_error):
+            return None, f"{RATE_LIMIT_PREFIX}{result_error}"
+        return None, str(result_error)
+    if text:
+        return text, None
+    return None, "agent returned an empty response"
+
+
+class ClaudeAdapter(AgentAdapter):
+    name = "claude"
+
+    async def one_shot(
+        self,
+        prompt: str,
+        system_prompt: str | None,
+        model: str,
+        thinking_budget: int = 0,
+    ) -> tuple[str | None, str | None]:
+        try:
+            from claude_agent_sdk import (
+                query,
+                ClaudeAgentOptions,
+                AssistantMessage,
+                RateLimitEvent,
+                ResultMessage,
+                TextBlock,
+                CLINotFoundError,
+            )
+            from claude_agent_sdk.types import (
+                ThinkingConfigDisabled,
+            )
+        except ImportError as e:
+            return None, (
+                "claude-agent-sdk is not installed. Run: pip install cat-agent "
+                f"(original error: {e})"
+            )
+
+        # Sealed session: fresh context, no tools, one turn, no user/project
+        # settings or CLAUDE.md files (running classify() from inside a repo
+        # must not inject that repo's instructions into classifications).
+        opts_kwargs = dict(
+            model=model,
+            allowed_tools=[],
+            max_turns=1,
+            setting_sources=[],
+        )
+        if system_prompt:
+            opts_kwargs["system_prompt"] = system_prompt
+
+        # Engine parity: the agent enables thinking by default (Phase-0
+        # probe), but cat-stack's default is thinking_budget=0 -> off.
+        # Positive budgets grade into the shared effort vocabulary.
+        if thinking_budget and thinking_budget > 0:
+            from catstack._providers import _thinking_budget_to_effort
+            opts_kwargs["effort"] = _thinking_budget_to_effort(thinking_budget)
+        else:
+            opts_kwargs["thinking"] = ThinkingConfigDisabled(type="disabled")
+
+        async def _run(options):
+            """Consume one query stream -> (text, result_error, rate_limit_detail)."""
+            text_parts = []
+            result_error = None
+            rate_limit_detail = None
+            async for message in query(prompt=prompt, options=options):
+                if isinstance(message, AssistantMessage):
+                    for block in message.content:
+                        if isinstance(block, TextBlock):
+                            text_parts.append(block.text)
+                elif isinstance(message, RateLimitEvent):
+                    detail = _rate_limit_detail(getattr(message, "rate_limit_info", None))
+                    if detail:
+                        rate_limit_detail = detail
+                elif isinstance(message, ResultMessage):
+                    if _api_status_is_rate_limit(getattr(message, "api_error_status", None)):
+                        rate_limit_detail = rate_limit_detail or "HTTP 429 (too many requests)"
+                    if getattr(message, "is_error", False):
+                        errs = getattr(message, "errors", None) or []
+                        parts = [
+                            str(p)
+                            for p in ([getattr(message, "result", None)] + list(errs))
+                            if p
+                        ]
+                        result_error = " ".join(parts) or "agent returned an error result"
+            return "".join(text_parts).strip(), result_error, rate_limit_detail
+
+        try:
+            return _finalize(*await _run(ClaudeAgentOptions(**opts_kwargs)))
+        except CLINotFoundError:
+            return None, (
+                "Claude CLI not found. Install it: https://code.claude.com/docs"
+            )
+        except Exception as e:
+            if _looks_rate_limited_text(e):
+                return None, f"{RATE_LIMIT_PREFIX}{e}"
+            # Thinking-config incompatibilities (e.g. models that reject an
+            # explicit disable) fall back to the agent default rather than
+            # failing the row.
+            if "thinking" in str(e).lower() and "thinking" in opts_kwargs:
+                opts_kwargs.pop("thinking", None)
+                try:
+                    return _finalize(*await _run(ClaudeAgentOptions(**opts_kwargs)))
+                except Exception as e2:
+                    if _looks_rate_limited_text(e2):
+                        return None, f"{RATE_LIMIT_PREFIX}{e2}"
+                    return None, f"claude adapter failed: {e2}"
+            return None, f"claude adapter failed: {e}"

catclaws/_backend.py

@@ -0,0 +1,31 @@
+"""Agent-agnostic plumbing: bounded-concurrency execution of sealed calls.
+
+classify() is synchronous (matching the rest of the CatLLM ecosystem); the
+SDKs are asyncio-native. This module owns that seam: build one coroutine per
+row, run them all under a semaphore in a single event loop.
+"""
+
+import asyncio
+
+
+def gather_bounded(coro_fns, max_workers: int = 4):
+    """Run zero-arg coroutine factories with at most `max_workers` in flight.
+
+    Returns results in input order. Factory exceptions are captured and
+    returned in place of results (callers decide how to record the failure) —
+    one bad row must never abort the batch.
+    """
+
+    async def _run():
+        sem = asyncio.Semaphore(max(1, int(max_workers)))
+
+        async def _bounded(fn):
+            async with sem:
+                try:
+                    return await fn()
+                except Exception as e:
+                    return e
+
+        return await asyncio.gather(*[_bounded(fn) for fn in coro_fns])
+
+    return asyncio.run(_run())

catclaws/classify.py

@@ -0,0 +1,186 @@
+"""catclaws.classify() — one-row-at-a-time classification through an agent CLI.
+
+Design (see MASTERPLAN.md):
+- One row = one sealed, fresh-context agent call. Throughput comes from
+  bounded concurrency, never from shared conversations or corpus prompts.
+- Prompts are cat-stack's validated classification prompt, byte-identical to
+  the API path (`build_text_classification_prompt`).
+- The model answers in JSON (prompt-requested); parsing reuses cat-stack's
+  `extract_json` + `validate_classification_json`; output is the standard
+  wide 0/1 DataFrame.
+"""
+
+import asyncio
+import time
+
+import pandas as pd
+
+from ._adapters import get_adapter
+from ._adapters.base import is_rate_limited, parse_reset_epoch
+from ._backend import gather_bounded
+
+# The system prompt is transport scaffolding (it replaces Claude Code's
+# default agent persona), NOT part of the validated per-row instrument —
+# the instrument travels entirely in the user prompt, as it does on the
+# API path where no system message is sent for text classification.
+_SYSTEM_PROMPT = (
+    "You are a text classification engine. Follow the user's instructions "
+    "exactly and reply with only what they ask for."
+)
+
+# First rate-limit backoff, in seconds (doubles each retry). Subscription
+# usage windows are minutes-scale, so the wait starts coarse rather than at
+# API-style sub-second values.
+_RATE_LIMIT_BASE_DELAY = 30.0
+
+
+def classify(
+    input_data,
+    categories,
+    user_model: str = "claude-sonnet-5",
+    agent: str = "claude",
+    description: str = "",
+    multi_label: bool = True,
+    thinking_budget: int = 0,
+    max_workers: int = 4,
+    json_retries: int = 2,
+    rate_limit_retries: int = 2,
+):
+    """Classify text rows into 0/1 category indicators via an agent CLI.
+
+    Runs on the agent's subscription login (no API key). Same prompt, same
+    JSON contract, and same output schema as ``catstack.classify()``.
+
+    Args:
+        input_data: list of text rows (or pandas Series).
+        categories: list of category names.
+        user_model: model the agent should use (e.g. "claude-sonnet-5").
+        agent: which agent CLI answers ("claude"; "codex" planned).
+        description: context about the data (survey question etc.) — feeds
+            the same "Context:" line as the API path.
+        multi_label: multiple categories per row (default) vs single best.
+        thinking_budget: cat-stack semantics — 0 disables reasoning (default,
+            engine parity), >0 grades into the agent's effort vocabulary.
+        max_workers: concurrent sealed calls in flight.
+        json_retries: re-asks per row when the reply isn't valid JSON.
+        rate_limit_retries: on a rate-limited row, how many times to back off
+            (exponential from 30s) and retry before giving up. Consumed before
+            json_retries; set 0 to fail fast on limits. Other in-flight rows
+            are unaffected while one row waits.
+
+    Returns:
+        pandas.DataFrame with input_data, processing_status, and one 0/1
+        category_N column per category (same schema as catstack.classify()).
+    """
+    from catstack.text_functions_ensemble import build_text_classification_prompt
+    from catstack import extract_json
+    from catstack._utils import validate_classification_json
+
+    rows = list(input_data)
+    if not rows:
+        raise ValueError("input_data is empty")
+    categories = list(categories)
+    if not categories:
+        raise ValueError("categories is empty")
+
+    adapter = get_adapter(agent)
+
+    # Same prompt components as the engine builds them.
+    categories_str = "\n".join(f"{i + 1}. {cat}" for i, cat in enumerate(categories))
+    survey_question_context = f"Context: {description}." if description else ""
+
+    def _row_prompt(text):
+        messages = build_text_classification_prompt(
+            response_text=text if text is not None else "",
+            categories_str=categories_str,
+            survey_question_context=survey_question_context,
+            multi_label=multi_label,
+        )
+        return messages[-1]["content"]
+
+    n_cats = len(categories)
+
+    # Total seconds our backoff schedule (30s, doubling) can bridge. A limit
+    # that resets beyond this can't be waited out here, so retrying is futile.
+    _backoff_budget = sum(
+        _RATE_LIMIT_BASE_DELAY * (2 ** k)
+        for k in range(max(0, int(rate_limit_retries)))
+    )
+
+    def _success(values):
+        return {
+            "status": "success",
+            "indicators": [
+                1 if str(values.get(str(i + 1), "0")) == "1" else 0
+                for i in range(n_cats)
+            ],
+        }
+
+    async def _classify_row(text):
+        """One row: sealed call -> parse -> validate.
+
+        Two independent retry budgets. A rate-limited reply spends a
+        `rate_limit_retries` slot: back off (exponential from 30s) and re-ask,
+        without touching json_retries — re-asking a limit immediately would
+        just hit it again. The `await asyncio.sleep` yields the event loop, so
+        other in-flight rows keep going while this one waits. Any other
+        malformed/failed reply spends a `json_retries` slot and re-asks now.
+        """
+        prompt = _row_prompt(text)
+        last_error = "unknown error"
+        rl_retries_left = max(0, int(rate_limit_retries))
+        json_retries_left = max(0, int(json_retries))
+        delay = _RATE_LIMIT_BASE_DELAY
+        while True:
+            reply, error = await adapter.one_shot(
+                prompt,
+                system_prompt=_SYSTEM_PROMPT,
+                model=user_model,
+                thinking_budget=thinking_budget,
+            )
+            if error and is_rate_limited(error):
+                # A hard cap resetting beyond our backoff budget won't clear by
+                # retrying — fail fast with the resumable message rather than
+                # sleeping through futile re-asks (learned from a live
+                # five_hour-window rejection). Unknown/near resets still back off.
+                reset = parse_reset_epoch(error)
+                futile = reset is not None and (reset - time.time()) > _backoff_budget
+                if rl_retries_left > 0 and not futile:
+                    rl_retries_left -= 1
+                    await asyncio.sleep(delay)
+                    delay *= 2
+                    continue
+                # Backoff exhausted or futile — terminal for this row.
+                return {"status": f"error: {error}", "indicators": [None] * n_cats}
+            if error:
+                last_error = error
+            else:
+                parsed = extract_json(reply)
+                ok, values = (False, None)
+                if parsed:
+                    ok, values = validate_classification_json(parsed, n_cats)
+                if ok:
+                    return _success(values)
+                last_error = f"invalid classification JSON in reply: {reply[:120]!r}"
+            if json_retries_left > 0:
+                json_retries_left -= 1
+                continue
+            return {"status": f"error: {last_error}", "indicators": [None] * n_cats}
+
+    results = gather_bounded(
+        [lambda t=t: _classify_row(t) for t in rows], max_workers=max_workers
+    )
+
+    out = {"input_data": rows, "processing_status": []}
+    for i in range(n_cats):
+        out[f"category_{i + 1}"] = []
+    for res in results:
+        if isinstance(res, Exception):
+            res = {"status": f"error: {res}", "indicators": [None] * n_cats}
+        out["processing_status"].append(
+            "success" if res["status"] == "success" else res["status"]
+        )
+        for i in range(n_cats):
+            out[f"category_{i + 1}"].append(res["indicators"][i])
+
+    return pd.DataFrame(out)