@pentatonic-ai/ai-agent-sdk 0.10.31 → 0.10.33

package/dist/index.cjs

@@ -878,7 +878,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.31";
+var VERSION = "0.10.33";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/dist/index.js

@@ -847,7 +847,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.31";
+var VERSION = "0.10.33";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.10.31",
+  "version": "0.10.33",
   "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",

package/packages/memory-engine-v2/compat/server.py

@@ -57,6 +57,8 @@ NV_EMBED_URL = os.environ.get("NV_EMBED_URL", "http://nv-embed:8041/v1/embedding
 NV_EMBED_API_KEY = os.environ.get("NV_EMBED_API_KEY", "")
 NV_EMBED_PROVIDER = os.environ.get("NV_EMBED_PROVIDER", "openai")  # 'openai' | 'pentatonic-gateway'
 EMBED_DIM = int(os.environ.get("EMBED_DIM", "4096"))
+# Window (minutes) over which /health/deep computes the distillation drain rate.
+HEALTH_DRAIN_WINDOW_MIN = int(os.environ.get("HEALTH_DRAIN_WINDOW_MIN", "5"))
 
 COLLECTION_NAME = "evidence"
 
@@ -665,6 +667,31 @@ async def health_deep():
     except Exception as e:
         result["stores"]["org_model"] = {"status": "error", "error": str(e)}
 
+    # distillation drain rate — events distilled per minute over a recent
+    # window, by producer. Surfaces whether the async extractor fleet is keeping
+    # up with ingest (pair with distillation_pending in the counts above). Cheap:
+    # served by idx_event_distillations_producer_time (producer, distilled_at).
+    try:
+        async with _pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT producer, count(*) AS n FROM event_distillations "
+                    "WHERE distilled_at > now() - make_interval(mins => %s) "
+                    "GROUP BY producer",
+                    (HEALTH_DRAIN_WINDOW_MIN,),
+                )
+                rows = await cur.fetchall()
+        by_producer = {r["producer"]: r["n"] for r in rows}
+        total = sum(by_producer.values())
+        result["distillation"] = {
+            "window_min": HEALTH_DRAIN_WINDOW_MIN,
+            "drain_per_min": round(total / HEALTH_DRAIN_WINDOW_MIN, 1),
+            "drained_in_window": total,
+            "by_producer": by_producer,
+        }
+    except Exception as e:
+        result["distillation"] = {"status": "error", "error": str(e)}
+
     # vector-index
     try:
         info = await _qdrant.get_collection(COLLECTION_NAME)

package/packages/memory-engine-v2/extractor-async/worker.py

@@ -193,13 +193,24 @@ _PROV_REL = _cap_prov("relationships.provenance_event_ids", "EXCLUDED.provenance
 # lever, this is the monitoring + active-learning sample (drift detection and
 # fresh teacher-gold on live traffic). Default conservative-ish 5%.
 STUDENT_SAMPLE_RATE = float(os.environ.get("STUDENT_SAMPLE_RATE", "0.05"))
-# Fact categories that always go to the teacher regardless of the student's
-# output (high-value, cheap to over-escalate). Comma-separated, lowercased.
+# Fact categories that go to the teacher regardless of the student's output
+# (high-value, cheap to over-escalate). Comma-separated, lowercased.
 HIGH_VALUE_CATEGORIES = {
     c.strip().lower()
     for c in os.environ.get("HIGH_VALUE_CATEGORIES", "decision,commitment").split(",")
     if c.strip()
 }
+# Fraction of high-value-class events that ESCALATE to the teacher. 1.0 (default)
+# = the original always-teacher gate. The gate was set at cascade launch when the
+# student was unproven; since then the clean student has zero quality-fail
+# escalations in prod and shadow-eval parity with the teacher — while the HV gate
+# routed ~57% of a decision/commitment-heavy backlog to the teacher (90% of all
+# escalations, 2026-07-09), pinning drain to teacher capacity with the student
+# idle. Lowering this (e.g. 0.25) makes HV student-primary with an elevated
+# teacher sample as the safety net/monitoring corpus on exactly the high-value
+# class. Instant rollback: set back to 1.0. Escalated-anyway HV events keep the
+# 'high_value_class' ledger reason, so the mix stays queryable.
+HIGH_VALUE_SAMPLE_RATE = float(os.environ.get("HIGH_VALUE_SAMPLE_RATE", "1.0"))
 
 
 # KV-text output format constants. We dropped JSON output (and the
@@ -1078,10 +1089,14 @@ def escalation_decision(
     for em in {e.lower() for e in _EMAIL_RE.findall(blob)}:
         if em not in known:
             return True, "grounding_violation"
-    # 2. High-value fact class — always teacher.
+    # 2. High-value fact class — teacher at HIGH_VALUE_SAMPLE_RATE (1.0 = the
+    # original always-teacher gate; lower = student-primary with an elevated
+    # teacher sample on exactly this class — see the config note).
     for f in student_result.get("facts", []):
         if (f.get("category") or "").lower() in HIGH_VALUE_CATEGORIES:
-            return True, "high_value_class"
+            if HIGH_VALUE_SAMPLE_RATE >= 1.0 or random.random() < HIGH_VALUE_SAMPLE_RATE:
+                return True, "high_value_class"
+            break  # HV but sampled-out → student writes; still eligible for gate 3
     # 3. Random monitoring/active-learning sample (not a quality lever).
     if STUDENT_SAMPLE_RATE > 0 and random.random() < STUDENT_SAMPLE_RATE:
         return True, "random_sample"
@@ -2964,7 +2979,8 @@ async def amain():
             f"cascade ENABLED — student-primary "
             f"(model={STUDENT_MODEL}, endpoint={STUDENT_ENDPOINT or '(unset!)'}, "
             f"sample_rate={STUDENT_SAMPLE_RATE}, "
-            f"high_value={sorted(HIGH_VALUE_CATEGORIES)})"
+            f"high_value={sorted(HIGH_VALUE_CATEGORIES)}, "
+            f"hv_sample_rate={HIGH_VALUE_SAMPLE_RATE})"
         )
         if not STUDENT_ENDPOINT:
             log.warning(

package/packages/memory-engine-v2/org-model/migrations/011_event_distillations_time_index.sql

@@ -0,0 +1,26 @@
+-- 011_event_distillations_time_index.sql — time-ordered index for drain-rate
+-- queries over the distillation ledger.
+--
+-- /health/deep surfaces the distillation drain rate (events distilled per
+-- minute, by producer) so we can see whether the async extractor fleet is
+-- keeping up with ingest. That query is a recent-window scan across ALL
+-- producers:
+--
+--   SELECT producer, count(*) FROM event_distillations
+--   WHERE distilled_at > now() - interval '5 minutes' GROUP BY producer;
+--
+-- The existing idx_event_distillations_producer_time is (producer, distilled_at)
+-- — producer-leading, so it cannot serve a cross-producer time-range scan, and
+-- the planner falls back to a Seq Scan (measured 244ms at 420k rows). The ledger
+-- is an append-only, unbounded log growing ~80k rows/day, so that scan degrades
+-- linearly. This time-leading index makes the drain query an index range scan
+-- (producer trails so the GROUP BY is covered) and keeps it flat as the ledger
+-- grows. Also serves any other "recent distillations" time-range query.
+--
+-- On an already-initialised prod DB (migrations mount at
+-- /docker-entrypoint-initdb.d and only run on a fresh volume) apply this
+-- manually with CREATE INDEX CONCURRENTLY to avoid locking the ledger against
+-- live writes.
+
+CREATE INDEX IF NOT EXISTS idx_event_distillations_distilled_at
+  ON event_distillations (distilled_at DESC, producer);

package/packages/memory-engine-v2/scripts/prune_distillation_queue.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""prune_distillation_queue.py — batched prune of old terminal-state rows from
+distillation_queue.
+
+The queue accumulates one row per distillation ATTEMPT and never prunes: done
+rows pile up (992k of ~1.08M rows measured 2026-07-09), and the redistill
+gardener inserts a fresh row per re-distill (no unique constraint on event_id).
+This bloats idx_distillation_status, so once the workers got fast (after the
+provenance cap) every `claim_next_batch` scan and every mark-done UPDATE started
+taking 10-12s — the queue became the next drain bottleneck.
+
+A `done` row's ONLY consumer is the ingest idempotency guard in
+_enqueue_distillation (`NOT EXISTS ... status IN ('pending','claimed','done')`),
+which stops a RE-DELIVERED event being distilled twice. Re-delivery only happens
+for recent events (ingest retries / DLQ replays), so done rows older than a
+safety window are pure tombstones. The redistill gardener does NOT read done rows
+(its "already queued" guard checks only pending/claimed; its "already clean" gate
+reads distillation_traces + event_distillations) — verified 2026-07-09. So
+pruning old terminal rows is safe and does not trigger re-distillation.
+
+Deletes in bounded batches (commit per batch) so it never holds a long lock or a
+huge transaction against live distillation / replication. Idempotent + resumable.
+
+DRY-RUN by default (reports how many rows match, writes nothing). --apply to delete.
+
+  python3 prune_distillation_queue.py --older-than-days 14            # dry-run
+  python3 prune_distillation_queue.py --older-than-days 14 --apply
+
+Only 'done' by default. 'failed' rows are kept (few; useful for investigation)
+unless --include-failed. After a large prune, plain autovacuum reclaims the space
+for reuse (table stops growing); returning it to disk needs VACUUM/pg_repack.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import time
+
+import psycopg
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--older-than-days", type=int, default=14,
+                    help="prune terminal rows whose completed_at (or enqueued_at) is older than this")
+    ap.add_argument("--batch", type=int, default=10000, help="rows deleted per commit")
+    ap.add_argument("--include-failed", action="store_true",
+                    help="also prune old 'failed' rows (default: 'done' only)")
+    ap.add_argument("--apply", action="store_true", help="delete (default: dry-run)")
+    args = ap.parse_args()
+
+    statuses = ["done"] + (["failed"] if args.include_failed else [])
+    # age is measured on completion time, falling back to enqueue time for legacy
+    # rows written before completed_at existed.
+    where = (
+        "status = ANY(%(statuses)s) "
+        "AND COALESCE(completed_at, enqueued_at) < now() - make_interval(days => %(days)s)"
+    )
+    params = {"statuses": statuses, "days": args.older_than_days}
+
+    with psycopg.connect(os.environ["PG_DSN"], autocommit=True) as conn:
+        total = conn.execute(
+            f"SELECT count(*) FROM distillation_queue WHERE {where}", params
+        ).fetchone()[0]
+        overall = conn.execute("SELECT count(*) FROM distillation_queue").fetchone()[0]
+        print(f"matched {total} prunable row(s) (statuses={statuses}, "
+              f"older_than={args.older_than_days}d) of {overall} total")
+        if not args.apply:
+            print("dry-run — pass --apply to delete")
+            return 0
+        if total == 0:
+            print("nothing to prune")
+            return 0
+
+        deleted = 0
+        t0 = time.monotonic()
+        while True:
+            # Delete by PK from a bounded id subset so each statement is a small,
+            # index-driven batch — never a full-table lock.
+            n = conn.execute(
+                f"DELETE FROM distillation_queue WHERE id IN "
+                f"(SELECT id FROM distillation_queue WHERE {where} LIMIT %(batch)s)",
+                {**params, "batch": args.batch},
+            ).rowcount
+            deleted += n
+            print(f"  deleted {deleted}/{total} ({time.monotonic()-t0:.0f}s)", flush=True)
+            if n == 0:
+                break
+
+        remaining = conn.execute("SELECT count(*) FROM distillation_queue").fetchone()[0]
+        print(f"done: pruned {deleted} row(s); distillation_queue now {remaining} rows")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())