atif-sql 0.2.0__py3-none-any.whl

atif_analytics/application/use_cases/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""The four LLM analytics pipelines: classify, conflicts, friction, perceived."""

atif_analytics/application/use_cases/_shared.py

@@ -0,0 +1,264 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Cross-use-case plumbing shared by the four LLM pipelines.
+
+The four are ``PIPELINE_NAMES`` in
+:mod:`atif_analytics.infrastructure.sqlite_state.checkpointer`: classify,
+conflicts, user_friction, perceived.
+
+The provider factory + per-pipeline usage/cost logging (one provider
+instance per pipeline run, usage accumulated in the provider's
+:class:`~atif_models.domain.ports.UsageAccumulator` and logged once at the
+end), and the storage-port default builders.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from loguru import logger
+
+from atif_analytics.infrastructure.parquet_cache import ParquetCache
+from atif_analytics.infrastructure.sqlite_state.checkpointer import SqliteCheckpoint
+from atif_analytics.infrastructure.sqlite_state.retry_queue import SqliteRetryQueue
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine, Generator, Sequence
+    from pathlib import Path
+
+    from atif_analytics.infrastructure.settings import AnalyticsSettings
+    from atif_models.domain.ports import LlmStructuredProvider
+    from atif_models.domain.registry import ModelSpec
+
+
+def build_provider(
+    settings: AnalyticsSettings, pipeline: str
+) -> tuple[LlmStructuredProvider, ModelSpec]:
+    """One provider per pipeline run, sized per atif-models settings.
+
+    Size assignments (atif-models ``LlmSettings``): classify=small,
+    conflicts=large, friction=small, perceived=medium — all resolved through
+    the atif-models registry (no model id is written down here).
+    """
+    from atif_models.infrastructure.openai_bedrock import OpenAiBedrockProvider
+
+    llm = settings.llm()
+    spec = llm.spec_for(pipeline)
+    provider = OpenAiBedrockProvider(
+        spec,
+        region=llm.llm_region,
+        concurrency=llm.llm_concurrency,
+    )
+    logger.info(
+        "{}: provider={} model={} concurrency={}",
+        pipeline,
+        provider.provider,
+        spec.model_id,
+        llm.llm_concurrency,
+    )
+    return provider, spec
+
+
+@contextmanager
+def pipeline_usage(
+    provider: LlmStructuredProvider, spec: ModelSpec, pipeline: str
+) -> Generator[None]:
+    """Log the accumulated usage + estimated cost once per pipeline run."""
+    from atif_models.domain.registry import estimate_cost as spec_cost
+
+    try:
+        yield
+    finally:
+        usage = getattr(provider, "usage", None)
+        if usage is not None:
+            summary = usage.summary()
+            cost = spec_cost(
+                spec,
+                input_tokens=summary["input_tokens"],
+                output_tokens=summary["output_tokens"],
+            )
+            logger.info(
+                "{}: usage calls={} in={} out={} reasoning={} cached={} est_cost={}",
+                pipeline,
+                summary["calls"],
+                summary["input_tokens"],
+                summary["output_tokens"],
+                summary["reasoning_tokens"],
+                summary["cached_tokens"],
+                f"${cost:.4f}" if cost is not None else "n/a",
+            )
+
+
+class RunBudget:
+    """Cross-pipeline dollar ceiling over the providers' UsageAccumulators.
+
+    One instance per ``run_analyze`` LLM lane. Each pipeline registers its
+    ``(provider, spec)`` via :meth:`watch` before dispatching; :meth:`spent_usd`
+    prices every watched accumulator's RUNNING ACTUALS (not estimates), so
+    :meth:`exhausted` is checked cheaply between dispatch batches. When it
+    trips, pipelines stop dispatching — nothing is stamped (no checkpoint, no
+    cache row, no retry entry) for units that never started, so the next run
+    picks them up cleanly.
+
+    OVERSHOOT BOUND. Actual spend is only observable after a call returns, so
+    the ceiling is a stop-dispatch trigger, not a hard cap. Worst case the run
+    ends at ``max_cost_usd`` plus the cost of the units already in flight when
+    the crossing became visible — at most :data:`BUDGET_CHECK_BATCH` units on
+    the most expensive watched model: :func:`gather_under_budget` sends units
+    in batches of that size and checks the budget at each batch boundary, so
+    the overshoot does NOT scale with the session ceiling or the write chunk
+    size. Pinned by ``test_overshoot_never_exceeds_the_documented_budget_batch``.
+    """
+
+    def __init__(self, max_cost_usd: float) -> None:
+        self.max_cost_usd = max_cost_usd
+        self._watched: list[tuple[LlmStructuredProvider, ModelSpec]] = []
+
+    def watch(self, provider: LlmStructuredProvider, spec: ModelSpec) -> None:
+        """Track one pipeline's provider accumulator for the rest of the run."""
+        self._watched.append((provider, spec))
+
+    def spent_usd(self) -> float:
+        """Total actual spend so far across every watched accumulator."""
+        from atif_models.domain.registry import estimate_cost as spec_cost
+
+        total = 0.0
+        for provider, spec in self._watched:
+            usage = getattr(provider, "usage", None)
+            if usage is None:
+                continue
+            summary = usage.summary()
+            cost = spec_cost(
+                spec,
+                input_tokens=summary["input_tokens"],
+                output_tokens=summary["output_tokens"],
+            )
+            total += cost or 0.0
+        return total
+
+    def exhausted(self) -> bool:
+        """True once actual spend has crossed the ceiling."""
+        return self.spent_usd() >= self.max_cost_usd
+
+
+#: Units dispatched between budget re-checks. This is the overshoot unit of
+#: the cost ceiling: the ceiling can only be observed after a call returns,
+#: so whatever is in flight at the crossing is already bought. Small enough
+#: that a stage's overshoot is a handful of calls rather than its whole
+#: remaining batch; large enough to keep the provider's concurrency limiter
+#: (default 16) fed.
+BUDGET_CHECK_BATCH: int = 8
+
+
+async def gather_under_budget[T, R](
+    units: Sequence[T],
+    *,
+    make_coro: Callable[[T], Coroutine[Any, Any, R]],
+    budget: RunBudget | None,
+    batch_size: int = BUDGET_CHECK_BATCH,
+) -> tuple[list[T], list[R | BaseException]]:
+    """Dispatch ``units`` in budget-checked batches; return what actually ran.
+
+    Returns ``(dispatched_units, results)`` — parallel lists, results in
+    ``asyncio.gather(return_exceptions=True)`` form. Dispatch stops at the
+    first batch boundary where the budget is exhausted, so the caller's
+    zip over the pair never stamps a unit that was never sent.
+
+    ``make_coro`` is called lazily per batch: a coroutine built for a unit
+    that never gets dispatched would be an un-awaited coroutine warning.
+    """
+    dispatched: list[T] = []
+    results: list[R | BaseException] = []
+    for start in range(0, len(units), max(1, batch_size)):
+        if budget is not None and budget.exhausted():
+            break
+        batch = list(units[start : start + max(1, batch_size)])
+        batch_results = await asyncio.gather(
+            *(make_coro(unit) for unit in batch), return_exceptions=True
+        )
+        dispatched.extend(batch)
+        results.extend(batch_results)
+    return dispatched, results
+
+
+def build_cache(target: Path) -> ParquetCache:
+    """Default cache port over one sharded parquet dir."""
+    return ParquetCache(target)
+
+
+def write_refusal_audit(
+    refusals_dir: Path,
+    *,
+    pipeline: str,
+    refusals: list[tuple[str, str]],
+) -> None:
+    """Append ``(unit_id, reason)`` refusal audit rows to ``analytics/refusals``.
+
+    Refusal-skips must be queryable, not just log lines. Used by pipelines
+    whose OUTPUT schema cannot hold an in-band sentinel row without bending
+    view semantics — conflicts rows are uuid-keyed PAIRS, so a sentinel pair
+    would poison the conversation-time joins. (classify writes an in-band
+    sentinel instead: its row is session-keyed, so a documented
+    ``goal='[refused]'`` row keeps ``session_classifications`` complete
+    without touching any view.) Empty ``refusals`` is a no-op.
+    """
+    if not refusals:
+        return
+    from datetime import UTC, datetime
+
+    import polars as pl
+
+    now = datetime.now(UTC)
+    ParquetCache(refusals_dir).write_part(
+        pl.DataFrame(
+            {
+                "pipeline": [pipeline] * len(refusals),
+                "unit_id": [uid for uid, _ in refusals],
+                "reason": [reason[:500] for _, reason in refusals],
+                "refused_at": [now] * len(refusals),
+            },
+            schema={
+                "pipeline": pl.Utf8,
+                "unit_id": pl.Utf8,
+                "reason": pl.Utf8,
+                "refused_at": pl.Datetime("us", "UTC"),
+            },
+        )
+    )
+
+
+def build_checkpoint(state_db: Path) -> SqliteCheckpoint:
+    """Default checkpoint port over the corpus ``state.db``."""
+    return SqliteCheckpoint(state_db)
+
+
+def build_retry_queue(state_db: Path) -> SqliteRetryQueue:
+    """Default retry-queue port over the corpus ``state.db``."""
+    return SqliteRetryQueue(state_db)
+
+
+def write_chunk_size(batch_size: int) -> int:
+    """Crash-resilience write chunking: ``max(batch_size*4, 256)`` rows per part.
+
+    This bounds how much completed work a crash can lose, NOT how much the
+    run can spend — the budget ceiling is enforced per
+    :data:`BUDGET_CHECK_BATCH` units inside each chunk, because the default
+    chunk (384) is wider than the whole session ceiling (50).
+    """
+    return max(batch_size * 4, 256)
+
+
+__all__ = [
+    "BUDGET_CHECK_BATCH",
+    "RunBudget",
+    "build_cache",
+    "build_checkpoint",
+    "build_provider",
+    "build_retry_queue",
+    "gather_under_budget",
+    "pipeline_usage",
+    "write_chunk_size",
+    "write_refusal_audit",
+]

atif_analytics/application/use_cases/classify.py

@@ -0,0 +1,430 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Session classification pipeline over the materialized corpus.
+
+Reads complete session transcripts from the MATERIALIZED corpus and emits one
+row per session into the ``session_classifications`` sharded cache with
+work_category, goal, and confidence fields. It runs on the SMALL model tier.
+
+Only ``interactive`` sessions are classified (``session_kind`` in
+:mod:`atif_analytics.domain.transcript`, the rule atif-duck's
+``session_outcomes.kind`` applies). A turn audit is a machine prompt and a
+verdict, and a one-shot job's goal is its one prompt; both are checkpointed
+as skipped without a call, and a session that later grows past one human
+turn is re-admitted by the checkpoint. What a session achieved is
+``session_outcomes.outcome``, computed from the steps, not asked of a model:
+the LLM ``success`` and ``autonomy_tier`` labels were dropped on 2026-09-27
+because they were not reproducible (802 success / 586 failure on the same
+turn-audit outcome).
+Pull-once / write-many shape: anti-join against the parquet, dispatch
+parallel structured-output calls under the provider's concurrency limiter,
+write results in chunks of ``max(batch_size * 4, 256)`` for crash-resilience.
+
+Transcript text is sent to a third-party model provider on this path: a
+session's full rendered body, tool arguments and tool results included,
+leaves this machine.
+
+Error routing (CONTRACT-V2 taxonomy): :class:`RefusalError` is terminal —
+the session is checkpointed with a DOCUMENTED sentinel audit row
+(``work_category='unknown'``, ``goal='[refused]'``, ``confidence=0.0``) so the refusal is queryable and never re-billed;
+:class:`ProviderUnavailable` (and any other exception) goes to the retry
+queue for a later run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+import polars as pl
+from loguru import logger
+
+from atif_analytics.application.prompts import CLASSIFY_SYSTEM_PROMPT
+from atif_analytics.application.use_cases._shared import (
+    RunBudget,
+    build_cache,
+    build_checkpoint,
+    build_provider,
+    build_retry_queue,
+    gather_under_budget,
+    pipeline_usage,
+    write_chunk_size,
+)
+from atif_analytics.domain.costs import estimate_cost_tokens, tokens_for_chars
+from atif_analytics.domain.models import SessionClassification
+from atif_analytics.infrastructure.corpus_reader import CorpusReader
+from atif_analytics.infrastructure.sqlite_state import checkpointer
+
+if TYPE_CHECKING:
+    from atif_analytics.infrastructure.parquet_cache import ParquetCache
+    from atif_analytics.infrastructure.settings import AnalyticsSettings
+    from atif_analytics.infrastructure.sqlite_state.checkpointer import SqliteCheckpoint
+    from atif_analytics.infrastructure.sqlite_state.retry_queue import SqliteRetryQueue
+    from atif_models.domain.ports import LlmStructuredProvider
+    from atif_models.domain.registry import ModelSpec
+
+_PARQUET_SCHEMA: dict[str, Any] = {
+    "session_id": pl.Utf8,
+    "work_category": pl.Utf8,
+    "goal": pl.Utf8,
+    "confidence": pl.Float32,
+    "classified_at": pl.Datetime("us", "UTC"),
+}
+
+#: Dry-run OUTPUT budget per session (~150 structured-output tokens: two
+#: labels and a one-sentence goal). Input
+#: is MEASURED from the rendered transcript (chars/4), never a static prior:
+#: a real transcript runs an order of magnitude past any fixed guess.
+_AVG_OUT_TOKENS = 150
+
+#: The one session kind classify spends on.
+_CLASSIFIED_KIND = "interactive"
+
+
+def _already_done(cache: ParquetCache) -> set[str]:
+    """Session ids already present in the cache (anti-join key)."""
+    done_df = cache.read_all(columns=["session_id"])
+    if done_df is not None and done_df.height > 0:
+        return set(done_df["session_id"].to_list())
+    return set()
+
+
+async def _classify_async(
+    settings: AnalyticsSettings,
+    *,
+    reader: CorpusReader,
+    provider: LlmStructuredProvider,
+    since_days: int | None,
+    limit: int | None,
+    cache: ParquetCache,
+    checkpoint: SqliteCheckpoint,
+    retry: SqliteRetryQueue,
+    budget: RunBudget | None,
+) -> int:
+    """Async implementation behind :func:`classify_sessions`."""
+    already = _already_done(cache)
+
+    # Checkpoint skip: compare current (last_ts, mtime) against the last run.
+    bounds = reader.session_bounds(since_days=since_days, limit=limit)
+    unchanged_pending, skipped = checkpointer.filter_unchanged(
+        ((sid, lt, mt) for sid, (lt, mt) in bounds.items()),
+        pipeline="classify",
+        checkpoint_db_path=checkpoint.db_path,
+    )
+    keep = set(unchanged_pending)
+
+    # Retry queue: pull pending retries first so they're re-admitted even
+    # when the checkpoint would otherwise skip them.
+    retry_ids = set(retry.drain(pipeline="classify"))
+    if retry_ids:
+        logger.info("classify: draining {} retry-queue entries", len(retry_ids))
+        keep |= retry_ids
+
+    # Retry queue is the SINGLE re-admission gate for failed units: a session
+    # with a live entry (attempts exhausted OR backoff not yet elapsed) is
+    # never checkpointed, so the checkpoint path would re-admit — and re-bill —
+    # it fresh on every run. Skip it here; drain re-admits when due.
+    blocked = retry.blocked_units(pipeline="classify")
+    if blocked & keep:
+        logger.info(
+            "classify: skipping {} sessions with live retry entries (backoff/attempts cap)",
+            len(blocked & keep),
+        )
+        keep -= blocked
+
+    # Session ceiling applied DURING the walk, not after: bounds is
+    # newest-first and the cap keeps the freshest sessions, so admitting
+    # past it only to slice back would render transcripts (up to 800K chars
+    # each) for sessions that can never run this tick. On a backlogged
+    # corpus that is the difference between 50 rendered strings and
+    # thousands held at once.
+    max_sessions = settings.llm_max_sessions_per_run
+    pending: list[tuple[str, str]] = []
+    empty_sids: list[str] = []
+    not_interactive: list[str] = []
+    deferred = 0
+    for sid in bounds:
+        if sid in already and sid not in retry_ids:
+            continue
+        if sid not in keep:
+            continue
+        if len(pending) >= max_sessions:
+            deferred += 1
+            continue
+        # Kind gate BEFORE rendering: a turn audit or a one-shot job is
+        # checkpointed at current bounds and never billed; growth re-admits.
+        if reader.session_kind(sid) != _CLASSIFIED_KIND:
+            not_interactive.append(sid)
+            continue
+        text = reader.session_text(sid)
+        if not text:
+            # A session that renders to nothing yields no row and no LLM
+            # call, so without a checkpoint it re-renders every tick
+            # forever. Stamp it at current bounds; growth re-admits it.
+            empty_sids.append(sid)
+            continue
+        pending.append((sid, text))
+
+    if empty_sids or not_interactive:
+        checkpoint.mark_completed(
+            pipeline="classify",
+            rows=[(sid, *bounds.get(sid, (None, None))) for sid in (*empty_sids, *not_interactive)],
+        )
+        logger.info(
+            "classify: checkpointed {} empty-transcript and {} non-interactive "
+            "(turn audit / one-shot job) sessions as skipped",
+            len(empty_sids),
+            len(not_interactive),
+        )
+
+    if deferred:
+        logger.warning(
+            "classify: capped at {} sessions (llm_max_sessions_per_run); {} deferred",
+            max_sessions,
+            deferred,
+        )
+
+    if not pending:
+        logger.info("classify: no pending sessions (skipped={} via checkpoint)", skipped)
+        return 0
+    if skipped:
+        logger.info("classify: skipped {} sessions via checkpoint", skipped)
+
+    chunk_size = write_chunk_size(settings.batch_size)
+    logger.info("classify: {} pending, chunks of {}", len(pending), chunk_size)
+
+    written = 0
+    i = 0
+    chunk_index = 0
+    total_chunks = (len(pending) + chunk_size - 1) // chunk_size
+    while i < len(pending):
+        chunk_index += 1
+        t0 = time.monotonic()
+        # Dispatch in budget-checked sub-batches. One gather over the whole
+        # write chunk would buy every remaining call before the ceiling was
+        # observable again: chunk_size is 384 by default against a session
+        # ceiling of 50, so the chunk loop alone checks exactly once, before
+        # any call. ``i`` advances by what was actually SENT, so a budget
+        # stop mid-chunk leaves the rest of the chunk unstamped rather than
+        # silently skipped.
+        chunk, results = await gather_under_budget(
+            pending[i : i + chunk_size],
+            make_coro=lambda unit: provider.classify_structured(
+                system=CLASSIFY_SYSTEM_PROMPT,
+                prompt=unit[1],
+                schema=SessionClassification,
+            ),
+            budget=budget,
+        )
+        elapsed = time.monotonic() - t0
+        if not chunk:
+            # Abort remaining work cleanly: unstarted sessions get no
+            # checkpoint/cache/retry stamp, so the next run picks them up.
+            logger.warning(
+                "classify: cost ceiling hit (${:.2f} >= ${:.2f}) — "
+                "aborting with {} sessions unstarted (nothing stamped)",
+                budget.spent_usd() if budget is not None else 0.0,
+                budget.max_cost_usd if budget is not None else 0.0,
+                len(pending) - i,
+            )
+            break
+        i += len(chunk)
+
+        now = datetime.now(UTC)
+        ok_rows: list[dict[str, Any]] = []
+        refused_sids: list[str] = []
+        errors = 0
+        for (sid, _), res in zip(chunk, results, strict=True):
+            if isinstance(res, BaseException):
+                from atif_models.domain.ports import RefusalError
+
+                if isinstance(res, RefusalError):
+                    # Terminal: write the DOCUMENTED refusal sentinel row
+                    # (work_category='unknown', goal='[refused]', confidence
+                    # 0.0) so refusal-skips are queryable, then checkpoint so
+                    # we never re-bill. The fake category sits at confidence
+                    # 0.0 and goal='[refused]' is the audit marker.
+                    # (conflicts, whose rows are uuid-keyed pairs, uses the
+                    # refusals sidecar instead.)
+                    logger.info("classify: {} refused (terminal) — sentinel row", sid)
+                    refused_sids.append(sid)
+                    ok_rows.append(
+                        {
+                            "session_id": sid,
+                            "work_category": "unknown",
+                            "goal": "[refused]",
+                            "confidence": 0.0,
+                            "classified_at": now,
+                        }
+                    )
+                    continue
+                errors += 1
+                logger.warning("classify: {} failed (queued for retry): {}", sid, res)
+                retry.enqueue(pipeline="classify", unit_id=sid, error=str(res))
+                continue
+            ok_rows.append(
+                {
+                    "session_id": sid,
+                    "work_category": res.work_category,
+                    "goal": res.goal,
+                    "confidence": float(res.confidence),
+                    "classified_at": now,
+                }
+            )
+
+        if ok_rows:
+            cache.write_part(pl.DataFrame(ok_rows, schema=_PARQUET_SCHEMA))
+
+        # Checkpoint at CURRENT bounds so a later rerun with no new steps is
+        # a no-op; refused sessions checkpoint too (terminal, via their
+        # sentinel rows already in ok_rows). Clear the completed sessions
+        # from the retry queue.
+        done_sids = [row["session_id"] for row in ok_rows]
+        if done_sids:
+            checkpoint.mark_completed(
+                pipeline="classify",
+                rows=[(sid, *bounds.get(sid, (None, None))) for sid in done_sids],
+            )
+            retry.mark_done(pipeline="classify", unit_ids=done_sids)
+
+        written += len(ok_rows)
+        logger.info(
+            "classify chunk {}/{}: {} ok, {} refused, {} errors, {:.1f}s",
+            chunk_index,
+            total_chunks,
+            len(ok_rows),
+            len(refused_sids),
+            errors,
+            elapsed,
+        )
+
+    logger.info("classify: wrote {} total rows", written)
+    return written
+
+
+def _dry_run_plan(
+    settings: AnalyticsSettings,
+    *,
+    reader: CorpusReader,
+    cache: ParquetCache,
+    spec: ModelSpec,
+    since_days: int | None,
+    limit: int | None,
+) -> dict[str, Any]:
+    """The classify ``--dry-run`` plan dict, with measured token counts.
+
+    Input tokens are MEASURED per pending session from the actual rendered
+    transcript (chars/4) instead of a static average, and the plan surfaces
+    the budget ceilings plus the capped session count — what WOULD run.
+    The kind gate applies here as in the real run: only interactive
+    sessions count toward the cap and the estimate.
+    """
+    already = _already_done(cache)
+    bounds = reader.session_bounds(since_days=since_days, limit=limit)
+    pending = [sid for sid in bounds if sid not in already]
+    max_sessions = settings.llm_max_sessions_per_run
+    capped: list[str] = []  # newest-first, same cap as the real run
+    skipped_kind = 0
+    for sid in pending:
+        if len(capped) >= max_sessions:
+            break
+        if reader.session_kind(sid) != _CLASSIFIED_KIND:
+            skipped_kind += 1
+            continue
+        capped.append(sid)
+    in_tokens = sum(tokens_for_chars(len(text)) for text in reader.session_texts(capped))
+    out_tokens = len(capped) * _AVG_OUT_TOKENS
+    pricing = (spec.pricing_in or 0.0, spec.pricing_out or 0.0)
+    cost = estimate_cost_tokens(in_tokens, out_tokens, pricing)
+    logger.info(
+        "classify --dry-run: {} sessions pending ({} would run under the cap, {} "
+        "skipped as turn audits or one-shot jobs). Estimated cost ~${:.2f} (model={})",
+        len(pending),
+        len(capped),
+        skipped_kind,
+        cost,
+        spec.model_id,
+    )
+    return {
+        "pipeline": "classify",
+        "candidates": len(pending),
+        "skipped_not_interactive": skipped_kind,
+        "capped_candidates": len(capped),
+        "llm_calls": len(capped),
+        "estimated_input_tokens": in_tokens,
+        "estimated_output_tokens": out_tokens,
+        "estimated_cost_usd": round(cost, 4),
+        "max_sessions_per_run": max_sessions,
+        "max_cost_usd_per_run": settings.llm_max_cost_usd_per_run,
+        "model": spec.model_id,
+        "since_days": since_days,
+        "limit": limit,
+        "dry_run": True,
+    }
+
+
+def classify_sessions(
+    settings: AnalyticsSettings,
+    *,
+    since_days: int | None = None,
+    limit: int | None = None,
+    dry_run: bool = True,
+    reader: CorpusReader | None = None,
+    provider: LlmStructuredProvider | None = None,
+    spec: ModelSpec | None = None,
+    cache: ParquetCache | None = None,
+    checkpoint: SqliteCheckpoint | None = None,
+    retry: SqliteRetryQueue | None = None,
+    budget: RunBudget | None = None,
+) -> int | dict[str, Any]:
+    """Classify pending sessions; return the row count (or a dry-run plan dict).
+
+    ``dry_run`` defaults to True (CONTRACT-V2 cost guard). The storage
+    ports and the reader default to the settings-derived adapters;
+    ``provider`` defaults to the registry-resolved OpenAI Bedrock adapter
+    (one instance per run, usage logged at the end). ``budget`` is the
+    cross-pipeline cost ceiling from ``run_analyze``; it is re-checked every
+    :data:`~atif_analytics.application.use_cases._shared.BUDGET_CHECK_BATCH`
+    sessions, and when it trips the remaining sessions are left unstamped.
+    Overshoot is bounded by the batch in flight at the crossing, not by the
+    session ceiling.
+    """
+    layout = settings.layout()
+    reader = (
+        reader
+        if reader is not None
+        else CorpusReader(settings.corpus_root, caps=settings.transcript_caps())
+    )
+    cache = cache if cache is not None else build_cache(layout.classifications_dir)
+
+    if provider is None or spec is None:
+        provider, spec = build_provider(settings, "classify")
+
+    if dry_run:
+        return _dry_run_plan(
+            settings, reader=reader, cache=cache, spec=spec, since_days=since_days, limit=limit
+        )
+
+    checkpoint = checkpoint if checkpoint is not None else build_checkpoint(layout.state_db_path)
+    retry = retry if retry is not None else build_retry_queue(layout.state_db_path)
+    if budget is not None:
+        budget.watch(provider, spec)
+    with pipeline_usage(provider, spec, "classify"):
+        return asyncio.run(
+            _classify_async(
+                settings,
+                reader=reader,
+                provider=provider,
+                since_days=since_days,
+                limit=limit,
+                cache=cache,
+                checkpoint=checkpoint,
+                retry=retry,
+                budget=budget,
+            )
+        )
+
+
+__all__ = ["classify_sessions"]