claude-sql 0.4.0__py3-none-any.whl

claude_sql/schemas.py

@@ -0,0 +1,454 @@
+"""Pydantic v2 classification schemas wired for Bedrock output_config.format.
+
+Each model exposes a ``SCHEMA_DICT`` module constant -- the ``model_json_schema()``
+output flattened (no ``$ref``/``$defs``) and with ``additionalProperties: false``
+injected at every object level, so it passes Bedrock's JSON Schema Draft 2020-12
+subset validator.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def _bedrock_schema(model: type[BaseModel]) -> dict:
+    """Turn a pydantic v2 BaseModel into a Bedrock-compatible JSON Schema.
+
+    Bedrock's structured output only accepts JSON Schema Draft 2020-12 SUBSET.
+    Pydantic's default ``model_json_schema()`` emits ``$ref``/``$defs`` for
+    nested models; Bedrock 400s on those.  We inline refs and inject
+    ``additionalProperties: false`` at every object level.
+
+    Parameters
+    ----------
+    model : type[BaseModel]
+        The pydantic model class to convert.
+
+    Returns
+    -------
+    dict
+        Flattened JSON Schema dict safe to pass to Bedrock's
+        ``output_config.format.schema`` field.
+    """
+    raw = model.model_json_schema()
+    return _flatten(raw)
+
+
+def _flatten(schema: dict, defs: dict | None = None) -> dict:
+    """Recursively inline $ref references and add additionalProperties: false.
+
+    Uses ``$defs`` from the root schema as the lookup table for inlining.
+    Walks every nested object/array and removes ``$defs``/``$ref`` keys.
+
+    Parameters
+    ----------
+    schema : dict
+        A (sub)schema dict produced by pydantic's ``model_json_schema``.
+    defs : dict | None
+        The ``$defs`` lookup table from the root schema.  Populated from
+        ``schema`` on the first call.
+
+    Returns
+    -------
+    dict
+        The flattened schema with refs inlined and object-typed nodes
+        forced to ``additionalProperties: false``.
+    """
+    if defs is None:
+        defs = schema.get("$defs") or schema.get("definitions") or {}
+    out: dict = {}
+    for k, v in schema.items():
+        if k in ("$defs", "definitions"):
+            continue
+        if k == "$ref":
+            # e.g. "#/$defs/Conflict"
+            name = v.rsplit("/", 1)[-1]
+            target = defs.get(name, {})
+            return _flatten(target, defs)  # replace the whole object
+        if isinstance(v, dict):
+            out[k] = _flatten(v, defs)
+        elif isinstance(v, list):
+            out[k] = [_flatten(i, defs) if isinstance(i, dict) else i for i in v]
+        else:
+            out[k] = v
+    # Ensure object-typed schemas reject unknown fields.
+    if out.get("type") == "object" and "additionalProperties" not in out:
+        out["additionalProperties"] = False
+    # Bedrock's JSON Schema subset rejects numeric range constraints on
+    # number/integer types; strip them.  Pydantic still enforces them at
+    # response-parse time, so we keep the ge/le annotations in the models.
+    if out.get("type") in ("number", "integer"):
+        for banned in ("minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf"):
+            out.pop(banned, None)
+    # String length constraints are also rejected by Bedrock's subset.
+    if out.get("type") == "string":
+        for banned in ("minLength", "maxLength", "pattern", "format"):
+            out.pop(banned, None)
+    # Array item/length constraints.
+    if out.get("type") == "array":
+        for banned in ("minItems", "maxItems", "uniqueItems"):
+            out.pop(banned, None)
+    # Title keys just add noise; Bedrock accepts them but they clutter the
+    # schema for the model's pattern-matching.  Keep descriptions, drop titles.
+    out.pop("title", None)
+    return out
+
+
+class SessionClassification(BaseModel):
+    """Classify an entire Claude Code session.
+
+    One row per session, written to ``session_classifications.parquet``.
+    Used to build the ``session_classifications`` DuckDB view.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    autonomy_tier: Literal["manual", "assisted", "autonomous"] = Field(
+        ...,
+        description=(
+            "How much the agent drove the work.  "
+            "'manual': the user typed every instruction and confirmed each step. "
+            "'assisted': the agent took initiative but the user course-corrected often. "
+            "'autonomous': the agent ran multi-step work end-to-end with minimal user "
+            "intervention -- tier-3 work."
+        ),
+    )
+    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."
+        ),
+    )
+    success: Literal["success", "partial", "failure", "unknown"] = Field(
+        ...,
+        description=(
+            "Did the session complete its stated goal? "
+            "'success': the user's goal was clearly met. "
+            "'partial': the goal was reached with caveats or leftover TODOs. "
+            "'failure': the session ended without achieving the goal. "
+            "'unknown': insufficient signal to judge."
+        ),
+    )
+    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."
+        ),
+    )
+
+
+SESSION_CLASSIFICATION_SCHEMA: dict = _bedrock_schema(SessionClassification)
+
+
+class MessageTrajectory(BaseModel):
+    """Per-message sentiment + transition-filler flag.
+
+    Applied only to messages that pass the cheap regex heuristic pre-filter.
+    Classification is on the message's standalone polarity — the model
+    sees just this one message, with no surrounding turns. The legacy
+    field name ``sentiment_delta`` is preserved for parquet compatibility,
+    but the semantics are absolute polarity, not "delta vs prior".
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    sentiment_delta: Literal["positive", "neutral", "negative"] = Field(
+        ...,
+        description=(
+            "Standalone emotional polarity of this single message — judged "
+            "from the message text alone, no surrounding context.  "
+            "'positive': excitement, approval, momentum, explicit thanks. "
+            "'neutral': factual, procedural, no affect (this is the "
+            "majority class for a coding session — use it aggressively). "
+            "'negative': frustration, pushback, blocked, explicit "
+            "correction. "
+            "When the cue is mild or ambiguous, prefer 'neutral'."
+        ),
+    )
+    is_transition: bool = Field(
+        ...,
+        description=(
+            "True if this message is pure transition/filler (e.g. 'Ok now let me check that', "
+            "'Running the tests', 'Clean.').  Use True for acknowledgement-only messages that "
+            "don't carry substantive content."
+        ),
+    )
+    confidence: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Classifier self-confidence 0.0-1.0.",
+    )
+
+
+MESSAGE_TRAJECTORY_SCHEMA: dict = _bedrock_schema(MessageTrajectory)
+
+
+class Conflict(BaseModel):
+    """A single stance conflict within a session."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    stance_a: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description="One-sentence summary of the first stance.",
+    )
+    stance_b: str = Field(
+        ...,
+        min_length=1,
+        max_length=280,
+        description="One-sentence summary of the conflicting stance.",
+    )
+    resolution: Literal["resolved", "unresolved", "abandoned"] = Field(
+        ...,
+        description=(
+            "How the conflict ended.  "
+            "'resolved': the session converged on one stance. "
+            "'unresolved': both stances were still live at end of session. "
+            "'abandoned': the topic was dropped without resolution."
+        ),
+    )
+
+
+class SessionConflicts(BaseModel):
+    """All stance conflicts detected in a session.  Empty list if none found."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    conflicts: list[Conflict] = Field(
+        default_factory=list,
+        description=(
+            "Zero or more stance conflicts.  A conflict is a pair of mutually-exclusive "
+            "positions on the same question that surface during the session.  Report "
+            "only substantive technical or strategic conflicts -- skip trivial style "
+            "disagreements."
+        ),
+    )
+
+
+SESSION_CONFLICTS_SCHEMA: dict = _bedrock_schema(SessionConflicts)
+
+
+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
+    :class:`Settings.friction_max_chars` (default 300).  Long user messages
+    are almost always genuine task turns rather than interrupt/confusion
+    signals -- the filter keeps Bedrock 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."
+        ),
+    )
+
+
+USER_FRICTION_SCHEMA: dict = _bedrock_schema(UserFrictionSignal)
+
+
+class Correction(BaseModel):
+    """One spot in the bound transcript where the human redirected the agent.
+
+    A correction is a substantive course change: the agent did one thing,
+    the human said "no, do this instead" (or equivalent), and the agent
+    pivoted. Style nits and acknowledgements don't qualify -- the
+    downstream PR review sheet uses these to surface where the agent
+    went off-rails, not where the human polished a phrase.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    what_agent_did: str = Field(
+        ...,
+        min_length=5,
+        max_length=300,
+        description=(
+            "The agent's action that was corrected, in one short clause. "
+            'Example: "Started rewriting the auth middleware from scratch."'
+        ),
+    )
+    correction: str = Field(
+        ...,
+        min_length=5,
+        max_length=300,
+        description=(
+            "What the human said to redirect, paraphrased to one short clause. "
+            'Example: "Asked to keep the existing middleware and only update the token rotator."'
+        ),
+    )
+
+
+class PRReviewSheet(BaseModel):
+    """Compressed PR review derived from the bound transcript.
+
+    Six-field schema designed to fit a 1K-token review-sheet budget when
+    rendered as Markdown. Field descriptions carry the synthesis rules so
+    downstream prompts only need to frame the task; the model's job is to
+    populate the schema from the bound JSONL transcript.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    human_intent: str = Field(
+        ...,
+        min_length=10,
+        max_length=600,
+        description=(
+            "What the human asked for in 1-3 sentences. Synthesized from the "
+            "initial user-role messages and any explicit goal restatements. "
+            "Present tense, paraphrased, not a literal quote."
+        ),
+    )
+    agent_exploration: list[str] = Field(
+        ...,
+        min_length=1,
+        max_length=8,
+        description=(
+            "Concrete subjects the agent explored, as 3-8 short bullets. "
+            "Each bullet is a noun phrase or short clause naming what was "
+            "investigated. Drawn from tool calls, search queries, and file "
+            "reads -- not from the agent's own narration."
+        ),
+    )
+    corrections: list[Correction] = Field(
+        ...,
+        max_length=5,
+        description=(
+            "Where the agent got corrected by the human, redirected, or ran "
+            "into stance conflicts. Up to 5 entries; empty list if none. "
+            "Skip surface-level acknowledgements; only substantive redirects."
+        ),
+    )
+    tools_used: list[str] = Field(
+        ...,
+        max_length=20,
+        description=(
+            "Tool names the agent successfully invoked (canonical names: "
+            "Read, Edit, Write, Bash, Grep, Glob, etc.). Deduplicated, "
+            "ordered by first use."
+        ),
+    )
+    tools_refused: list[str] = Field(
+        ...,
+        max_length=10,
+        description=(
+            "Tool calls the agent declined or that were blocked by hooks / "
+            "permissions. Empty list if none. Format each entry as "
+            "'ToolName: brief reason' (e.g. 'Bash: blocked by allowlist')."
+        ),
+    )
+    diff_rationale: str = Field(
+        ...,
+        min_length=20,
+        max_length=800,
+        description=(
+            "The 'why' behind the merged diff in 2-4 sentences. Names the "
+            "specific files or modules touched and the user-facing change. "
+            "Avoids restating the diff line-by-line; focus on the rationale."
+        ),
+    )
+
+
+PR_REVIEW_SHEET_SCHEMA: dict = _bedrock_schema(PRReviewSheet)
+
+
+__all__ = [
+    "MESSAGE_TRAJECTORY_SCHEMA",
+    "PR_REVIEW_SHEET_SCHEMA",
+    "SESSION_CLASSIFICATION_SCHEMA",
+    "SESSION_CONFLICTS_SCHEMA",
+    "USER_FRICTION_SCHEMA",
+    "Conflict",
+    "Correction",
+    "MessageTrajectory",
+    "PRReviewSheet",
+    "SessionClassification",
+    "SessionConflicts",
+    "UserFrictionSignal",
+]