atif-sql 0.2.0__py3-none-any.whl

atif_duck/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""atif-duck: DuckDB views over the materialized ATIF corpus.
+
+Layered: ``infrastructure`` (DuckDB registry) > ``domain`` (static
+view/macro catalog). ``register(con, corpus_root)`` wires a connection to a
+CONTRACT-shaped corpus (``<root>/sessions/<id>/{trajectory.json,
+edges.jsonl, loss_report.json, meta.json}``) and exposes the core query
+surface: the views in :data:`VIEW_NAMES` (sessions / steps / messages /
+tool_calls / user_steps / human_turns / session_outcomes / ...) plus the
+macros in :data:`MACRO_NAMES`. The v2
+analytics surface (``ANALYTICS_VIEW_NAMES``,
+``ANALYTICS_MACRO_SIGNATURES``) registers separately and needs
+``atif-sql analyze`` to have run.
+"""
+
+from atif_duck.domain.catalog import (
+    DEFAULT_PRICING,
+    MACRO_NAMES,
+    MACRO_SIGNATURES,
+    VIEW_NAMES,
+    VIEW_SCHEMA,
+)
+from atif_duck.infrastructure.registry import (
+    RawSources,
+    register,
+    register_macros,
+    register_raw,
+    register_views,
+)
+
+__all__ = [
+    "DEFAULT_PRICING",
+    "MACRO_NAMES",
+    "MACRO_SIGNATURES",
+    "VIEW_NAMES",
+    "VIEW_SCHEMA",
+    "RawSources",
+    "register",
+    "register_macros",
+    "register_raw",
+    "register_views",
+]

atif_duck/domain/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Domain layer: the static view/macro catalog for atif-duck.
+
+Pure value objects — no duckdb import, no I/O. The catalog is the
+agent-facing contract (`atif-sql schema` answers from here in <50ms with
+zero DuckDB bind cost); drift against the actual DDL is caught by the
+tests in ``tests/test_duck_views.py``.
+"""
+
+from atif_duck.domain.catalog import (
+    DEFAULT_PRICING,
+    DESCRIPTIONS,
+    MACRO_NAMES,
+    MACRO_SIGNATURES,
+    TABLE_MACRO_NAMES,
+    VIEW_NAMES,
+    VIEW_SCHEMA,
+)
+from atif_duck.domain.examples import ExampleQuery, build_examples
+
+__all__ = [
+    "DEFAULT_PRICING",
+    "DESCRIPTIONS",
+    "MACRO_NAMES",
+    "MACRO_SIGNATURES",
+    "TABLE_MACRO_NAMES",
+    "VIEW_NAMES",
+    "VIEW_SCHEMA",
+    "ExampleQuery",
+    "build_examples",
+]

atif_duck/domain/artifacts.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""How the per-session JSON artifacts are stored: their names and their compression.
+
+Three of the artifacts a session directory holds are the bulk of a corpus's
+bytes: ``trajectory.json`` (the ATIF document), ``edges.jsonl`` and
+``session_events.jsonl``. materialize stores each of them zstd-compressed,
+as ``<name>.zst``, and a corpus written before that keeps the plain file until
+``atif-sql corpus slim`` compresses it. Either spelling holds the same bytes
+once decompressed, so every reader resolves the stored file per session
+(:func:`stored_names`, the compressed one first) and nothing else about it
+changes. ``meta.json`` and ``loss_report.json`` stay plain: they're small, and
+``meta.json`` is what the corpus writer and every reader check first.
+
+A path a view reports (``sessions.trajectory_path``) names the logical
+artifact, ``<session>/trajectory.json``, whichever spelling is on disk, so a
+row reads the same before and after a corpus is slimmed.
+
+atif-corpus writes these names and carries the twin constants; the cross-package
+pin lives in atif-cli's tests, the one package that may import both.
+
+Pure constants: no filesystem access.
+"""
+
+from __future__ import annotations
+
+#: The ATIF document.
+TRAJECTORY_JSON: str = "trajectory.json"
+#: One line per raw transcript record.
+EDGES_JSONL: str = "edges.jsonl"
+#: One line per kept non-message record.
+SESSION_EVENTS_JSONL: str = "session_events.jsonl"
+#: The completion marker every reader gates on (always plain).
+META_JSON: str = "meta.json"
+#: The fidelity report (always plain).
+LOSS_REPORT_JSON: str = "loss_report.json"
+
+#: The suffix a compressed artifact carries after its logical name.
+COMPRESSED_SUFFIX: str = ".zst"
+
+#: The artifacts materialize stores compressed.
+COMPRESSED_ARTIFACTS: tuple[str, ...] = (TRAJECTORY_JSON, EDGES_JSONL, SESSION_EVENTS_JSONL)
+
+
+def stored_names(name: str) -> tuple[str, ...]:
+    """The file names ``name`` may be stored under, in the order a reader tries them.
+
+    The compressed spelling comes first: a session caught between ``corpus
+    slim`` writing ``<name>.zst`` and removing ``<name>`` holds both, with the
+    same content, and either answer is right.
+    """
+    if name in COMPRESSED_ARTIFACTS:
+        return (f"{name}{COMPRESSED_SUFFIX}", name)
+    return (name,)
+
+
+__all__ = [
+    "COMPRESSED_ARTIFACTS",
+    "COMPRESSED_SUFFIX",
+    "EDGES_JSONL",
+    "LOSS_REPORT_JSON",
+    "META_JSON",
+    "SESSION_EVENTS_JSONL",
+    "TRAJECTORY_JSON",
+    "stored_names",
+]

atif_duck/domain/authorship.py

@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Who wrote a user-role step: the ``author`` rule table and its SQL form.
+
+Claude Code and Codex deliver a lot of machine-written text in the USER role:
+Stop hook feedback, ``<task-notification>`` blocks, retry and continuation
+nudges, skill bodies, slash-command wrappers, image metadata from a screenshot
+the agent read, and the prompts of automated review sessions. Counted as
+user turns they drown the human ones (on a busy agent corpus about half of
+the main-chain user steps were machine-written), so every analytics reader
+classifies a user step first and treats only ``human`` as the user
+speaking.
+
+The classification is a PREFIX match over the message with leading
+whitespace stripped, first rule wins, in :data:`AUTHOR_PREFIX_RULES` order.
+Prefixes only, so the SQL macro (``starts_with``) and the Python twin
+(``str.startswith``) cannot disagree on a regex dialect. An empty message is
+``harness``: nothing a human typed. One rule sits outside the text: a step the
+converter flagged ``is_compact_summary`` is ``harness`` whatever it says
+(``user_steps.author`` and the Python twin both apply it; the bare
+``step_author`` macro sees only source and text).
+
+This table is the ONE definition. atif-analytics may not import atif-duck
+(independence contract), so ``atif_analytics.domain.authorship`` carries a
+twin of the two tuples below, and ``tests/test_authorship_twin_pin.py`` reads
+that twin as source text and fails on any difference (the ``session_id``
+precedent).
+
+Pure domain module: stdlib only, no duckdb.
+"""
+
+from __future__ import annotations
+
+from atif_duck.domain.sql_literal import SqlFragment, sql_literal
+
+#: The author labels, in the order the docs list them.
+AUTHOR_VALUES: tuple[str, ...] = (
+    "human",
+    "stop_hook",
+    "task_notification",
+    "harness",
+    "audit_prompt",
+)
+
+#: Characters stripped from the left of a message before matching.
+AUTHOR_STRIP_CHARS: str = " \t\r\n"
+
+#: ``(author, prefix)``, first match wins. Every prefix was read off real
+#: Claude Code and Codex corpora in September 2026 as a most-common opening of
+#: user-role steps; the comment beside each says what writes it.
+AUTHOR_PREFIX_RULES: tuple[tuple[str, str], ...] = (
+    # An automated review session: a hook that audits another agent's turn
+    # opens a fresh session whose whole content is its prompt and a verdict.
+    ("audit_prompt", "You are auditing an agent turn"),
+    # Claude Code Stop / SubagentStop hooks that blocked the agent's stop.
+    ("stop_hook", "Stop hook feedback"),
+    ("stop_hook", "SubagentStop hook feedback"),
+    # Background task completion notices.
+    ("task_notification", "<task-notification>"),
+    ("task_notification", "[SYSTEM NOTIFICATION"),
+    # Claude Code bookkeeping: interrupts, continuation and retry nudges,
+    # compaction summaries, skill bodies, image metadata for a screenshot the
+    # agent read, workflow-computed tasks, reminders and hook output.
+    ("harness", "[Request interrupted"),
+    ("harness", "Continue from where you left off"),
+    ("harness", "Your previous attempt hit a transient"),
+    ("harness", "This session is being continued from a previous conversation"),
+    ("harness", "Base directory for this skill:"),
+    ("harness", "[Image: original "),
+    ("harness", '{"type": "image"'),
+    ("harness", "[Workflow harness"),
+    ("harness", "[structured-output-enforce]"),
+    ("harness", "<system-reminder>"),
+    ("harness", "<user-prompt-submit-hook>"),
+    ("harness", "UserPromptSubmit operation blocked by hook"),
+    ("harness", "<fork-boilerplate>"),
+    ("harness", "Another Claude session sent a message"),
+    ("harness", "The coordinator sent a message"),
+    # Slash-command and local-shell wrappers.
+    ("harness", "<command-name>"),
+    ("harness", "<command-message>"),
+    ("harness", "<command-args>"),
+    ("harness", "<local-command-stdout>"),
+    ("harness", "<local-command-stderr>"),
+    ("harness", "<local-command-caveat>"),
+    ("harness", "Caveat: The messages below were generated"),
+    ("harness", "<bash-input>"),
+    ("harness", "<bash-stdout>"),
+    ("harness", "<bash-stderr>"),
+    # Codex CLI context injections.
+    ("harness", "<environment_context>"),
+    ("harness", "<codex_internal_context"),
+    ("harness", "<user_instructions>"),
+    ("harness", "# AGENTS.md instructions"),
+    ("harness", "<turn_aborted>"),
+    ("harness", "The following is the Codex agent history"),
+)
+
+#: Prefixes that mark an interrupted turn (``session_outcomes.interrupts``).
+#: Both are also ``harness`` rules above, so an interrupt never counts as a
+#: human turn.
+INTERRUPT_PREFIXES: tuple[str, ...] = ("[Request interrupted", "<turn_aborted>")
+
+
+#: ``ltrim`` argument naming :data:`AUTHOR_STRIP_CHARS` by code point (space,
+#: tab, CR, LF); ``test_authorship.py`` pins the two against each other.
+_STRIP_CHARS_SQL = "chr(32) || chr(9) || chr(13) || chr(10)"
+
+#: The stripped message inside the ``step_author(src, msg)`` macro body.
+_MACRO_MSG_STRIPPED = f"ltrim(msg, {_STRIP_CHARS_SQL})"
+
+#: The stripped ``message`` column, for predicates over ``steps`` rows.
+_COLUMN_MSG_STRIPPED = f"ltrim(message, {_STRIP_CHARS_SQL})"
+
+
+def _author_arms() -> SqlFragment:
+    """One ``WHEN starts_with(...) THEN '<author>'`` arm per rule, in order."""
+    return SqlFragment(
+        "\n".join(
+            f"    WHEN starts_with({_MACRO_MSG_STRIPPED}, {sql_literal(prefix)}) "
+            f"THEN {sql_literal(author)}"
+            for author, prefix in AUTHOR_PREFIX_RULES
+        )
+    )
+
+
+def _step_author_case() -> SqlFragment:
+    """The ``CASE`` expression behind the ``step_author(src, msg)`` macro.
+
+    ``NULL`` for a step whose source is not ``user``; otherwise ``harness`` for
+    an empty message, the first matching rule's author, and ``human`` when
+    nothing matches.
+    """
+    return SqlFragment(
+        "CASE\n    WHEN src IS DISTINCT FROM 'user' THEN NULL\n"
+        f"    WHEN msg IS NULL OR {_MACRO_MSG_STRIPPED} = '' THEN 'harness'\n"
+        f"{_author_arms()}\n    ELSE 'human'\nEND"
+    )
+
+
+def _interrupt_predicate() -> SqlFragment:
+    """``starts_with`` over :data:`INTERRUPT_PREFIXES` for the ``message`` column."""
+    return SqlFragment(
+        "("
+        + " OR ".join(
+            f"starts_with({_COLUMN_MSG_STRIPPED}, {sql_literal(prefix)})"
+            for prefix in INTERRUPT_PREFIXES
+        )
+        + ")"
+    )
+
+
+#: The macro body and the interrupt test, rendered once from the tables above.
+STEP_AUTHOR_CASE_SQL: SqlFragment = _step_author_case()
+INTERRUPT_PREDICATE_SQL: SqlFragment = _interrupt_predicate()
+
+
+__all__ = [
+    "AUTHOR_PREFIX_RULES",
+    "AUTHOR_STRIP_CHARS",
+    "AUTHOR_VALUES",
+    "INTERRUPT_PREDICATE_SQL",
+    "INTERRUPT_PREFIXES",
+    "STEP_AUTHOR_CASE_SQL",
+]