amfs-adapter-postgres 0.2.42__tar.gz → 0.2.44__tar.gz

{amfs_adapter_postgres-0.2.42 → amfs_adapter_postgres-0.2.44}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: amfs-adapter-postgres
-Version: 0.2.42
+Version: 0.2.44
 Summary: AMFS Postgres adapter with back-propagation triggers
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
-Requires-Dist: amfs-core>=0.3.53
+Requires-Dist: amfs-core>=0.3.56
 Requires-Dist: psycopg-pool>=3.1
 Requires-Dist: psycopg[binary]<4,>=3.1

{amfs_adapter_postgres-0.2.42 → amfs_adapter_postgres-0.2.44}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "amfs-adapter-postgres"
-version = "0.2.42"
+version = "0.2.44"
 description = "AMFS Postgres adapter with back-propagation triggers"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 dependencies = [
     # 0.3.14 adds the capture fields this adapter now persists and selects back,
     # tool_calls among them.
-    "amfs-core>=0.3.53",
+    "amfs-core>=0.3.56",
     "psycopg[binary]>=3.1,<4",
     "psycopg-pool>=3.1",
 ]

{amfs_adapter_postgres-0.2.42 → amfs_adapter_postgres-0.2.44}/src/amfs_postgres/adapter.py

@@ -34,7 +34,7 @@ from amfs_core.exclusions import (
     AGENT_ID_NOT_EXCLUDED_SQL,
     ENTITY_PATH_NOT_EXCLUDED_SQL,
 )
-from amfs_core.actions import entity_paths_of, recorded_environment
+from amfs_core.actions import entity_paths_of, recorded_covariates, recorded_environment
 from amfs_core.evidence import cited_entries, outcome_model, outcome_read_keys, outcome_verified_by
 from amfs_core.models import (
     OUTCOME_MULTIPLIERS,
@@ -222,6 +222,14 @@ def priority_score_sql(now: datetime, config: Any | None = None) -> tuple[str, l
     return expr, params
 
 
+#: A row whose TTL has not passed: the predicate every read path that
+#: surfaces current entries carries (``list``, ``search``, ``semantic_search``,
+#: the agent listing). ``NOW()`` rather than a parameter because the fragment
+#: sits in WHERE lists whose parameters are positional and spliced around by
+#: their callers; with nothing to bind it cannot shift any of them.
+_NOT_EXPIRED = "(ttl_at IS NULL OR ttl_at > NOW())"
+
+
 def list_conditions(
     namespace: str,
     entity_path: str | None,
@@ -231,6 +239,7 @@ def list_conditions(
     scope: SqlScope | None,
     agent_id: str | None,
     branch_scope: tuple[str, list[Any]] | None = None,
+    include_expired: bool = False,
 ) -> tuple[list[str], list[Any]]:
     """The WHERE behind ``list()`` and ``count_entries()`` on both adapters.
 
@@ -238,6 +247,13 @@ def list_conditions(
     about which rows exist, and so the shared-namespace guard is applied to
     the unscoped read in one place (``tests/test_shared_path_scoping.py``).
 
+    The rows are the live ones: current and not past their ``ttl_at``, which
+    is the rule ``read`` and ``search`` apply, so a TTL takes effect on every
+    listing at once instead of when the sweep next archives the row. Two
+    callers see expired rows all the same. *include_superseded* is the
+    history, which hides nothing; *include_expired* is for the sweep, whose
+    whole purpose is to find them (``list_expired``).
+
     *branch_scope* replaces the plain ``branch = %s`` predicate with the
     overlay fragment from :func:`branch_scope_sql` (a branch's own live rows
     plus the parent's for every key it has not touched) — the adapters pass
@@ -258,6 +274,8 @@ def list_conditions(
 
     if not include_superseded:
         conditions.append("superseded_at IS NULL")
+        if not include_expired:
+            conditions.append(_NOT_EXPIRED)
     if agent_id is not None:
         conditions.append("agent_id = %s")
         params.append(agent_id)
@@ -313,6 +331,10 @@ _LOCAL_EVIDENCE_SQL = (
 _OUTCOME_TASK_TEXT_SQL = (
     Path(__file__).parent / "migrations" / "011_outcome_task_text.sql"
 ).read_text(encoding="utf-8")
+#: Migration 014 — the covariates of the task on the outcome row.
+_OUTCOME_COVARIATES_SQL = (
+    Path(__file__).parent / "migrations" / "014_outcome_covariates.sql"
+).read_text(encoding="utf-8")
 #: Migration 012 — the evidence functions rendered from ``amfs_core.evidence``
 #: (``evidence_sql.render_evidence_sql``), replacing the hand-written bodies
 #: of 008/009 with the same arithmetic read off the Python model. Applied
@@ -864,6 +886,7 @@ class PostgresAdapter(AdapterABC):
         self._has_outcome_embedding_col = False
         self._has_outcome_env_col = False
         self._has_task_text_col = False
+        self._has_covariates_col = False
         self._has_verified_by_col = False
         self._pgvector_version: tuple[int, ...] | None = None
         # When an embedder is provided, embeddings are computed at write time and
@@ -1375,6 +1398,12 @@ class PostgresAdapter(AdapterABC):
             ALTER TABLE amfs_outcomes
             ADD COLUMN IF NOT EXISTS environment JSONB
         """)
+        # The covariates of the task — the run's declared attributes other
+        # than its environment and situation (the customer's plan, the app
+        # version a lookup showed) — so a contested situation's record can be
+        # split by what separates the runs the old action still wins from the
+        # ones it lost (amfs_core.actions.split_contested). See migration 014.
+        cur.execute(_OUTCOME_COVARIATES_SQL)
         # Query-conditioned evidence: see migration 010.
         cur.execute(_LOCAL_EVIDENCE_SQL)
         # The task text on outcomes: see migration 011.
@@ -1845,7 +1874,7 @@ class PostgresAdapter(AdapterABC):
                     WHERE table_name = 'amfs_outcomes'
                       AND column_name IN (
                         'actions_taken', 'task_embedding', 'environment', 'task_text',
-                        'verified_by'
+                        'verified_by', 'covariates'
                       )
                     """,
                 )
@@ -1855,6 +1884,7 @@ class PostgresAdapter(AdapterABC):
                 self._has_outcome_env_col = "environment" in found
                 self._has_task_text_col = "task_text" in found
                 self._has_verified_by_col = "verified_by" in found
+                self._has_covariates_col = "covariates" in found
 
     # ------------------------------------------------------------------
     # read
@@ -2441,13 +2471,15 @@ class PostgresAdapter(AdapterABC):
 
         What a TTL sweep needs: the rows to archive, found through the
         partial index on ``ttl_at`` (``idx_entries_ttl``) rather than by
-        listing the tenant and checking each entry's clock in Python. Same
-        row set as ``list()`` — current versions, this branch, shared paths
-        excluded — narrowed to the expired ones. *limit* bounds one sweep;
-        the next sweep picks up the rest.
+        listing the tenant and checking each entry's clock in Python. The
+        scope is ``list()``'s — current versions, this branch, shared paths
+        excluded — and the rows are the ones ``list()`` leaves out: those past
+        their TTL and not yet archived. *limit* bounds one sweep; the next
+        sweep picks up the rest.
         """
         conditions, params = list_conditions(
             self._namespace, None, include_superseded=False, branch=branch, scope=None, agent_id=None,
+            include_expired=True,
         )
         conditions.append("ttl_at IS NOT NULL AND ttl_at <= %s")
         params.append(now or datetime.now(timezone.utc))
@@ -2672,7 +2704,7 @@ class PostgresAdapter(AdapterABC):
 
         # The branch scope is resolved on the connection below (it may need the
         # branch's parent); a placeholder keeps its position in the WHERE.
-        conditions = ["namespace = %s", _BRANCH_SCOPE, "superseded_at IS NULL"]
+        conditions = ["namespace = %s", _BRANCH_SCOPE, "superseded_at IS NULL", _NOT_EXPIRED]
         params: list[Any] = [self._namespace]
 
         if query.depth < 3:
@@ -2809,7 +2841,7 @@ class PostgresAdapter(AdapterABC):
 
         query_vec = query.embedding if query.embedding is not None else embedder.embed(query.text)
 
-        conditions = ["namespace = %s", "superseded_at IS NULL", "embedding IS NOT NULL"]
+        conditions = ["namespace = %s", "superseded_at IS NULL", "embedding IS NOT NULL", _NOT_EXPIRED]
         params: list[Any] = [self._namespace]
 
         if query.entity_path is not None:
@@ -2916,15 +2948,20 @@ class PostgresAdapter(AdapterABC):
         belonging to another agent turns up in ``keys``. A NULL *agent_id*
         compares as unknown rather than true, so passing nothing counts shared
         entries only — the safe direction.
+
+        The TTL predicate is here for the same reason: ``list()`` leaves out an
+        entry past its ``ttl_at``, so the key of one must not turn up in
+        ``keys`` either.
         """
         with self._pool.connection() as conn:
             row = conn.execute(
-                """SELECT count(*) AS total,
+                f"""SELECT count(*) AS total,
                           count(*) FILTER (WHERE coalesce(recall_count, 0) = 0)
                               AS never_read
                      FROM amfs_memory_entries
                     WHERE namespace = %s AND branch = %s AND entity_path = %s
                       AND superseded_at IS NULL
+                      AND {_NOT_EXPIRED}
                       AND (%s::text IS NULL OR key <> %s)
                       AND (shared OR agent_id = %s::text)""",
                 (self._namespace, branch, entity_path, exclude_key, exclude_key,
@@ -2932,9 +2969,10 @@ class PostgresAdapter(AdapterABC):
             ).fetchone()
             keys = [
                 r["key"] for r in conn.execute(
-                    """SELECT key FROM amfs_memory_entries
+                    f"""SELECT key FROM amfs_memory_entries
                         WHERE namespace = %s AND branch = %s AND entity_path = %s
                           AND superseded_at IS NULL
+                          AND {_NOT_EXPIRED}
                           AND (%s::text IS NULL OR key <> %s)
                           AND (shared OR agent_id = %s::text)
                         ORDER BY key LIMIT %s""",
@@ -4248,6 +4286,15 @@ class PostgresAdapter(AdapterABC):
                         columns.append("environment")
                         placeholders.append("%s::jsonb")
                         params.append(json.dumps(env))
+                if getattr(self, "_has_covariates_col", False):
+                    covariates = recorded_covariates({
+                        "covariates": record.covariates or None,
+                        "session_metadata": record.session_metadata or {},
+                    })
+                    if covariates:
+                        columns.append("covariates")
+                        placeholders.append("%s::jsonb")
+                        params.append(json.dumps(covariates, default=str))
                 task_embedding = self._outcome_embedding(record)
                 if task_embedding is not None:
                     columns.append("task_embedding")
@@ -4556,9 +4603,10 @@ class PostgresAdapter(AdapterABC):
             conditions.append("committed_at >= %s")
             params.append(since)
         env_col = ", environment" if getattr(self, "_has_outcome_env_col", False) else ""
+        cov_col = ", covariates" if getattr(self, "_has_covariates_col", False) else ""
         sql = f"""
             SELECT outcome_ref, outcome_type, committed_at, agent_id, actions_taken, situation,
-                   1 - (task_embedding <=> %s::vector) AS similarity{env_col}
+                   1 - (task_embedding <=> %s::vector) AS similarity{env_col}{cov_col}
             FROM amfs_outcomes
             WHERE {" AND ".join(conditions)}
             ORDER BY task_embedding <=> %s::vector
@@ -4581,6 +4629,7 @@ class PostgresAdapter(AdapterABC):
                 "situation": row.get("situation"),
                 "actions_taken": _jsonb(row.get("actions_taken"), []),
                 "environment": _jsonb(row.get("environment"), {}) or {},
+                "covariates": _jsonb(row.get("covariates"), {}) or {},
                 "similarity": sim,
             })
         return out
@@ -4788,8 +4837,9 @@ class PostgresAdapter(AdapterABC):
             conditions.append("committed_at >= %s")
             params.append(since)
         env_col = ", environment" if getattr(self, "_has_outcome_env_col", False) else ""
+        cov_col = ", covariates" if getattr(self, "_has_covariates_col", False) else ""
         sql = f"""
-            SELECT outcome_ref, outcome_type, committed_at, agent_id, actions_taken, situation{env_col}
+            SELECT outcome_ref, outcome_type, committed_at, agent_id, actions_taken, situation{env_col}{cov_col}
             FROM amfs_outcomes
             WHERE {" AND ".join(conditions)}
             ORDER BY committed_at DESC
@@ -4807,6 +4857,7 @@ class PostgresAdapter(AdapterABC):
             "situation": row.get("situation"),
             "actions_taken": _jsonb(row.get("actions_taken"), []),
             "environment": _jsonb(row.get("environment"), {}) or {},
+            "covariates": _jsonb(row.get("covariates"), {}) or {},
             "similarity": 1.0,
         } for row in rows]
 
@@ -5061,6 +5112,7 @@ class PostgresAdapter(AdapterABC):
             "agent_id = %s",
             "superseded_at IS NULL",
             "branch = 'main'",
+            _NOT_EXPIRED,
         ]
         params: list[Any] = [namespace, agent_id]
         for prefix in exclude_prefixes:

{amfs_adapter_postgres-0.2.42 → amfs_adapter_postgres-0.2.44}/src/amfs_postgres/async_adapter.py

@@ -42,6 +42,7 @@ from amfs_postgres.adapter import (
     _EVIDENCE_COLUMNS,
     _EVIDENCE_SELECT,
     _EXCLUDE_SHARED_PATHS,
+    _NOT_EXPIRED,
     _REUSE_EVENT_INSERT_SQL,
     PostgresAdapter,
     _evidence_params,
@@ -353,6 +354,12 @@ class AsyncPostgresAdapter:
         entry = self._row_to_entry(row)
         if entry.confidence < min_confidence:
             return None
+        # As ``PostgresAdapter.read`` does: a TTL takes effect on read, without
+        # waiting for the sweep. Missing here, the HTTP read route — which
+        # tries this adapter first — served an expired entry that the sync
+        # adapter behind the same route would have withheld.
+        if entry.is_expired():
+            return None
         return entry
 
     # ──────────────────────────────────────────────────────────────
@@ -580,7 +587,7 @@ class AsyncPostgresAdapter:
 
         # ``_BRANCH_SCOPE`` is swapped for the real branch condition once a
         # connection is open; its params are spliced in after the namespace.
-        conditions = ["namespace = %s", _BRANCH_SCOPE, "superseded_at IS NULL"]
+        conditions = ["namespace = %s", _BRANCH_SCOPE, "superseded_at IS NULL", _NOT_EXPIRED]
         params: list[Any] = [self._namespace]
 
         if query.depth < 3:
@@ -713,6 +720,7 @@ class AsyncPostgresAdapter:
             _BRANCH_SCOPE,
             "superseded_at IS NULL",
             "embedding IS NOT NULL",
+            _NOT_EXPIRED,
         ]
         params: list[Any] = [self._namespace]
         if query.entity_path is not None:
@@ -1145,15 +1153,19 @@ class AsyncPostgresAdapter:
         ``list()`` applied, and this block's ``keys`` land in a tool result. A
         NULL *agent_id* compares as unknown, so passing nothing counts shared
         entries only.
+
+        The TTL predicate is carried for the same reason: ``list()`` leaves out
+        an entry past its ``ttl_at``, so its key must not turn up here either.
         """
         async with self._pool.connection() as conn:
             cur = await conn.execute(
-                """SELECT count(*) AS total,
+                f"""SELECT count(*) AS total,
                           count(*) FILTER (WHERE coalesce(recall_count, 0) = 0)
                               AS never_read
                      FROM amfs_memory_entries
                     WHERE namespace = %s AND branch = %s AND entity_path = %s
                       AND superseded_at IS NULL
+                      AND {_NOT_EXPIRED}
                       AND (%s::text IS NULL OR key <> %s)
                       AND (shared OR agent_id = %s::text)""",
                 (self._namespace, branch, entity_path, exclude_key, exclude_key,
@@ -1161,9 +1173,10 @@ class AsyncPostgresAdapter:
             )
             row = await cur.fetchone()
             cur = await conn.execute(
-                """SELECT key FROM amfs_memory_entries
+                f"""SELECT key FROM amfs_memory_entries
                     WHERE namespace = %s AND branch = %s AND entity_path = %s
                       AND superseded_at IS NULL
+                      AND {_NOT_EXPIRED}
                       AND (%s::text IS NULL OR key <> %s)
                       AND (shared OR agent_id = %s::text)
                     ORDER BY key LIMIT %s""",

amfs_adapter_postgres-0.2.44/src/amfs_postgres/migrations/014_outcome_covariates.sql

@@ -0,0 +1,20 @@
+-- Migration 014: the covariates of the task on the outcome row
+--
+-- An outcome records what was done (`actions_taken`) in what kind of task
+-- (`situation`) under what runtime (`environment`). It did not record what
+-- the task *was like*: the customer's plan, the app version the lookup
+-- showed, the card's issuer country. When a rule changes for part of a
+-- situation — the export fix stops working on paid plans and keeps working
+-- on the free one — the situation's record turns contested (wins and losses
+-- interleaved, no streak) and nothing in it says which runs the old action
+-- still wins. On the 2026-10-21 regime study the recommendation kept the
+-- stale action as `act` on 59 % of the first searches after such a change.
+--
+-- The covariates are the scalar attributes a run declared about the task
+-- (`set_session_attributes`, `Run.begin(covariates=...)`) less its
+-- environment keys and the situation label, copied here at commit from the
+-- record so `amfs_core.actions.split_contested` can read them off the same
+-- rows the priors are aggregated from. Scalars only; at most the attribute
+-- bag's 20 keys. Written only when the record has any.
+
+ALTER TABLE amfs_outcomes ADD COLUMN IF NOT EXISTS covariates JSONB;