fix(reducer): snippet-fallback labels + in-place /relabel endpoint

Closes the gap where free_label_from_terms could still bottom out at
"Cluster N" when the c-TF-IDF vocabulary collapsed entirely (URLs,
numbers, non-alpha tokens). The labeler now passes the medoid snippet
into the free path too — previously snippets only fed the opt-in LLM
upgrade — and falls back to a Title-Cased, sanitized fragment of that
snippet when terms are empty. The bare numeric placeholder only
survives the case where every text in the cluster is genuinely empty.

Adds POST /relabel/{project_id} and a matching `uv run python -m
app.cli relabel <id>` subcommand so projects already persisted with
placeholder labels can be repaired without re-embedding. The route
runs through the existing reducer secret + Starlette threadpool; the
CLI talks Postgres directly so label repair works even when the
reducer service isn't live.

app/api.py

@@ -16,7 +16,16 @@ from pydantic import BaseModel, Field
 
 from .auth import verify_reducer_secret
 from .config import ASYNC_ROW_THRESHOLD, DEFAULT_EMBED_MODEL, DEFAULT_REDUCER, REDIS_URL
-from .db import connect, ensure_project, fetch_status, set_status, write_results
+from .db import (
+    connect,
+    ensure_project,
+    fetch_points_for_labeling,
+    fetch_status,
+    set_status,
+    update_cluster_labels,
+    write_results,
+)
+from .labeling import label_clusters
 from .pipeline import run_pipeline
 from .progress import get_progress
 
@@ -161,6 +170,50 @@ async def embed_reduce(req: EmbedReduceRequest) -> EmbedReduceResponse:
     return EmbedReduceResponse(**summary, mode="sync")
 
 
+class RelabelResponse(BaseModel):
+    project_id: str
+    n_clusters: int
+    n_updated: int
+    labels: dict[int, str]
+
+
+@router.post(
+    "/relabel/{project_id}",
+    response_model=RelabelResponse,
+    dependencies=[Depends(verify_reducer_secret)],
+)
+async def relabel(project_id: str) -> RelabelResponse:
+    """Recompute cluster labels for an existing project without re-embedding.
+
+    Pulls texts + cluster_ids straight from the points table, runs the
+    free c-TF-IDF (and optional LLM upgrade) labeler, and writes the result
+    back to clusters.label. Used to repair projects whose labels were
+    persisted as 'Cluster N' placeholders by an older reducer build.
+    """
+
+    def _do_work() -> tuple[int, int, dict[int, str]]:
+        with connect() as conn:
+            texts, cluster_ids, snippets = fetch_points_for_labeling(conn, project_id)
+            if not texts:
+                raise HTTPException(
+                    status_code=404,
+                    detail=f"project {project_id} has no points (or does not exist)",
+                )
+            labels = label_clusters(
+                texts, cluster_ids, medoid_snippets_by_cluster=snippets or None
+            )
+            updated = update_cluster_labels(conn, project_id, labels)
+            return len(labels), updated, labels
+
+    n_clusters, n_updated, labels = await anyio.to_thread.run_sync(_do_work)
+    return RelabelResponse(
+        project_id=project_id,
+        n_clusters=n_clusters,
+        n_updated=n_updated,
+        labels=labels,
+    )
+
+
 @router.get(
     "/status/{project_id}",
     response_model=StatusResponse,

app/cli.py

@@ -11,7 +11,15 @@ import pandas as pd
 import typer
 
 from .config import DEFAULT_EMBED_MODEL, DEFAULT_REDUCER
-from .db import connect, ensure_project, set_status, write_results
+from .db import (
+    connect,
+    ensure_project,
+    fetch_points_for_labeling,
+    set_status,
+    update_cluster_labels,
+    write_results,
+)
+from .labeling import label_clusters
 from .pipeline import run_pipeline
 
 cli = typer.Typer(add_completion=False, no_args_is_help=True)
@@ -200,6 +208,32 @@ def bake_static(
     typer.echo(f"wrote      : {out_path} ({size_mb:.2f} MiB)")
 
 
+@cli.command()
+def relabel(
+    project_id: str = typer.Argument(..., help="UUID of project to relabel"),  # noqa: B008
+) -> None:
+    """Recompute and persist cluster labels for an existing project.
+
+    Reads texts + cluster_ids straight from points, runs c-TF-IDF (+ optional
+    LLM upgrade if OPENAI_API_KEY is set), and updates clusters.label in place.
+    No embedding work, no point/edge writes — just label repair.
+    """
+    with connect() as conn:
+        texts, cluster_ids, snippets = fetch_points_for_labeling(conn, project_id)
+        if not texts:
+            typer.echo(f"project {project_id}: no points (or missing)")
+            raise typer.Exit(code=1)
+        labels = label_clusters(
+            texts, cluster_ids, medoid_snippets_by_cluster=snippets or None
+        )
+        updated = update_cluster_labels(conn, project_id, labels)
+    typer.echo(f"project {project_id}")
+    typer.echo(f"  clusters : {len(labels)}")
+    typer.echo(f"  updated  : {updated}")
+    for cid, lbl in sorted(labels.items()):
+        typer.echo(f"  {cid:>3}: {lbl}")
+
+
 def main() -> None:
     cli()
 

app/db.py

@@ -251,3 +251,71 @@ def write_results(
     }
 
 
+def fetch_points_for_labeling(
+    conn: psycopg.Connection, project_id: str
+) -> tuple[list[str], np.ndarray, dict[int, list[str]]]:
+    """Return (texts, cluster_ids, medoid_snippets_by_cluster) for a project.
+
+    Used by the relabel path to recompute labels in place without re-embedding.
+    `medoid_snippets_by_cluster` is built from each cluster's recorded
+    medoid_point_id (preferred) with a high-probability fallback so the LLM
+    upgrade path still has decent input even on older rows where the medoid
+    text isn't otherwise distinguished.
+    """
+    rows = conn.execute(
+        """
+        select text, cluster_id
+        from public.points
+        where project_id = %s
+        order by id
+        """,
+        (project_id,),
+    ).fetchall()
+    texts: list[str] = []
+    cids: list[int] = []
+    for text, cid in rows:
+        texts.append(text or "")
+        cids.append(int(cid) if cid is not None else -1)
+
+    snippets: dict[int, list[str]] = {}
+    medoid_rows = conn.execute(
+        """
+        select c.cluster_id, p.text
+        from public.clusters c
+        left join public.points p on p.id = c.medoid_point_id
+        where c.project_id = %s
+        """,
+        (project_id,),
+    ).fetchall()
+    for cid, text in medoid_rows:
+        if text:
+            snippets.setdefault(int(cid), []).append(text)
+
+    return texts, np.array(cids, dtype=np.int32), snippets
+
+
+def update_cluster_labels(
+    conn: psycopg.Connection, project_id: str, labels: dict[int, str]
+) -> int:
+    """Overwrite cluster.label for the given (project_id, cluster_id) pairs.
+    Returns the number of rows updated. Tenant scoping is enforced by the
+    project_id filter; this helper runs with the service-role connection so
+    RLS is not in play here — callers must already have authorized the project.
+    """
+    if not labels:
+        return 0
+    updated = 0
+    with conn.cursor() as cur:
+        for cid, label in labels.items():
+            cur.execute(
+                """
+                update public.clusters
+                set label = %s
+                where project_id = %s and cluster_id = %s
+                """,
+                (label, project_id, int(cid)),
+            )
+            updated += cur.rowcount or 0
+    return updated
+
+

app/labeling.py

@@ -33,6 +33,7 @@ LABEL_LLM_MODEL = "gpt-4o-mini"
 
 _LEAD_LABEL_RE = re.compile(r"^(label|topic|title|name)\s*[:\-]\s*", re.IGNORECASE)
 _TRAIL_PUNCT = ".,;:!?-—–\"'`"
+_WORDLIKE_RE = re.compile(r"\S+")
 
 
 def _texts_by_cluster(texts: list[str], cluster_ids: np.ndarray) -> dict[int, list[str]]:
@@ -107,18 +108,57 @@ def ctfidf_terms(
     return out
 
 
+def _snippet_label(snippet: str | None, max_chars: int, max_words: int) -> str | None:
+    """Title-cased fragment of a representative snippet, used as the very last
+    resort when c-TF-IDF produced nothing usable (vocabulary collapsed to
+    stopwords, URLs, numbers, or single characters). Returns None when the
+    snippet itself has nothing word-like to show.
+    """
+    if not snippet:
+        return None
+    s = _sanitize(snippet).strip()
+    if not s:
+        return None
+    words = _WORDLIKE_RE.findall(s)
+    if not words:
+        return None
+    picked: list[str] = []
+    for w in words[: max_words * 2]:
+        picked.append(w)
+        if len(" ".join(picked)) >= max_chars or len(picked) >= max_words:
+            break
+    label = " ".join(picked).rstrip(_TRAIL_PUNCT).strip()
+    if not label:
+        return None
+    if len(label) > max_chars:
+        label = label[: max_chars - 1].rstrip() + "…"
+    return " ".join(w.capitalize() if w.isalpha() else w for w in label.split())
+
+
 def free_label_from_terms(
-    terms: list[str], cluster_id: int, max_chars: int = LABEL_MAX_CHARS, max_terms: int = 3
+    terms: list[str],
+    cluster_id: int,
+    *,
+    snippet: str | None = None,
+    max_chars: int = LABEL_MAX_CHARS,
+    max_terms: int = 3,
 ) -> str:
-    """Title-cased label from top distinctive terms. Falls back to 'Cluster N'."""
-    if not terms:
-        return f"Cluster {cluster_id}"
-    for n in range(min(max_terms, len(terms)), 0, -1):
-        label = " ".join(t.capitalize() for t in terms[:n])
-        if len(label) <= max_chars:
-            return label
-    # Even one term is too long — truncate hard.
-    return terms[0].capitalize()[: max_chars - 1] + "…"
+    """Title-cased label from top distinctive terms. When `terms` is empty,
+    falls back to a sanitized fragment of `snippet` (the cluster medoid). Only
+    if both are unusable do we return the bare 'Cluster N' — and that branch
+    should be unreachable in practice now that the medoid is always passed in.
+    """
+    if terms:
+        for n in range(min(max_terms, len(terms)), 0, -1):
+            label = " ".join(t.capitalize() for t in terms[:n])
+            if len(label) <= max_chars:
+                return label
+        return terms[0].capitalize()[: max_chars - 1] + "…"
+
+    fallback = _snippet_label(snippet, max_chars, LABEL_MAX_WORDS)
+    if fallback:
+        return fallback
+    return f"Cluster {cluster_id}"
 
 
 def _clean_llm_label(raw: str, max_chars: int, max_words: int) -> str | None:
@@ -235,7 +275,13 @@ def label_clusters(
 
     labels: dict[int, str] = {}
     for cid in grouped:
-        labels[cid] = free_label_from_terms(top_terms.get(cid, []), cid)
+        snippet = None
+        if medoid_snippets_by_cluster:
+            snips = medoid_snippets_by_cluster.get(cid) or []
+            snippet = snips[0] if snips else None
+        if snippet is None and grouped.get(cid):
+            snippet = grouped[cid][0]
+        labels[cid] = free_label_from_terms(top_terms.get(cid, []), cid, snippet=snippet)
 
     if config.OPENAI_API_KEY and medoid_snippets_by_cluster:
         for cid in grouped:

tests/test_labeling.py

@@ -252,13 +252,13 @@ def test_label_clusters_degenerate_input_prefers_keyword_over_placeholder(
         )
 
 
-def test_label_clusters_truly_unlabelable_keeps_placeholder(
+def test_label_clusters_stopword_only_falls_back_to_snippet(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    # All-stopword/punctuation input → CountVectorizer raises ValueError on
-    # empty vocabulary → ctfidf_terms returns {c: []} → free fallback to
-    # "Cluster N". This is the ONLY case where the numeric placeholder is
-    # acceptable.
+    # All-stopword input → CountVectorizer raises ValueError on empty
+    # vocabulary → ctfidf_terms returns {c: []}. Old behavior was to drop
+    # to bare "Cluster N"; new contract is to use the medoid snippet so the
+    # user still sees *something* from their own text in the title card.
     monkeypatch.setattr(config, "OPENAI_API_KEY", "")
 
     texts = ["the and of"] * 5 + ["a an in"] * 5
@@ -266,7 +266,25 @@ def test_label_clusters_truly_unlabelable_keeps_placeholder(
 
     labels = labeling.label_clusters(texts, cluster_ids)
     assert set(labels.keys()) == {0, 1}
-    # Documenting the contract: numeric placeholders only appear when truly
-    # no keyword can be extracted (e.g. empty vocabulary after stopwording).
+    for cid, lbl in labels.items():
+        assert lbl, f"cluster {cid} produced an empty label"
+        assert lbl != f"Cluster {cid}", (
+            f"cluster {cid} fell through to the bare numeric placeholder"
+        )
+
+
+def test_label_clusters_only_unusable_text_returns_placeholder(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # The single remaining case where the numeric placeholder is acceptable:
+    # every text in the cluster is genuinely empty after sanitization, so
+    # neither c-TF-IDF nor the snippet fallback has anything to show.
+    monkeypatch.setattr(config, "OPENAI_API_KEY", "")
+
+    texts = ["", "   ", "\t\t"] + ["", "  "]
+    cluster_ids = np.array([0, 0, 0, 1, 1], dtype=np.int32)
+
+    labels = labeling.label_clusters(texts, cluster_ids)
+    assert set(labels.keys()) == {0, 1}
     for cid, lbl in labels.items():
         assert lbl == f"Cluster {cid}"