@pentatonic-ai/ai-agent-sdk 0.9.6 → 0.10.0

package/packages/memory-engine/.env.example

@@ -1,13 +0,0 @@
-# pentatonic-memory-engine — environment overrides
-
-# Compat shim port (matches pentatonic-memory v0.5 default)
-PME_PORT=8099
-
-# Client tenant scoping
-CLIENT_ID=default
-
-# Neo4j auth (L3 KG)
-NEO4J_AUTH=neo4j/local-dev-pw
-
-# NV-Embed model (auto-downloaded from Hugging Face on first run)
-NV_EMBED_MODEL=nvidia/NV-Embed-v2

package/packages/memory-engine/MIGRATION.md

@@ -1,219 +0,0 @@
-# Wire format & migration
-
-`pentatonic-memory-engine` is a drop-in replacement for `pentatonic-memory` v0.5.x.
-Same HTTP API, same request/response shapes — your existing SDK client code
-keeps working. This doc covers:
-
-1. **Wire format** — what every endpoint accepts and returns
-2. **What changed vs v0.5.x** — new endpoints + small additive fields
-3. **Operational notes** — per-layer health, deep healthchecks, env vars
-
----
-
-## Wire format
-
-All endpoints accept and return JSON. Base URL is the compat-shim host
-(default `http://localhost:8099`).
-
-### `POST /store`
-
-Write a memory.
-
-```json
-{
-  "content": "User prefers dark mode",
-  "metadata": {
-    "arena": "my-app",         // tenant-scoping key. Defaults to "default".
-    "kind": "note",             // optional; opaque, surfaced on read
-    "source_file": "config.md", // optional; routed to L1/L6 paths
-    "contact_email": "...",     // optional; triggers L3 Person extraction
-    "contact_name": "...",      // optional; same
-    "channel": "email",         // optional; tags ChannelStat denormalisation
-    "direction": "inbound"      // optional; same
-  },
-  "client_id": "my-app"         // optional; alternative to metadata.arena
-}
-```
-
-Response:
-
-```json
-{
-  "id": "cc830b145b1e36514f73fd508aac885a",
-  "content": "User prefers dark mode",
-  "layerId": "ml_my-app_episodic",
-  "engine": {
-    "l0": 1, "l4_qmd": 1, "l4": 1, "l5": 1, "l6": 1,
-    "l3_chunks": 0, "l3_entities": 0  // non-zero when metadata.contact_* present
-  }
-}
-```
-
-### `POST /store-batch`
-
-Same body as `/store` but `content` is replaced with `records: [{content, metadata}, ...]`.
-30–50× faster than calling `/store` per record because L2 issues one
-batched `/v1/embeddings` call instead of one per record.
-
-### `POST /search`
-
-Hybrid search across all 7 layers, RRF-fused.
-
-```json
-{
-  "query": "dark mode preferences",
-  "limit": 10,                  // default 16
-  "min_score": 0.3,              // default 0; filter low-similarity hits
-  "client_id": "my-app",         // tenant scope
-  "user_id": "alice@example.com", // optional; spans clientId AND clientId:user_id arenas
-  "method": "hybrid"             // hybrid (default) | vector | bm25
-}
-```
-
-Response:
-
-```json
-{
-  "results": [
-    {
-      "id": "cc830b145b1e36514f73fd508aac885a.md",
-      "content": "User prefers dark mode",
-      "metadata": { "arena": "my-app", "kind": "note", ... },
-      "similarity": 0.87,
-      "layer_id": "ml_my-app_episodic",
-      "source": "cc830b145b1e36514f73fd508aac885a.md",
-      "engine_layer": ""        // which layer produced this hit (l0/l3/l4/l5/l6)
-    }
-  ]
-}
-```
-
-### `POST /forget`
-
-Delete memories matching a filter. Two modes:
-
-- **Per-arena delete**: `{"arena": "my-app"}` removes everything tagged with
-  that arena across L0/L4/L5/L6 + L3 chunks + L3 Entity nodes.
-- **Global wipe**: `{"confirm": "GLOBAL_WIPE"}` (literal string, no arena) wipes
-  every layer for every tenant. Intended for dev resets only.
-
-Returns counts deleted per layer.
-
-### `GET /health`
-
-Shallow health. Returns 200 even when `status: "degraded"` — the body's
-`status` is the verdict.
-
-```json
-{
-  "status": "ok",
-  "version": "0.1.0",
-  "engine": "pentatonic-memory-engine",
-  "layers": {
-    "l0": "ok", "l1": "ok", "l2": "ok", "l3": "ok",
-    "l4": "ok", "l5": "ok", "l6": "ok", "nv_embed": "ok"
-  },
-  "memories": {
-    "l0_bm25_chunks": 233142,
-    "l4_vectors": 64212,
-    "l5_chats_chunks": 109671,
-    "l6_vector_chunks": 68220,
-    "l6_fts_chunks": 39703
-  }
-}
-```
-
-Layer values are either `"ok"`, `"degraded"`, `"http <code>"`, or
-`"unreachable: <reason>"`. The aggregate `status` is `degraded` if any
-single layer is non-ok and `down` if ≥3 are non-ok.
-
-The `memories` field is a per-layer chunk-count dict (since v0.8.4 — previously
-a single int that only reported L6's count and misled operators about real
-corpus size).
-
-### `GET /health/deep` (since v0.8.4)
-
-Synthetic round-trip per layer: embed a sentinel → write to layer → search
-for it → assert hit. Slower (~1–2s); intended for ops/cron, not for compose
-healthchecks.
-
-```json
-{
-  "status": "ok",
-  "ok": true,
-  "layers": {
-    "l4": {"status": "ok", "ok": true, "embed_ms": 12.6, "write_ms": 2.2,
-           "search_ms": 0.0, "hit": true, "total_ms": 17.1},
-    "l5": {"status": "ok", "ok": true,
-           "collections": {"chats": true, "emails": true, "contacts": true, "memory": true},
-           "embed_ms": 9.4, "write_ms": 7.6, "search_ms": 1.6, "hit": true},
-    "l6": {"status": "ok", "ok": true, "embed_ms": 11.3, "write_ms": 635.1,
-           "search_ms": 59.5, "hit": true, "reranker": "ok"}
-  }
-}
-```
-
-Sentinel rows are stored under arena `__healthcheck__` with a fixed id, so
-the probe pollutes the corpus by at most one row per layer (upserts, never
-accumulates).
-
-### `POST /aggregate` (since v0.8.x)
-
-Typed-Person aggregation over the L3 graph. Counts `(:Person)-[:COMMUNICATED]->(:Chunk)`
-edges by `group_by` keys. See `packages/memory-engine/compat/server.py` for
-the full schema — used today by the relationships UI in the TES module.
-
----
-
-## What changed vs `pentatonic-memory` v0.5.x
-
-| | v0.5.x | This package |
-|---|---|---|
-| Storage | Single Postgres + pgvector + HNSW | 7-layer fusion (SQLite FTS, Neo4j, sqlite-vec, Milvus, Milvus+rerank) |
-| Embedding | One model, one dim, ingest-time | Per-layer configurable; provider-aware (`L*_EMBED_PROVIDER`) |
-| Endpoints added | — | `/store-batch`, `/forget`, `/health/deep`, `/aggregate` |
-| `/health` body | `{status, layers}` only | + `version`, `engine`, `nv_embed` layer, per-layer `memories` dict |
-| `/store` engine fields | absent | `engine: { l0, l3_chunks, l3_entities, l4, l5, l6 }` per-layer write counts |
-| Backwards-incompat changes | — | **None.** All v0.5 client code keeps working. |
-
-The engine container's compat shim (`compat/server.py`) is the API surface;
-the layer services behind it can be replaced or scaled independently
-without changing client code.
-
----
-
-## Operational notes
-
-### Provider-aware embedding (since v0.8.0)
-
-Each layer service picks an embedding provider via `L*_EMBED_PROVIDER`:
-
-- `openai` (default) — Bearer auth, `/v1/embeddings` path, OpenAI-shaped body
-- `pentatonic-gateway` — X-API-Key auth, `/v1/embed` path
-- `cohere` — `{texts, input_type}` body shape
-
-A 401 from the configured provider auto-detects against the other built-ins
-(opt out per layer with `L*_EMBED_AUTODETECT=false`). See
-`engine/services/_shared/embed_provider.py` for the dispatch table.
-
-### L2 concurrency (since v0.8.4)
-
-L2 hybridrag-proxy is async throughout — `AsyncGraphDatabase` for Neo4j,
-`httpx.AsyncClient` for L4/L5/L6 fan-out, `asyncio.to_thread` for sqlite +
-PyTorch reranker. Fan-out across layers runs concurrently via
-`asyncio.gather`. Under sustained ingest, `/health` and `/search` no
-longer compete for a saturated threadpool.
-
-### L5 collection bootstrap (since v0.8.4)
-
-L5's serve() ensures all four collections (`chats`, `emails`, `contacts`,
-`memory`) exist at startup. Previously only `chats` was bootstrapped and
-writes to the others would 500.
-
-### Health check semantics
-
-- `compose` healthcheck and `engine-runner.sh` deploy gate use `/health` —
-  it's fast (<50ms) and returns HTTP 200 regardless of body status.
-- Operators/cron should use `/health/deep` for real functional validation.
-- A `compose` healthcheck on `/health/deep` would burn embedding budget
-  every 10s — avoid.

package/packages/memory-engine/README.md

@@ -1,145 +0,0 @@
-# pentatonic-memory-engine
-
-**Drop-in replacement for `pentatonic-memory` v0.5.x with a 7-layer retrieval stack underneath.**
-
-| Configuration | Mean accuracy* | p50 latency |
-|---|---|---|
-| pentatonic-memory v0.5.6 (current OSS) | 17.6% | 33ms |
-| pentatonic-memory v0.4.7 (legacy OSS) | 38.8% | 27ms |
-| **pentatonic-memory-engine — fast path** (L6-only via docker, default config) | **84.6%** | **110ms** |
-| **pentatonic-memory-engine — max accuracy** (full 7-layer L2 fusion) | **85.7%** | **1241ms** |
-| langmem (in-process) | 83.0% | 121ms |
-| cognee | 82.1% | 192ms |
-| single-store baseline | 79.3% | 110ms |
-
-\* Mean over 6 commerce-domain benches (agent-coding, chat-recall, circular-economy, customer-support, marketplace-ops, product-catalogue) using substring grading. Full reports under `bench/`.
-
-**Two configurations, same package.** The fast path (L6-only) is the default and ships at #1 on accuracy among real OSS memory stacks. The max-accuracy 7-layer mode adds Knowledge-Graph entity matching + L0 BM25 + L4 vec fusion via the L2 orchestrator — buys you +1.1pp at 11× latency. Pick per workload (live agent loop → fast path; offline batch / accuracy-graded eval → 7-layer).
-
----
-
-## What this is
-
-A self-contained docker-compose package that exposes the **same HTTP API as `pentatonic-memory`** (`/store`, `/search`, `/health`), plus two regression-fix endpoints (`/store-batch`, `/forget`) — but routes every call through a 7-layer hybrid retrieval engine instead of the single Postgres + pgvector store.
-
-Same client code. Same SDK. ~5x better accuracy on retrieval-style benchmarks.
-
-## Why does the existing OSS underperform?
-
-Detailed analysis in `docs/why-v05-underperforms.md`. Short version:
-
-- Single vector store (pgvector), single embedding per row → diluted vectors on long content
-- `atomBoost: +0.15` makes LLM-paraphrased atoms outrank source verbatim → substring grading fails
-- HyDE generated at ingest time (60s LLM call per /store), not at query time
-- pgvector HNSW broken at >2000 dims → 4096d NV-Embed falls back to sequential scan
-- No reranker, no graph traversal, no multi-store fusion
-
-## Architecture (7-layer)
-
-The engine is the same `sequential-hybridrag-7-layer` stack the L2 proxy reports in its health endpoint.
-
-```
-                                                     ┌──────────────────┐
-                                                     │  L0  BM25 (FTS)  │
-                                                     ├──────────────────┤
-                                                     │  L1  Core files  │
-                  POST /store    ┌──────────────┐   ├──────────────────┤
-                  POST /search   │ compat shim  │   │  L2  HybridRAG   │
-client (any) ───► POST /forget ──►   (FastAPI)  │──►│      orchestrator│
-                  POST /store-batch└──────────────┘   ├──────────────────┤
-                  GET  /health                       │  L3  Knowledge    │
-                                                     │      Graph (KG)   │
-                                                     ├──────────────────┤
-                                                     │  L4  sqlite-vec   │
-                                                     ├──────────────────┤
-                                                     │  L5  Milvus comms │
-                                                     ├──────────────────┤
-                                                     │  L6  Document     │
-                                                     │      Store +      │
-                                                     │      reranker     │
-                                                     └─────────┬────────┘
-                                                               │
-                                              ┌────────────────┴───────┐
-                                              │  NV-Embed-v2            │
-                                              │  Cross-encoder reranker │
-                                              └─────────────────────────┘
-```
-
-Each layer indexes the same content differently. Search runs all seven in parallel and fuses results via Reciprocal Rank Fusion (RRF). Different query types win on different layers — agent-coding queries land on L0 BM25, chat-recall on L5, multi-hop entity questions on L3, conversational context on L1.
-
-**Layer cheat-sheet:**
-
-| # | Layer | Purpose | Backing tech |
-|---|---|---|---|
-| L0 | BM25 | Lexical / keyword recall | SQLite FTS5 |
-| L1 | Core files | Always-loaded high-priority text (system manuals, key docs) | flat markdown read by L2 |
-| L2 | HybridRAG orchestrator | Fan-out + RRF fusion across all layers | Python FastAPI |
-| L3 | Knowledge Graph | Entity-aware retrieval, multi-hop relationships | Neo4j (OSS) |
-| L4 | Vector index | High-recall semantic search | sqlite-vec |
-| L5 | Comms / multi-collection vectors | Chat / email / contact / memory namespaces | Milvus (Lite by default; standalone via compose) |
-| L6 | Document store | Per-arena docs + cross-encoder reranker | sqlite + Milvus + MiniLM |
-
-## Quick start
-
-```bash
-git clone <this-repo>
-cd pentatonic-memory-engine
-cp .env.example .env       # set NEO4J_AUTH, etc.
-docker compose up -d
-```
-
-Wait ~30s for layers to come up. Verify:
-
-```bash
-curl http://localhost:8099/health
-# → {
-#     "status": "ok",
-#     "version": "0.1.0",
-#     "engine": "pentatonic-memory-engine",
-#     "layers": {"l0":"ok","l1":"ok","l2":"ok","l3":"ok","l4":"ok","l5":"ok","l6":"ok","nv_embed":"ok"},
-#     "memories": {
-#       "l0_bm25_chunks": N, "l4_vectors": N,
-#       "l5_chats_chunks": N, "l6_vector_chunks": N, "l6_fts_chunks": N
-#     }
-#   }
-
-# Or run real functional round-trips per layer (slower; ~1–2s):
-curl http://localhost:8099/health/deep
-```
-
-Now point your existing `pentatonic-memory` SDK client at `http://localhost:8099` — no code change.
-
-### Picking a mode
-
-Both modes share the same `docker compose up -d` and the same HTTP API. Switch via one env var on the `compat` container:
-
-```bash
-# Fast path — L6-only, 84.6% / 110ms p50  (default)
-BYPASS_L2_PROXY=1 docker compose up -d compat
-
-# Max accuracy — full 7-layer L2 fusion, 85.7% / 1241ms p50
-BYPASS_L2_PROXY=0 docker compose up -d compat
-```
-
-| Mode | Mean acc | p50 | When to use |
-|---|---|---|---|
-| L6-only (default) | 84.6% | 110ms | Live agent calls, latency-sensitive paths |
-| 7-layer fusion | 85.7% | 1241ms | Offline batch retrieval, accuracy-graded eval, multi-hop entity queries |
-
-Both modes populate all 7 layers on `/store-batch` (since v0.2). The mode flag only changes which layers the **search** path queries.
-
-## API compatibility
-
-| Endpoint | v0.5 | This package | Notes |
-|---|---|---|---|
-| `POST /store` | ✅ | ✅ | Same request/response shape |
-| `POST /search` | ✅ | ✅ | Same request/response shape; ?mode=vector/text both supported |
-| `GET /health` | ✅ | ✅ | Returns aggregate health across all 7 layers + nv-embed reachability + per-layer `memories` counts |
-| `GET /health/deep` | ❌ | ✅ | NEW (v0.8.4): synthetic embed → write → search round-trip per layer. Slower (~1–2s); for ops/monitoring on demand. |
-| `POST /store-batch` | ❌ | ✅ | Batch-ingest N records in one HTTP call (30-50× faster) |
-| `POST /forget` | ❌ (regression) | ✅ | Restored from v0.4.x; supports `metadata_contains` filter |
-| `POST /aggregate` | ❌ | ✅ | NEW (v0.8.x): typed-Person aggregation over the L3 graph — counts COMMUNICATED edges per channel via the ChannelStat denormalisation |
-
-Migration: see [`MIGRATION.md`](MIGRATION.md) for the wire-format walkthrough.
-
-

package/packages/memory-engine/bench/README.md

@@ -1,99 +0,0 @@
-# Benchmark Results
-
-All runs were conducted on **DGX Spark GB10** (10-core ARM CPU, 128GB unified memory, NVIDIA GB10 SoC) on **2026-04-27**.
-
-## Summary
-
-| Stack | Mean accuracy | Mean p50 latency | Coverage |
-|---|---|---|---|
-| **pentatonic-memory-engine — 7-layer fusion** | **85.7%** | 1241ms | 6/6 |
-| **pentatonic-memory-engine — L6-only fast path** | **84.6%** | 110ms | 6/6 |
-| pentatonic-memory v0.4.7 (current canonical OSS) | 38.8% | 27ms | 6/6 |
-| pentatonic-memory v0.5.6 (latest OSS) | 17.6% | 33ms | 6/6 |
-
-Both pentatonic-memory baselines were freshly purged before the run (no stale data pollution). Both modes of `pentatonic-memory-engine` ship in the same docker-compose package — one env var (`BYPASS_L2_PROXY`) toggles between fast path and 7-layer fusion.
-
-## Per-bench breakdown
-
-| Bench | 7-layer | L6-only | v0.4.7 | v0.5.6 |
-|---|---|---|---|---|
-| agent-coding | 100.0% (22/22) | 100.0% (22/22) | 63.6% (14/22) | 9.1% (2/22) |
-| chat-recall | 100.0% (16/16) | 100.0% (16/16) | 12.5% (2/16) | 0.0% (0/16) |
-| circular-economy | 76.0% (19/25) | 80.0% (20/25) | 40.0% (10/25) | 32.0% (8/25) |
-| customer-support | 75.0% (15/20) | 70.0% (14/20) | 25.0% (5/20) | 5.0% (1/20) |
-| marketplace-ops | 80.0% (16/20) | 80.0% (16/20) | 25.0% (5/20) | 15.0% (3/20) |
-| product-catalogue | 83.3% (15/18) | 77.8% (14/18) | 66.7% (12/18) | 44.4% (8/18) |
-| **MEAN** | **85.7%** | **84.6%** | **38.8%** | **17.6%** |
-
-### When does 7-layer fusion help?
-
-Layer-by-layer effect over L6-only:
-
-- **+5.6pp on product-catalogue** — KG entity matching pulls related SKUs / materials in one hop; L0 BM25 catches part numbers that vector search alone misses.
-- **+5.0pp on customer-support** — Multi-hop entity resolution (customer → order → policy) lifts retrieval where pure semantic search loses the relationship.
-- **Tied on agent-coding, chat-recall, marketplace-ops** — L6 already saturated (100%, 100%, 80%); extra layers add nothing.
-- **−4.0pp on circular-economy** — Extra layers add noise on this sustainability corpus; L6's reranker alone is the better signal.
-
-Net: +1.1pp accuracy at 11× latency cost. Use 7-layer for accuracy-graded eval and offline batch retrieval; stay on L6-only for live agent calls.
-
-## Bench corpora
-
-The 6 benches use commerce-domain corpora that overlap Pentatonic's actual product space:
-
-- `agent-coding` — 22 questions over 22 docs (TES + agent SDK source/docs)
-- `chat-recall` — 16 questions over a 16-turn chat transcript
-- `circular-economy` — 25 questions over 25 sustainability docs
-- `customer-support` — 20 questions over a 20-doc support knowledge base
-- `marketplace-ops` — 20 questions over 20 marketplace listings
-- `product-catalogue` — 18 questions over an 18-SKU product catalogue
-
-All grading uses **substring match**: a hit is correct if the retrieved text contains the literal answer string. This is the strictest grading mode and the closest analogue to "did the SDK return a chunk that actually answers the question."
-
-## Reproduce
-
-```bash
-# Bring up the engine
-cd pentatonic-memory-engine && docker compose up -d
-
-# Wait for healthy
-until curl -sf http://localhost:8099/health | grep -q '"status":"ok"'; do sleep 2; done
-
-# Set up the bench harness
-cd ~/pentatonic-memory-bench
-pip install -e .
-
-# Run the L6-only fast path (default)
-PENTATONIC_MEMORY_URL=http://localhost:8099 \
-  python -m pentatonic_bench.cli run -b chat-recall -s pentatonic-memory -k 3
-
-# Run the 7-layer fusion (toggle BYPASS_L2_PROXY=0 + restart compat)
-BYPASS_L2_PROXY=0 docker compose up -d --force-recreate compat
-PENTATONIC_MEMORY_URL=http://localhost:8099 \
-  python -m pentatonic_bench.cli run -b chat-recall -s pentatonic-memory -k 3
-```
-
-## Comparison to other open-source memory stacks
-
-| Stack | Mean acc | Mean p50 | Notes |
-|---|---|---|---|
-| 🥇 **pentatonic-memory-engine — 7-layer** | **85.7%** | **1241ms** | This package, full L2 fusion |
-| 🥈 **pentatonic-memory-engine — L6-only** | **84.6%** | **110ms** | This package, fast path |
-| 🥉 langmem | 83.0% | 121ms | LangChain's in-process memory; no HTTP/embedding overhead |
-| cognee | 82.1% | 192ms | Graph + vector hybrid, KG-first |
-| single-store baseline | 79.3% | 110ms | Single vector store + sentence-transformers |
-| llamaindex | 79.3% | 203ms | LlamaIndex with default config |
-| bm25-baseline | 75.9% | 0ms | Pure SQLite FTS5, no embeddings |
-| pentatonic-memory v0.4.7 | 38.8% | 27ms | Current canonical OSS |
-| graphiti | 30.1% | 156ms | Graph-only, no vector |
-| pentatonic-memory v0.5.6 | 17.6% | 33ms | Latest OSS |
-
-Engine beats every other OSS memory stack on accuracy in both modes. The L6-only fast path matches langmem's latency profile while delivering +1.6pp accuracy. The 7-layer mode is the genuine #1 on accuracy across all benchmarked stacks.
-
-## Raw scorecards
-
-- `scorecards-engine-via-docker/` — 6 JSON scorecards, L6-only fast path (84.6% mean / 110ms p50)
-- `scorecards-engine-via-l2-7-layer-populated/` — 6 JSON scorecards, full 7-layer fusion (85.7% mean / 1241ms p50)
-- `scorecards-engine-via-l2-empty-layers/` — earlier experiment, 7-layer with empty L0/L4-qmd/L3 (82.1%, rolled back; superseded by populated 7-layer)
-- `scorecards-engine-via-shim/` — earlier experiment, shim-direct ingestion path
-- `scorecards-engine/` — initial bench (1183ms, before L6-only optimisation)
-- `scorecards-pentatonic-baseline/` — 12 JSON scorecards (6 per stack) for the v0.4.7 and v0.5.6 baselines