atif-sql 0.2.0__py3-none-any.whl

atif_analytics/domain/costs.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pure cost arithmetic for the LLM-analytics pipelines.
+
+:func:`estimate_cost_tokens` is the back-of-envelope dollar projection every
+``--dry-run`` path uses to price a pending batch of classification calls. It
+is pure arithmetic over token counts and a ``(input_rate, output_rate)``
+$/MTok tuple — no DuckDB, no Bedrock, no settings — so it belongs in the
+domain hexagon.
+
+Distinct from :func:`atif_models.domain.registry.estimate_cost`, which prices
+one ACCUMULATED usage total against a resolved ``ModelSpec``; this one prices
+a PLANNED batch before any call is made. The dry-run plan dicts use this; the
+post-run usage log uses the atif-models one.
+"""
+
+from __future__ import annotations
+
+#: The chars→tokens heuristic every measured dry-run estimate uses. Four
+#: chars per token is the standard English/code prior. Measuring the real
+#: rendered length matters more than the ratio: a fixed per-call "avg
+#: tokens" constant understates a real transcript by an order of magnitude.
+CHARS_PER_TOKEN: int = 4
+
+
+def tokens_for_chars(chars: int) -> int:
+    """Estimate the token count of ``chars`` characters (chars/4, floor 1 when non-empty)."""
+    if chars <= 0:
+        return 0
+    return max(1, chars // CHARS_PER_TOKEN)
+
+
+def estimate_cost_tokens(
+    input_tokens: int,
+    output_tokens: int,
+    pricing: tuple[float, float],
+) -> float:
+    """Dollar estimate for MEASURED token totals (the dry-run plan path).
+
+    ``pricing`` is ``(input_rate, output_rate)`` in $/MTok. Cost is
+    ``(in_tokens * in_rate + out_tokens * out_rate) / 1e6`` — a flat linear
+    projection with no minimums, tiers, or cache accounting. Totals are
+    summed per unit from real rendered prompt lengths, never from a static
+    per-call average.
+    """
+    in_rate, out_rate = pricing
+    return (input_tokens * in_rate + output_tokens * out_rate) / 1_000_000
+
+
+__all__ = ["CHARS_PER_TOKEN", "estimate_cost_tokens", "tokens_for_chars"]

atif_analytics/domain/friction.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pure regex fast-path for user-friction classification.
+
+The friction pipeline's regex fast-path is a pure function over a message
+string — stdlib ``re`` only, no DuckDB, no LLM, no settings — so it belongs
+in the domain layer. It catches the unambiguous friction shapes (status pings, hard
+interruption keywords, explicit corrections) so those never pay an LLM call;
+everything ambiguous falls through to the SQL-stamp layer and then the LLM
+(both of which live in ``application.use_cases.friction``).
+
+The label semantics are **frozen**: ``status_ping`` / ``interruption`` /
+``correction`` at a flat 0.9 confidence. Ambiguous phrasings deliberately fall
+through so a single mis-tuned pattern can't poison the corpus.
+"""
+
+from __future__ import annotations
+
+import re
+
+# ---------------------------------------------------------------------------
+# Regex fast-path
+# ---------------------------------------------------------------------------
+#
+# These patterns catch the unambiguous cases so we don't pay the LLM for them.
+# Everything ambiguous falls through to the LLM, which is where the
+# "screenshot?" / "tests?" class lives (those need semantic context to
+# distinguish from genuine topic questions like "can you write tests?").
+
+
+REGEX_BANK: tuple[tuple[str, re.Pattern[str]], ...] = (
+    # Status pings — only multi-word phrasings that unambiguously ask about
+    # progress.  Anything shorter or even slightly ambiguous ("status?",
+    # "what's the status column called?") falls through to the LLM so it
+    # can disambiguate via context.  The trailing-context guards below
+    # require a question mark, end-of-string, or a progress-related word
+    # to avoid matching "what's the status column called".
+    (
+        "status_ping",
+        re.compile(
+            r"""
+            \bhow(?:'s|\s+is|\s+are|\s+it)?\s+(?:it|we|things|progress)\s+
+                (?:going|coming|doing|looking|progressing|holding\s+up)\b
+            | \bhow'?s?\s+progress\b(?=\s*[?.!]?\s*$)
+            | \bany\s+update(?:s)?\b(?=\s*[?.!]?\s*$)
+            | \bstatus\s+update\b
+            | \bwhere\s+(?:are\s+we|we['’]re)\s+(?:at|with)\b
+            | \b(?:are\s+you\s+)?still\s+(?:working|going|running|on\s+it)\b
+            | \bwhat'?s?\s+(?:the|your)\s+eta\b
+            | \bhow\s+(?:much\s+)?long\s+(?:until|till|more|left)\b
+            """,
+            re.IGNORECASE | re.VERBOSE,
+        ),
+    ),
+    # Hard interruption keywords at the start of a message.
+    (
+        "interruption",
+        re.compile(
+            r"""
+            ^\s*
+            (?:
+                wait(?:\s*[.,!]|\s+a\s+(?:sec|second|moment|minute)|[\s$])
+              | stop(?:\s*[.,!]|\s+(?:right\s+)?there|[\s$])
+              | hold\s+on
+              | hold\s+up
+              | hang\s+on
+              | actually[,\s]
+              | before\s+you\s+(?:do|go)
+              | pause\b
+              | nvm\b
+              | never\s*mind\b
+            )
+            """,
+            re.IGNORECASE | re.VERBOSE,
+        ),
+    ),
+    # Explicit corrections.
+    (
+        "correction",
+        re.compile(
+            r"""
+            ^\s*
+            (?:
+                no[,\s.!]
+              | nope[,\s.!]?
+              | nah[,\s.!]?
+              | that'?s\s+(?:wrong|not\s+(?:right|it|what)|incorrect)
+              | not\s+(?:that|what\s+i)
+              | try\s+again
+              | wrong\b
+              | that'?s\s+not\s+
+            )
+            """,
+            re.IGNORECASE | re.VERBOSE,
+        ),
+    ),
+)
+
+
+def regex_fast_path(text: str) -> tuple[str, float] | None:
+    """Return ``(label, confidence)`` for a regex hit or ``None``.
+
+    Confidence is a flat 0.9 for regex hits -- these are hand-picked,
+    unambiguous phrasings.  Ambiguous shapes deliberately fall through to
+    the LLM so a single misclassification in the bank does not poison the
+    corpus.
+    """
+    if not text:
+        return None
+    probe = text[:512]
+    for label, pat in REGEX_BANK:
+        if pat.search(probe):
+            return label, 0.9
+    return None
+
+
+__all__ = ["REGEX_BANK", "regex_fast_path"]

atif_analytics/domain/layout.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""The analytics artifact layout under one corpus root, as a value object.
+
+CONTRACT-V2 §Ports & state fixes the storage shape: sharded parquet dirs
+under ``<corpus_root>/analytics/<name>/`` for the LLM pipelines and one
+sqlite WAL ``state.db`` per corpus. The trajectory dir and the structural
+single-file parquets (clusters, cluster_terms, session_communities,
+community_profile) were removed with their pipelines on 2026-09-27; an older
+corpus may still hold them, and nothing reads them.
+This module is the only place those paths are computed (the atif-corpus
+``CorpusLayout`` precedent) — atif-duck reads the same shape without
+importing us, and atif-cli threads ``corpus_root`` through.
+
+Pure path arithmetic; nothing here touches the filesystem.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+#: Sharded-cache directory names for the LLM pipelines. The names match
+#: the DuckDB view each backs.
+CLASSIFICATIONS_DIRNAME = "session_classifications"
+CONFLICTS_DIRNAME = "session_conflicts"
+USER_FRICTION_DIRNAME = "user_friction"
+PERCEIVED_ERRORS_DIRNAME = "perceived_errors"
+
+#: Refusal audit sidecar: a durable parquet record of a refusal-skip rather
+#: than a log line that ages out. Pipelines whose in-band schema can't hold a
+#: sentinel row (conflicts: rows are uuid-keyed PAIRS) append here instead:
+#: ``{pipeline, unit_id, reason, refused_at}``.
+#:
+#: The atif-duck catalog binds NO view over this directory, so it has no name
+#: in ``atif-sql schema`` and no name to SELECT from. A reader has to point
+#: ``read_parquet`` at the shard files under
+#: ``<corpus_root>/analytics/refusals/`` itself.
+REFUSALS_DIRNAME = "refusals"
+
+STATE_DB_FILENAME = "state.db"
+
+
+@dataclass(frozen=True, slots=True)
+class AnalyticsLayout:
+    """Computes every analytics artifact path under one ``corpus_root``."""
+
+    corpus_root: Path
+
+    @property
+    def analytics_dir(self) -> Path:
+        """``<corpus_root>/analytics/`` — parent of every artifact below."""
+        return self.corpus_root / "analytics"
+
+    @property
+    def classifications_dir(self) -> Path:
+        """Sharded cache for the classify pipeline."""
+        return self.analytics_dir / CLASSIFICATIONS_DIRNAME
+
+    @property
+    def conflicts_dir(self) -> Path:
+        """Sharded cache for the conflicts pipeline."""
+        return self.analytics_dir / CONFLICTS_DIRNAME
+
+    @property
+    def user_friction_dir(self) -> Path:
+        """Sharded cache for the friction pipeline."""
+        return self.analytics_dir / USER_FRICTION_DIRNAME
+
+    @property
+    def perceived_errors_dir(self) -> Path:
+        """Sharded cache for the perceived-error pipeline."""
+        return self.analytics_dir / PERCEIVED_ERRORS_DIRNAME
+
+    @property
+    def refusals_dir(self) -> Path:
+        """Sharded refusal-audit sidecar (see :data:`REFUSALS_DIRNAME`)."""
+        return self.analytics_dir / REFUSALS_DIRNAME
+
+    @property
+    def state_db_path(self) -> Path:
+        """The sqlite WAL checkpoint + retry-queue file (one per corpus)."""
+        return self.analytics_dir / STATE_DB_FILENAME
+
+
+__all__ = [
+    "CLASSIFICATIONS_DIRNAME",
+    "CONFLICTS_DIRNAME",
+    "PERCEIVED_ERRORS_DIRNAME",
+    "REFUSALS_DIRNAME",
+    "STATE_DB_FILENAME",
+    "USER_FRICTION_DIRNAME",
+    "AnalyticsLayout",
+]

atif_analytics/domain/models.py

@@ -0,0 +1,385 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pydantic v2 classification schemas (pure domain models).
+
+Enum value sets, field names, bounds, and descriptions are FROZEN by
+CONTRACT-V2 §Ports & state. The descriptions are part of the prompt surface
+— the strict-schema transform in atif-models ships them to the model — so
+editing one here changes classifier behavior, and changing an enum value
+breaks the analytics views bound to it.
+
+The OpenAI strict-mode wire transform lives in
+:mod:`atif_models.domain.schema`; these models stay pure pydantic.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SessionClassification(BaseModel):
+    """Classify an entire Claude Code session: what kind of work, toward what goal.
+
+    One row per session, written to the ``session_classifications`` parquet
+    cache. Used to build the ``session_classifications`` DuckDB view.
+
+    ``autonomy_tier`` and ``success`` were removed on 2026-09-27: neither was
+    reproducible, and what a session achieved is now computed from its steps
+    (atif-duck's ``session_outcomes``).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    work_category: Literal[
+        "sde",
+        "admin",
+        "strategy_business",
+        "events",
+        "thought_leadership",
+        "other",
+    ] = Field(
+        ...,
+        description=(
+            "Dominant activity.  "
+            "'sde': software engineering, debugging, code review, tests, CI. "
+            "'admin': expense reports, scheduling, low-signal email triage, routine ops. "
+            "'strategy_business': business analysis, competitive research, strategic memos, "
+            "proposals. "
+            "'events': event planning/logistics, speaker prep, agenda building. "
+            "'thought_leadership': writing for external audiences (blog posts, conference "
+            "abstracts, LinkedIn). "
+            "'other': use only when nothing else fits."
+        ),
+    )
+    goal: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description=(
+            "ONE sentence summarizing the user's goal, inferred from the opening user "
+            "messages and overall arc.  Present tense, <= 280 chars.  Example: "
+            '"Refactor the auth middleware to use the new token rotator."'
+        ),
+    )
+    confidence: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Classifier self-assessed confidence 0.0-1.0. Use <0.5 for genuinely "
+            "ambiguous sessions."
+        ),
+    )
+
+
+class ConflictPair(BaseModel):
+    """A single stance-conflict pair, keyed on the two opposing turn UUIDs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    turn_a_uuid: str = Field(
+        ...,
+        min_length=1,
+        max_length=64,
+        description=(
+            "UUID of the first turn that holds stance A.  Pull from the "
+            "``[uuid=...]`` headers in the bound transcript -- copy verbatim, "
+            "do NOT invent or paraphrase.  Together with ``turn_b_uuid`` this "
+            "is the natural key of a conflict row."
+        ),
+    )
+    turn_b_uuid: str = Field(
+        ...,
+        min_length=1,
+        max_length=64,
+        description=(
+            "UUID of the second turn that holds the opposing stance.  Same "
+            "rules as ``turn_a_uuid`` -- copy verbatim from the transcript "
+            "headers.  Must differ from ``turn_a_uuid``."
+        ),
+    )
+    conflict_kind: Literal["disagreement", "correction", "reversal", "impasse"] = Field(
+        ...,
+        description=(
+            "Shape of the conflict.  "
+            "'disagreement': two parties hold opposing positions and discuss them. "
+            "'correction': one party explicitly tells the other their answer/action "
+            "was wrong (e.g. 'no, not that, do X instead'). "
+            "'reversal': the same party flips their own earlier position "
+            "('actually let's NOT do X'). "
+            "'impasse': both sides restate their positions without converging "
+            "and the topic stalls."
+        ),
+    )
+    severity: Literal["low", "medium", "high"] = Field(
+        ...,
+        description=(
+            "How consequential the conflict is for the session outcome.  "
+            "'low': a minor course nudge with little downstream impact. "
+            "'medium': changes the implementation approach or scope but stays "
+            "inside the original goal. "
+            "'high': blocks progress, reverses a major decision, or "
+            "fundamentally changes the goal."
+        ),
+    )
+    agent_position: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description=(
+            "One-sentence summary of the agent's stance in this conflict, "
+            "phrased in the agent's own framing.  Strip pleasantries; keep "
+            "the substantive claim."
+        ),
+    )
+    user_position: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description=(
+            "One-sentence summary of the user's stance, phrased the way the "
+            "user phrased it.  Same length budget as ``agent_position``."
+        ),
+    )
+    confidence: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Classifier self-confidence 0.0-1.0 that this is a real, "
+            "substantive conflict (not deliberation, not collaboration, not "
+            "an accepted-risk caveat).  Use <0.5 for borderline cases."
+        ),
+    )
+
+
+class ConflictsResult(BaseModel):
+    """The model's response: zero or more conflict pairs.
+
+    An empty list is valid and common.  When the model returns an empty
+    list the pipeline writes ZERO rows for that session — sessions with no
+    conflicts simply don't appear in ``session_conflicts`` (or in the
+    derived ``conflicts_summary`` view).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    conflicts: list[ConflictPair] = Field(
+        default_factory=list,
+        description=(
+            "Zero or more stance-conflict pairs.  Each entry names the two "
+            "turn UUIDs whose stances clash, the kind/severity, both party "
+            "positions, and a confidence score.  Report only substantive "
+            "technical or strategic conflicts -- skip trivial style "
+            "disagreements."
+        ),
+    )
+
+
+class UserFrictionSignal(BaseModel):
+    """Classify a single short user message for friction signals.
+
+    A "friction signal" is anything in the user's utterance that implies the
+    agent's last turn fell short of expectations: an impatient status ping,
+    a one-word question pointing at a missed artifact (``screenshot?``,
+    ``tests?``), confusion about what happened, a hard interruption, a
+    correction, or open frustration.
+
+    Applied only to user-role messages below the friction char cutoff
+    (default 300).  Long user messages are almost always genuine task turns
+    rather than interrupt/confusion signals — the filter keeps LLM cost
+    linear in the interesting slice.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    label: Literal[
+        "status_ping",
+        "unmet_expectation",
+        "confusion",
+        "interruption",
+        "correction",
+        "frustration",
+        "none",
+    ] = Field(
+        ...,
+        description=(
+            "Dominant friction category for this single user message.  "
+            "'status_ping': the user asks about progress/ETA ('how's it going?', "
+            "'any update?', 'status?', 'where are we?'). "
+            "'unmet_expectation': a one- or two-word question that points at "
+            "something the agent should have done proactively but didn't "
+            "('screenshot?', 'tests?', 'link?', 'diff?'). "
+            "'confusion': the user signals they don't understand the output or "
+            "state ('what does that mean?', 'why did you do X?', 'I don't get it'). "
+            "'interruption': the user cuts the agent off or redirects mid-task "
+            "('wait', 'stop', 'hold on', 'actually...', 'before you do that'). "
+            "'correction': the user tells the agent its last action/answer was "
+            "wrong ('no, not that', 'that's wrong', 'nope', 'try again'). "
+            "'frustration': terse annoyance or sarcasm ('ugh', 'seriously?', "
+            "'are you kidding', 'really?'). "
+            "'none': ordinary task turn with no friction signal -- a substantive "
+            "instruction, a plain question, an acknowledgement. USE THIS FOR "
+            "THE MAJORITY OF MESSAGES."
+        ),
+    )
+    rationale: str = Field(
+        ...,
+        min_length=1,
+        max_length=200,
+        description=(
+            "One short sentence (<=200 chars) naming the specific phrase or "
+            "structural cue that triggered the label.  Use an empty-ish "
+            "placeholder like 'ordinary instruction' when label='none'."
+        ),
+    )
+    confidence: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Classifier self-confidence 0.0-1.0.  Use <0.5 when the message is "
+            "genuinely ambiguous between 'none' and a friction label."
+        ),
+    )
+
+
+class PerceivedError(BaseModel):
+    """One user-perceived agent error, keyed on the USER turn where it surfaces.
+
+    Implements LangSmith's published "Perceived Error" definition —
+    conversations where the agent "made a mistake, misunderstood a request,
+    or took the interaction in the wrong direction", judged from
+    USER-VISIBLE evidence only, never objective correctness. Explicit
+    signals (correction / repeated_request / rejected_action) come from the
+    user's own words; inferred signals (contradictory_response /
+    acknowledged_mistake / persistent_misunderstanding / unresolved_outcome)
+    come from the conversation shape.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    turn_uuid: str = Field(
+        ...,
+        min_length=1,
+        max_length=64,
+        description=(
+            "UUID of the USER turn where the perception of error surfaces "
+            "(the correction, the repeat, the rejection, or the user-visible "
+            "cue an inferred signal rests on).  Pull from the ``[uuid=...]`` "
+            "headers in the bound transcript -- copy verbatim, do NOT invent "
+            "or paraphrase.  For inferred signals with no single user cue "
+            "turn, use the user turn closest AFTER the agent's error."
+        ),
+    )
+    signal: Literal[
+        "correction",
+        "repeated_request",
+        "rejected_action",
+        "contradictory_response",
+        "acknowledged_mistake",
+        "persistent_misunderstanding",
+        "unresolved_outcome",
+    ] = Field(
+        ...,
+        description=(
+            "The evidence category.  EXPLICIT (the user says so): "
+            "'correction': the user tells the agent its answer/action was "
+            "wrong or restates what they actually meant. "
+            "'repeated_request': the user asks for the same thing again "
+            "because the first response missed it. "
+            "'rejected_action': the user declines, reverts, or interrupts "
+            "an action the agent took or proposed. "
+            "INFERRED (the conversation shows it): "
+            "'contradictory_response': the agent contradicts its own "
+            "earlier statement and the user is exposed to both. "
+            "'acknowledged_mistake': the agent itself admits an error "
+            "('you're right, I misread...') in front of the user. "
+            "'persistent_misunderstanding': the agent keeps answering a "
+            "different question than the one the user is asking across "
+            "multiple turns. "
+            "'unresolved_outcome': the session ends with the user's problem "
+            "visibly unsolved after the agent's attempts."
+        ),
+    )
+    severity: Literal["minor", "moderate", "major"] = Field(
+        ...,
+        description=(
+            "How much the perceived error cost the user.  "
+            "'minor': a one-turn nudge; the user corrected and work resumed "
+            "immediately (the common case in coding sessions). "
+            "'moderate': the error cost visible rework, repeated exchanges, "
+            "or an undone/redone action. "
+            "'major': the error derailed the session -- wrong direction "
+            "sustained across many turns, destructive action rejected too "
+            "late, or the user gave up."
+        ),
+    )
+    evidence: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description=(
+            "The user's own words that show the perception -- a short "
+            "verbatim quote or close paraphrase of the user turn(s), "
+            "<= 280 chars.  For inferred signals, quote the user-visible "
+            "text the inference rests on (e.g. the agent's own admission)."
+        ),
+    )
+    agent_error_summary: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description=(
+            "One sentence describing what the agent got wrong FROM THE "
+            "USER'S PERSPECTIVE, <= 280 chars.  Example: 'The agent renamed "
+            "the CLI flag the user had asked to keep.'  Describe the "
+            "perceived mistake, not whether it was objectively wrong."
+        ),
+    )
+    confidence: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Classifier self-confidence 0.0-1.0 that the USER perceived "
+            "an error (not that an error objectively occurred).  Use <0.5 "
+            "when the cue could equally be the user changing their mind or "
+            "ordinary iterative steering."
+        ),
+    )
+
+
+class PerceivedErrorsResult(BaseModel):
+    """The model's response: zero or more perceived errors for one session.
+
+    An empty list is valid and common — it means a CLEAN session (the user
+    never perceived an error).  The pipeline writes ZERO rows for that
+    session; the session is checkpointed so it never re-bills.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    errors: list[PerceivedError] = Field(
+        default_factory=list,
+        description=(
+            "Zero or more user-perceived agent errors.  Each entry names "
+            "the user turn where perception surfaces, the evidence "
+            "category, severity, the user's words, a one-sentence summary "
+            "of the perceived mistake, and a confidence score.  Report "
+            "only errors the USER visibly perceived -- an empty array is "
+            "the correct answer for a clean session."
+        ),
+    )
+
+
+__all__ = [
+    "ConflictPair",
+    "ConflictsResult",
+    "PerceivedError",
+    "PerceivedErrorsResult",
+    "SessionClassification",
+    "UserFrictionSignal",
+]