claude-sql 0.4.0__py3-none-any.whl

claude_sql/terms_worker.py

@@ -0,0 +1,145 @@
+"""c-TF-IDF per cluster -- in-house (no bertopic).
+
+Reads ``clusters.parquet`` (from cluster_worker) and the text messages
+view to build one pseudo-document per cluster, then runs a sklearn
+``CountVectorizer`` and computes the c-TF-IDF weights used by BERTopic.
+Writes top-N terms per cluster to ``cluster_terms.parquet``.
+
+Public API
+----------
+run_terms(con, settings, *, force=False) -> dict[str, int]
+    Compute ``cluster_terms.parquet``.  Returns ``{"clusters": K, "terms": N}``.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+import numpy as np
+import polars as pl
+from loguru import logger
+
+if TYPE_CHECKING:
+    import duckdb
+
+    from claude_sql.config import Settings
+
+
+def run_terms(
+    con: duckdb.DuckDBPyConnection,
+    settings: Settings,
+    *,
+    force: bool = False,
+) -> dict[str, int]:
+    """Compute c-TF-IDF top terms per cluster and write the parquet output.
+
+    Parameters
+    ----------
+    con
+        Open DuckDB connection with ``messages_text`` registered.
+    settings
+        Runtime settings (``clusters_parquet_path``, ``cluster_terms_parquet_path``,
+        and the ``tfidf_*`` hyperparameters).
+    force
+        If True, recompute even when the output parquet already exists.
+
+    Returns
+    -------
+    dict[str, int]
+        ``{"clusters": K, "terms": N}`` where K is the number of clusters
+        processed and N is the total row count written to parquet.
+    """
+    out = settings.cluster_terms_parquet_path
+    clusters_path = settings.clusters_parquet_path
+
+    if not clusters_path.exists() or clusters_path.stat().st_size < 16:
+        raise FileNotFoundError(
+            f"Clusters parquet missing at {clusters_path}.  Run `claude-sql cluster` first."
+        )
+    if out.exists() and out.stat().st_size > 16 and not force:
+        df = pl.read_parquet(out)
+        logger.info("cluster_terms parquet already exists at {}", out)
+        return {"clusters": int(df["cluster_id"].n_unique()), "terms": len(df)}
+
+    from sklearn.feature_extraction.text import CountVectorizer
+
+    t0 = time.monotonic()
+    # Join clusters parquet to messages_text on uuid.  ``mt.uuid`` is DuckDB
+    # UUID; the parquet column is VARCHAR -- cast to match.
+    sql = """
+        SELECT c.cluster_id,
+               mt.text_content
+          FROM read_parquet(?) c
+          JOIN messages_text mt
+            ON CAST(mt.uuid AS VARCHAR) = c.uuid
+         WHERE c.cluster_id >= 0
+           AND mt.text_content IS NOT NULL
+    """
+    df = con.execute(sql, [str(clusters_path)]).pl()
+    logger.info(
+        "Joined {} rows clusters x messages_text in {:.1f}s",
+        len(df),
+        time.monotonic() - t0,
+    )
+
+    # Build one pseudo-document per cluster.
+    per_cluster = (
+        df.group_by("cluster_id")
+        .agg(pl.col("text_content").str.join("\n").alias("doc"))
+        .sort("cluster_id")
+    )
+    cluster_ids = per_cluster["cluster_id"].to_list()
+    docs = per_cluster["doc"].to_list()
+    logger.info("Built {} cluster pseudo-docs", len(docs))
+
+    cv = CountVectorizer(
+        min_df=settings.tfidf_min_df,
+        max_df=settings.tfidf_max_df,
+        ngram_range=(settings.tfidf_ngram_min, settings.tfidf_ngram_max),
+        lowercase=True,
+        strip_accents="unicode",
+    ).fit(docs)
+    tf = cv.transform(docs).toarray().astype(np.float32)  # (n_clusters, vocab)
+    vocab = cv.get_feature_names_out()
+    logger.info("Vocabulary size: {} terms", len(vocab))
+
+    # c-TF-IDF: term frequency in cluster x log(1 + avg_docs_per_term / col_sum).
+    row_sum = tf.sum(axis=1, keepdims=True)
+    row_sum[row_sum == 0] = 1.0
+    tf_norm = tf / row_sum
+    col_sum = tf.sum(axis=0)
+    total = tf.sum()
+    avg = col_sum / max(total, 1.0)
+    idf = np.log(1.0 + (avg.sum() / np.maximum(col_sum, 1e-9)))
+    ctfidf = tf_norm * idf  # (n_clusters, vocab)
+
+    top_n = settings.tfidf_top_n_terms
+    rows: list[tuple[int, str, float, int]] = []
+    for k, cid in enumerate(cluster_ids):
+        idx = np.argsort(-ctfidf[k])[:top_n]
+        for rank, i in enumerate(idx):
+            w = float(ctfidf[k, i])
+            if w <= 0:
+                continue
+            rows.append((int(cid), str(vocab[i]), w, rank + 1))
+
+    out_df = pl.DataFrame(
+        rows,
+        schema={
+            "cluster_id": pl.Int32,
+            "term": pl.Utf8,
+            "weight": pl.Float32,
+            "rank": pl.Int32,
+        },
+        orient="row",
+    )
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out_df.write_parquet(out)
+    logger.info(
+        "Wrote {} term-rows across {} clusters in {:.1f}s",
+        len(out_df),
+        len(cluster_ids),
+        time.monotonic() - t0,
+    )
+    return {"clusters": len(cluster_ids), "terms": len(out_df)}

claude_sql/ungrounded_worker.py

@@ -0,0 +1,190 @@
+"""Ungrounded-claim detector v0 — entity spotting over tool outputs.
+
+For each assistant turn, extract *factual claims about internal systems*
+(file paths, function names, config flags, CLI subcommands, table names,
+env vars, Slack/work IDs) and check whether those entities appear in the
+same session's tool-call outputs.  An assertion that names an entity
+never seen in tool output is flagged as potentially ungrounded.
+
+This is v0: fast, conservative, a regex+span-graph combo.  A later pass
+can add Nova 2 Lite for claim-phrase extraction when the regex misses
+semantic claims.
+
+Schema written to parquet::
+
+    session_id       STRING
+    turn_idx         INT64
+    claim_entity     STRING     # the specific entity name the agent asserted
+    claim_kind       STRING     # path | function | flag | env_var | id | cli
+    grounded         BOOLEAN    # True if seen in tool output
+    tool_output_hits INT64      # count of exact matches in tool results
+    freeze_sha       STRING
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+import polars as pl
+
+# ---------------------------------------------------------------------------
+# Entity extractors
+# ---------------------------------------------------------------------------
+
+# Unix-ish paths with at least one '/' and a filename-shaped tail
+_PATH_RE = re.compile(r"(?<![A-Za-z])(/(?:[A-Za-z0-9_.-]+/)+[A-Za-z0-9_.-]+)")
+# Python-style dotted function/attr references and bare ident(): handler.run, foo()
+_FUNCTION_RE = re.compile(r"\b([a-z_][a-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)+)\s*\(")
+# Flags: --flag-name, CLAUDE_SQL_CONCURRENCY, SOME_ENV_VAR (>=2 underscores OR upper + underscore)
+_FLAG_RE = re.compile(r"(--[a-z][a-z0-9-]{2,})")
+_ENV_VAR_RE = re.compile(r"\b([A-Z][A-Z0-9_]{4,}_[A-Z0-9_]+)\b")
+# Work item / thread ts / session UUID patterns from blind_handover
+_ID_RE = re.compile(
+    r"\b(wi_[0-9a-f]{12}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\b"
+)
+# Specific CLI subcommand style: `claude-sql <verb>`
+_CLI_RE = re.compile(r"\bclaude-sql\s+([a-z][a-z0-9-]+)\b")
+
+
+@dataclass(frozen=True)
+class Claim:
+    """One extracted claim: entity name + the category it belongs to."""
+
+    entity: str
+    kind: str  # "path" | "function" | "flag" | "env_var" | "id" | "cli"
+
+
+def extract_claims(text: str) -> list[Claim]:
+    """Pull factual-entity claims out of assistant text.
+
+    Order matters: more specific patterns run first so a CLI subcommand
+    isn't double-counted as a generic function call.
+    """
+    claims: list[Claim] = []
+    seen: set[tuple[str, str]] = set()
+
+    def push(entity: str, kind: str) -> None:
+        key = (entity, kind)
+        if key not in seen:
+            seen.add(key)
+            claims.append(Claim(entity=entity, kind=kind))
+
+    for m in _CLI_RE.finditer(text):
+        push(m.group(1), "cli")
+    for m in _PATH_RE.finditer(text):
+        push(m.group(1), "path")
+    for m in _FUNCTION_RE.finditer(text):
+        push(m.group(1), "function")
+    for m in _FLAG_RE.finditer(text):
+        push(m.group(1), "flag")
+    for m in _ENV_VAR_RE.finditer(text):
+        push(m.group(1), "env_var")
+    for m in _ID_RE.finditer(text):
+        push(m.group(1), "id")
+    return claims
+
+
+# ---------------------------------------------------------------------------
+# Grounding check
+# ---------------------------------------------------------------------------
+
+
+def count_in(haystack: str, needle: str) -> int:
+    """Count non-overlapping substring occurrences; safe for regex-unfriendly needles."""
+    if not needle:
+        return 0
+    return haystack.count(needle)
+
+
+def check_claims(claims: Iterable[Claim], tool_output_text: str) -> list[dict]:
+    """For each claim, count hits in the tool-output text and decide grounded."""
+    rows: list[dict] = []
+    for claim in claims:
+        hits = count_in(tool_output_text, claim.entity)
+        rows.append(
+            {
+                "claim_entity": claim.entity,
+                "claim_kind": claim.kind,
+                "grounded": hits > 0,
+                "tool_output_hits": hits,
+            }
+        )
+    return rows
+
+
+# ---------------------------------------------------------------------------
+# Batch over sessions
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Turn:
+    """One assistant turn paired with the tool output visible to it."""
+
+    session_id: str
+    turn_idx: int
+    assistant_text: str
+    tool_output_text: str  # concatenation of ToolResult content from this session
+
+
+def detect(turns: list[Turn], freeze_sha: str) -> pl.DataFrame:
+    """Run the detector over a batch of turns; return a parquet-shaped frame."""
+    rows: list[dict] = []
+    for t in turns:
+        claims = extract_claims(t.assistant_text)
+        checked = check_claims(claims, t.tool_output_text)
+        # PERF401: comprehension would obscure the nested per-turn state mapping.
+        for row in checked:
+            rows.append(  # noqa: PERF401
+                {
+                    "session_id": t.session_id,
+                    "turn_idx": t.turn_idx,
+                    "claim_entity": row["claim_entity"],
+                    "claim_kind": row["claim_kind"],
+                    "grounded": row["grounded"],
+                    "tool_output_hits": row["tool_output_hits"],
+                    "freeze_sha": freeze_sha,
+                }
+            )
+    if not rows:
+        return pl.DataFrame(
+            schema={
+                "session_id": pl.String,
+                "turn_idx": pl.Int64,
+                "claim_entity": pl.String,
+                "claim_kind": pl.String,
+                "grounded": pl.Boolean,
+                "tool_output_hits": pl.Int64,
+                "freeze_sha": pl.String,
+            }
+        )
+    return pl.DataFrame(rows)
+
+
+def summarize(df: pl.DataFrame) -> pl.DataFrame:
+    """Per-session rollup: ungrounded-claim count + rate."""
+    if df.height == 0:
+        return pl.DataFrame(
+            schema={
+                "session_id": pl.String,
+                "n_claims": pl.Int64,
+                "n_ungrounded": pl.Int64,
+                "ungrounded_rate": pl.Float64,
+            }
+        )
+    return (
+        df.group_by("session_id")
+        .agg(
+            pl.len().alias("n_claims"),
+            (~pl.col("grounded")).sum().alias("n_ungrounded"),
+            (1.0 - pl.col("grounded").cast(pl.Float64).mean()).alias("ungrounded_rate"),
+        )
+        .sort("ungrounded_rate", descending=True)
+    )
+
+
+def to_parquet(df: pl.DataFrame, path: Path) -> None:
+    df.write_parquet(path)