amfs-adapter-postgres 0.2.41__tar.gz → 0.2.43__tar.gz

{amfs_adapter_postgres-0.2.41 → amfs_adapter_postgres-0.2.43}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: amfs-adapter-postgres
-Version: 0.2.41
+Version: 0.2.43
 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.54
 Requires-Dist: psycopg-pool>=3.1
 Requires-Dist: psycopg[binary]<4,>=3.1

{amfs_adapter_postgres-0.2.41 → amfs_adapter_postgres-0.2.43}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "amfs-adapter-postgres"
-version = "0.2.41"
+version = "0.2.43"
 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.54",
     "psycopg[binary]>=3.1,<4",
     "psycopg-pool>=3.1",
 ]

{amfs_adapter_postgres-0.2.41 → amfs_adapter_postgres-0.2.43}/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,
@@ -183,6 +183,45 @@ def _paginate_sql(
     return query, params
 
 
+def priority_score_sql(now: datetime, config: Any | None = None) -> tuple[str, list[Any]]:
+    """``amfs_core.tiering.PriorityScorer.score`` as a SQL expression.
+
+    The tiers pages rank every current entry in the account by this score and
+    take the top 50 as Hot and the next 200 as Warm. Scoring in Python meant
+    loading the whole namespace first; on a 420K-entry account the two
+    requests the page makes together took an 8 GiB instance down. The
+    expression below is the same formula over the same columns, so the
+    database can order by it and hand back one page::
+
+        (alpha * importance + beta * recency) * freq_boost * time_decay
+
+    with ``importance = importance_score or confidence`` clamped to [0, 1],
+    ``recency = exp(-lambda * age_days)``, ``freq_boost = max(1, ln(1 +
+    recall_count))`` and ``time_decay = exp(-lambda * age_days / freq_boost)``.
+    ``importance_score`` of 0 falls through to confidence exactly as the
+    Python ``or`` does. Returns the expression and its parameters in placeholder
+    order: alpha, beta, lambda, *now*, lambda, *now*.
+    """
+    if config is None:
+        from amfs_core.models import TierConfig
+
+        config = TierConfig()
+    age_days = "GREATEST(0.0, EXTRACT(EPOCH FROM (%s - written_at)) / 86400.0)"
+    importance = (
+        "LEAST(1.0, GREATEST(0.0, COALESCE(NULLIF(importance_score, 0), confidence)::float8))"
+    )
+    freq_boost = "GREATEST(1.0, LN(1.0 + COALESCE(recall_count, 0)))"
+    expr = (
+        f"((%s * {importance} + %s * EXP(-%s * {age_days}))"
+        f" * {freq_boost}"
+        f" * EXP(-%s * {age_days} / {freq_boost}))"
+    )
+    # The age expression appears twice, each with its own ``now``.
+    lam = float(config.decay_lambda)
+    params: list[Any] = [float(config.alpha), float(config.beta), lam, now, lam, now]
+    return expr, params
+
+
 def list_conditions(
     namespace: str,
     entity_path: str | None,
@@ -274,6 +313,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
@@ -825,6 +868,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
@@ -1336,6 +1380,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.
@@ -1806,7 +1856,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'
                       )
                     """,
                 )
@@ -1816,6 +1866,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
@@ -2500,6 +2551,90 @@ class PostgresAdapter(AdapterABC):
                 row = cur.fetchone()
         return int(row["n"]) if row else 0
 
+    def priority_stats(
+        self,
+        *,
+        scope: SqlScope | None = None,
+        agent_id: str | None = None,
+        now: datetime | None = None,
+        branch: str = "main",
+    ) -> tuple[int, float | None]:
+        """``(count, mean priority score)`` over the rows :meth:`list` returns.
+
+        What the tiers distribution needs and nothing more: the count fixes
+        the Hot/Warm/Archive split (the tiers are rank bands) and the mean is
+        the page's "average score". Computed by the database with
+        :func:`priority_score_sql`; no entry row leaves it.
+        """
+        now = now or datetime.now(timezone.utc)
+        score, score_params = priority_score_sql(now)
+        with self._pool.connection() as conn:
+            with conn.cursor() as cur:
+                conditions, params = list_conditions(
+                    self._namespace,
+                    None,
+                    include_superseded=False,
+                    branch=branch,
+                    scope=scope,
+                    agent_id=agent_id,
+                    branch_scope=self._branch_scope(cur, branch),
+                )
+                where = " AND ".join(conditions)
+                cur.execute(
+                    f"SELECT COUNT(*) AS n, AVG({score}) AS mean "
+                    f"FROM amfs_memory_entries WHERE {where}",
+                    [*score_params, *params],
+                )
+                row = cur.fetchone()
+        if not row or not row["n"]:
+            return 0, None
+        mean = row["mean"]
+        return int(row["n"]), (float(mean) if mean is not None else None)
+
+    def list_by_priority(
+        self,
+        *,
+        scope: SqlScope | None = None,
+        agent_id: str | None = None,
+        limit: int,
+        offset: int = 0,
+        now: datetime | None = None,
+        branch: str = "main",
+    ) -> list[MemoryEntry]:
+        """One page of the rows :meth:`list` returns, highest priority first.
+
+        The order is :func:`priority_score_sql` descending with the stable
+        ``written_at DESC, entity_path, key`` tiebreak, so a page boundary is
+        deterministic. A tier is a band of this ranking: rows 0–49 are Hot,
+        50–249 Warm, the rest Archive — the caller picks *offset* and *limit*
+        from the band and the database returns only that page.
+        """
+        now = now or datetime.now(timezone.utc)
+        score, score_params = priority_score_sql(now)
+        with self._pool.connection() as conn:
+            with conn.cursor() as cur:
+                conditions, params = list_conditions(
+                    self._namespace,
+                    None,
+                    include_superseded=False,
+                    branch=branch,
+                    scope=scope,
+                    agent_id=agent_id,
+                    branch_scope=self._branch_scope(cur, branch),
+                )
+                where = " AND ".join(conditions)
+                query = (
+                    f"SELECT {entry_select(self._has_is_artifact_col, self._has_validators_col)} "
+                    f"FROM amfs_memory_entries WHERE {where} "
+                    f"ORDER BY {score} DESC, written_at DESC, entity_path, key"
+                )
+                query, all_params = _paginate_sql(
+                    query, [*params, *score_params], limit=limit, offset=offset
+                )
+                cur.execute(query, all_params)
+                rows = cur.fetchall()
+        return [self._row_to_entry(r) for r in rows]
+
     def entry_authors(self, refs: list[tuple[str, str]]) -> dict[tuple[str, str], str]:
         """Who wrote each ``(entity_path, key)``, for the current version.
 
@@ -4125,6 +4260,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")
@@ -4433,9 +4577,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
@@ -4458,6 +4603,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
@@ -4665,8 +4811,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
@@ -4684,6 +4831,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]
 

amfs_adapter_postgres-0.2.43/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;