agentfootprint 9.2.0 → 9.3.0

package/dist/memory/embedding/loadRelevant.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.__resetEmptyCorpusWarnings = exports.loadRelevant = void 0;
 const index_js_1 = require("../identity/index.js");
+const capability_js_1 = require("../store/capability.js");
 const fnv1a_js_1 = require("../../lib/fnv1a.js");
 const provenance_js_1 = require("../retrieval/provenance.js");
 const topK_js_1 = require("../retrieval/topK.js");
@@ -37,7 +38,17 @@ function loadRelevant(config) {
     const { store, embedder } = config;
     if (!store.search) {
         throw new Error('loadRelevant: the configured store does not implement search(). ' +
-            'Use a vector-capable adapter (InMemoryStore, pgvector, Pinecone, ...).');
+            'Use a store that can retrieve (InMemoryStore, sqliteVectorStore, pgVectorStore, ' +
+            's3VectorsStore, ...).');
+    }
+    // Fail-loud at STAGE BUILD time, as this stage has always done for a store
+    // with no `search()`: a retriever with no embedder over a store that ranks
+    // vectors is a config bug, not a runtime condition, and its symptom would be
+    // an empty answer.
+    if (!embedder && (0, capability_js_1.resolveRankingMode)(store, 'loadRelevant') !== 'server-text') {
+        throw new Error('loadRelevant: no `embedder` was configured, and this store does not declare ' +
+            "`ranksBy: 'server-text'`. Something has to turn the query into a vector before a " +
+            'vector-ranking store can answer it.');
     }
     const queryFrom = config.queryFrom ?? defaultQueryFrom;
     // The shorthand and the strategy are two spellings of one rule; the
@@ -80,23 +91,30 @@ function loadRelevant(config) {
             return;
         }
         const signal = scope.$getEnv?.()?.signal;
-        const embedStartedAt = Date.now();
-        const queryVec = (await embedder.embed({
-            text,
-            ...(signal ? { signal } : {}),
-        }));
-        // The QUERY-time half of the two-phase cost model (8.9.0): one embedding
-        // per retrieval, scaling with traffic rather than with corpus size. Paired
-        // with the `'document'` side in `embedMessages`, this is what makes the
-        // cost of a corpus a number you can read rather than one you estimate.
-        (0, emitEmbedding_js_1.emitEmbedding)(scope, {
-            model: config.embedderId ?? embedder.id ?? 'unknown',
-            provider: 'custom',
-            inputKind: 'query',
-            dimension: queryVec.length,
-            count: 1,
-            durationMs: Date.now() - embedStartedAt,
-        });
+        // No embedder means a store that ranks the TEXT server-side: there is no
+        // vector to make, so none is made, none is billed, and no embedding event
+        // is emitted. `[]` is what the port's `query` argument honestly is here,
+        // and `options.text` below is the query such a store actually reads.
+        let queryVec = [];
+        if (embedder) {
+            const embedStartedAt = Date.now();
+            queryVec = (await embedder.embed({
+                text,
+                ...(signal ? { signal } : {}),
+            }));
+            // The QUERY-time half of the two-phase cost model (8.9.0): one embedding
+            // per retrieval, scaling with traffic rather than with corpus size. Paired
+            // with the `'document'` side in `embedMessages`, this is what makes the
+            // cost of a corpus a number you can read rather than one you estimate.
+            (0, emitEmbedding_js_1.emitEmbedding)(scope, {
+                model: config.embedderId ?? embedder.id ?? 'unknown',
+                provider: 'custom',
+                inputKind: 'query',
+                dimension: queryVec.length,
+                count: 1,
+                durationMs: Date.now() - embedStartedAt,
+            });
+        }
         // store.search optional on MemoryStore but required when an embedder
         // is configured (validated upstream by defineMemory).
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion

package/dist/memory/embedding/loadRelevant.js.map

@@ -1 +1 @@
-{"version":3,"file":"loadRelevant.js","sourceRoot":"","sources":["../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loadRelevant.js","sourceRoot":"","sources":["../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"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"}

package/dist/memory/pipeline/semantic.js

@@ -55,7 +55,7 @@ function semanticPipeline(config) {
     }
     const loadConfig = {
         store: config.store,
-        embedder: config.embedder,
+        ...(config.embedder !== undefined && { embedder: config.embedder }),
         ...(config.embedderId !== undefined && { embedderId: config.embedderId }),
         ...(config.k !== undefined && { k: config.k }),
         ...(config.minScore !== undefined && { minScore: config.minScore }),
@@ -73,10 +73,6 @@ function semanticPipeline(config) {
         ...(config.formatFooter !== undefined && { footer: config.formatFooter }),
         ...(config.flavor !== undefined && { flavor: config.flavor }),
     };
-    const embedConfig = {
-        embedder: config.embedder,
-        ...(config.embedderId !== undefined && { embedderId: config.embedderId }),
-    };
     const writeConfig = {
         store: config.store,
         ...(config.writeTier && { tier: config.writeTier }),
@@ -89,6 +85,16 @@ function semanticPipeline(config) {
         .addFunction('Format', (0, formatDefault_js_1.formatDefault)(formatConfig), 'format-default', 'Render selected entries as a system message')
         .build();
     // ── Write subflow: EmbedMessages → WriteMessages
+    //
+    // Built only when there is an embedder to build it around. Without one the
+    // pipeline is read-only by construction rather than by a flag — nothing to
+    // disable later by accident, and no stage in the chart that does nothing.
+    if (config.embedder === undefined)
+        return { read };
+    const embedConfig = {
+        embedder: config.embedder,
+        ...(config.embedderId !== undefined && { embedderId: config.embedderId }),
+    };
     const write = (0, footprintjs_1.flowChart)('EmbedMessages', (0, embedMessages_js_1.embedMessages)(embedConfig), 'embed-messages', { description: 'Embed newMessages into per-message vectors for vector search' })
         .addFunction('WriteMessages', (0, writeMessages_js_1.writeMessages)(writeConfig), 'write-messages', 'Batch-persist messages with embeddings via store.putMany')
         .build();

package/dist/memory/pipeline/semantic.js.map

@@ -1 +1 @@
-{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../../src/memory/pipeline/semantic.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"semantic.js","sourceRoot":"","sources":["../../../src/memory/pipeline/semantic.ts"],"names":[],"mappings":"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"}

package/dist/memory/store/capability.js

@@ -1,18 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertServesVectors = void 0;
+exports.assertServesVectors = exports.resolveRankingMode = void 0;
 /** The stores this library ships that DO rank the vectors they were given. */
-const VECTOR_CAPABLE = 'InMemoryStore (dev/tests) or sqliteVectorStore (durable, one file)';
+const VECTOR_CAPABLE = 'InMemoryStore (dev/tests), sqliteVectorStore (durable, one file), pgVectorStore ' +
+    '(Postgres + pgvector) or s3VectorsStore (Amazon S3 Vectors)';
+/**
+ * The ranking mode a store DECLARES, with a contradiction refused by name.
+ *
+ * Two members answer two questions ({@link MemoryStore.supportsVectorSearch}
+ * "can you serve my vectors back?" and {@link MemoryStore.ranksBy} "what query
+ * form does your search take?"), and a store may state either, both, or
+ * neither. Both, disagreeing, is the one case that cannot be resolved: there is
+ * no reading of `{ supportsVectorSearch: true, ranksBy: 'server-text' }` that
+ * is not somebody's bug, and picking a winner would encode a guess about which
+ * line was the mistake. Refused — the same law that refuses `topK` beside
+ * `retrieval`.
+ *
+ * @returns `'vector'` | `'server-text'` | `undefined` (undeclared — the state
+ *          every adapter written before 9.3.0 is in, and the one that must
+ *          change nothing).
+ * @throws when the two declarations contradict each other.
+ */
+function resolveRankingMode(store, caller) {
+    const declared = store.ranksBy;
+    const servesVectors = store.supportsVectorSearch;
+    if (declared === undefined) {
+        // A bare `supportsVectorSearch: true` is a store saying it ranks the
+        // vectors it was given, which IS `'vector'` — read it as one, so a
+        // pre-9.3.0 adapter gets the new behaviour without a new line. A bare
+        // `false` says only that it cannot serve them back, not how it ranks, so
+        // it stays undeclared here.
+        return servesVectors === true ? 'vector' : undefined;
+    }
+    if (declared === 'vector' && servesVectors === false) {
+        throw new Error(contradiction(store, caller, 'vector', false));
+    }
+    if (declared === 'server-text' && servesVectors === true) {
+        throw new Error(contradiction(store, caller, 'server-text', true));
+    }
+    return declared;
+}
+exports.resolveRankingMode = resolveRankingMode;
+function contradiction(store, caller, ranksBy, supportsVectorSearch) {
+    const name = storeName(store);
+    return (`${caller}: \`${name}\` declares \`ranksBy: '${ranksBy}'\` and ` +
+        `\`supportsVectorSearch: ${String(supportsVectorSearch)}\`, and those two cannot both be ` +
+        `true.\n` +
+        `  \`ranksBy: 'vector'\` means search() ranks the embeddings you wrote, which is exactly ` +
+        `what \`supportsVectorSearch: true\` claims; \`'server-text'\` means the backend ranks ` +
+        `text on its own side, which is exactly what \`false\` admits.\n` +
+        `  Fix:  keep ONE of them. A local vector backend declares ` +
+        `\`ranksBy: 'vector'\` (or nothing but \`supportsVectorSearch: true\`); a managed ` +
+        `text-ranking backend declares \`ranksBy: 'server-text'\` and \`supportsVectorSearch: false\`.\n` +
+        `  This refuses rather than picking a winner — either line could be the mistake, and ` +
+        `guessing which would silently decide whether your queries get embedded.`);
+}
 /**
  * Refuse a store that has declared it cannot rank the vectors it is given.
  *
  * @param store  the store the caller passed.
  * @param caller the function name to put in the message — the call the
  *               reader actually wrote, not this helper.
- * @throws when `store.supportsVectorSearch === false`. Never throws on a
- *         store that declares nothing.
+ * @throws when `store.supportsVectorSearch === false`, when it declares
+ *         `ranksBy: 'server-text'`, or when the two declarations contradict.
+ *         Never throws on a store that declares nothing.
  */
 function assertServesVectors(store, caller) {
+    // A contradiction is refused here too — a corpus builder is usually the
+    // FIRST call a new store meets, and it is the cheapest place to find out.
+    const mode = resolveRankingMode(store, caller);
+    if (mode === 'server-text') {
+        throw new Error(`${caller}: \`${storeName(store)}\` declares \`ranksBy: 'server-text'\`, so indexing a ` +
+            `corpus into it would report success and retrieve nothing.\n` +
+            `  It embeds and ranks on the BACKEND's side, over a population the backend derived ` +
+            `itself — the vectors written here would be stored and never read.\n` +
+            `  Fix:  index into a vector-ranking store — ${VECTOR_CAPABLE}.\n` +
+            `  Or:   let the backend do its own ingestion (its console, its API), and point ` +
+            `\`defineRAG\` at it with NO embedder — a server-text store takes the question as ` +
+            `words, so there is nothing for this library to embed.`);
+    }
     if (store.supportsVectorSearch !== false)
         return;
     const name = storeName(store);

package/dist/memory/store/capability.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/memory/store/capability.ts"],"names":[],"mappings":";;;AA2BA,8EAA8E;AAC9E,MAAM,cAAc,GAAG,oEAAoE,CAAC;AAE5F;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAAC,KAAkB,EAAE,MAAc;IACpE,IAAI,KAAK,CAAC,oBAAoB,KAAK,KAAK;QAAE,OAAO;IACjD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9B,wEAAwE;IACxE,wEAAwE;IACxE,4DAA4D;IAC5D,MAAM,GAAG,GACP,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU;QAChC,CAAC,CAAC,iFAAiF;YACjF,oDAAoD;QACtD,CAAC,CAAC,6EAA6E;YAC7E,cAAc,CAAC;IACrB,MAAM,IAAI,KAAK,CACb,GAAG,MAAM,OAAO,IAAI,mEAAmE;QACrF,wCAAwC;QACxC,kDAAkD,GAAG,gCAAgC;QACrF,mBAAmB;QACnB,+CAA+C,cAAc,wBAAwB;QACrF,oEAAoE;QACpE,YAAY,IAAI,yDAAyD;QACzE,gFAAgF,CACnF,CAAC;AACJ,CAAC;AAtBD,kDAsBC;AAED,oFAAoF;AACpF,SAAS,SAAS,CAAC,KAAkB;IACnC,MAAM,IAAI,GAAI,KAA6C,CAAC,WAAW,CAAC;IACxE,MAAM,IAAI,GAAG,OAAO,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC;AAC9E,CAAC"}
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/memory/store/capability.ts"],"names":[],"mappings":"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"}

package/dist/memory/store/index.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CORPUS_BUNDLE_FORMAT = exports.bundleEntryToMemoryEntry = exports.assertCorpusBundle = exports.staticVectorStore = exports.InMemoryStore = void 0;
+exports.CORPUS_BUNDLE_FORMAT = exports.bundleEntryToMemoryEntry = exports.assertCorpusBundle = exports.staticVectorStore = exports.resolveRankingMode = exports.assertServesVectors = exports.InMemoryStore = void 0;
 var InMemoryStore_js_1 = require("./InMemoryStore.js");
 Object.defineProperty(exports, "InMemoryStore", { enumerable: true, get: function () { return InMemoryStore_js_1.InMemoryStore; } });
+// The declared-capability readers (9.3.0). `resolveRankingMode` is exported so
+// an adapter author can check their own two declarations agree without waiting
+// for a corpus builder to tell them.
+var capability_js_1 = require("./capability.js");
+Object.defineProperty(exports, "assertServesVectors", { enumerable: true, get: function () { return capability_js_1.assertServesVectors; } });
+Object.defineProperty(exports, "resolveRankingMode", { enumerable: true, get: function () { return capability_js_1.resolveRankingMode; } });
 var staticVectorStore_js_1 = require("./staticVectorStore.js");
 Object.defineProperty(exports, "staticVectorStore", { enumerable: true, get: function () { return staticVectorStore_js_1.staticVectorStore; } });
 Object.defineProperty(exports, "assertCorpusBundle", { enumerable: true, get: function () { return staticVectorStore_js_1.assertCorpusBundle; } });

package/dist/memory/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/store/index.ts"],"names":[],"mappings":";;;AASA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,+DAQgC;AAP9B,yHAAA,iBAAiB,OAAA;AACjB,0HAAA,kBAAkB,OAAA;AAClB,gIAAA,wBAAwB,OAAA;AACxB,4HAAA,oBAAoB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/store/index.ts"],"names":[],"mappings":";;;AASA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,+EAA+E;AAC/E,+EAA+E;AAC/E,qCAAqC;AACrC,iDAA0E;AAAjE,oHAAA,mBAAmB,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAChD,+DAQgC;AAP9B,yHAAA,iBAAiB,OAAA;AACjB,0HAAA,kBAAkB,OAAA;AAClB,gIAAA,wBAAwB,OAAA;AACxB,4HAAA,oBAAoB,OAAA"}

package/dist/memory-providers.js

@@ -2,9 +2,9 @@
 /**
  * memory-providers — memory store adapters.
  *
- * RedisStore, AgentCoreStore, and future stores (DynamoDB, Postgres,
- * Pinecone, …) all live here — a new store adds an export, never a new
- * import path.
+ * RedisStore, AgentCoreStore, sqliteVectorStore, pgVectorStore, s3VectorsStore
+ * and future stores (DynamoDB, Pinecone, …) all live here — a new store adds an
+ * export, never a new import path.
  *
  * Pattern: Adapter (GoF) — each store translates the `MemoryStore`
  *          interface onto a specific backend (Redis, DynamoDB-style
@@ -22,7 +22,7 @@
  * symbols, one door. Import from the door.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BedrockAgentMemory = exports.SqliteUnavailableError = exports.EmbedderMismatchError = exports.UnreadableIndexFileError = exports.sqliteVectorStore = exports.UnreadableMemoryEntryError = exports.AgentCoreStore = exports.RedisStore = void 0;
+exports.BedrockAgentMemory = exports.s3VectorsStore = exports.PgVectorSchemaError = exports.pgVectorStore = exports.EmbedderMismatchError = exports.SqliteUnavailableError = exports.UnreadableIndexFileError = exports.sqliteVectorStore = exports.UnreadableMemoryEntryError = exports.AgentCoreStore = exports.RedisStore = void 0;
 // Lazy-required peer-dep stores. Both adapters defer their vendor SDK
 // `require()` to constructor time; importing this barrel doesn't load
 // `ioredis` or `@aws-sdk/client-bedrock-agent-runtime`.
@@ -38,11 +38,28 @@ Object.defineProperty(exports, "UnreadableMemoryEntryError", { enumerable: true,
 var sqliteVector_js_1 = require("./adapters/memory/sqliteVector.js");
 Object.defineProperty(exports, "sqliteVectorStore", { enumerable: true, get: function () { return sqliteVector_js_1.sqliteVectorStore; } });
 Object.defineProperty(exports, "UnreadableIndexFileError", { enumerable: true, get: function () { return sqliteVector_js_1.UnreadableIndexFileError; } });
-Object.defineProperty(exports, "EmbedderMismatchError", { enumerable: true, get: function () { return sqliteVector_js_1.EmbedderMismatchError; } });
 // The SAME refusal `sqliteSessions` raises for the same missing module — one
 // class, so catching it does not require knowing which store was being built.
 var sqliteUnavailable_js_1 = require("./lib/sqliteUnavailable.js");
 Object.defineProperty(exports, "SqliteUnavailableError", { enumerable: true, get: function () { return sqliteUnavailable_js_1.SqliteUnavailableError; } });
+// ONE refusal for every store that can tell a vector met an index built by a
+// different embedder (9.3.0). It lived in sqliteVector.ts from 8.9.0; when
+// pgVectorStore and s3VectorsStore learned the same check it moved to lib/, so
+// `catch (e) { if (e instanceof EmbedderMismatchError) }` cannot depend on
+// which store threw. The old import path still works.
+var embedderMismatch_js_1 = require("./lib/embedderMismatch.js");
+Object.defineProperty(exports, "EmbedderMismatchError", { enumerable: true, get: function () { return embedderMismatch_js_1.EmbedderMismatchError; } });
+// Postgres + pgvector: the corpus beside the application's own data, inheriting
+// its backups, failover and access control. `pg` is lazy-required at the first
+// call — pass `client` to reuse the pool your app already has.
+var pgVector_js_1 = require("./adapters/memory/pgVector.js");
+Object.defineProperty(exports, "pgVectorStore", { enumerable: true, get: function () { return pgVector_js_1.pgVectorStore; } });
+Object.defineProperty(exports, "PgVectorSchemaError", { enumerable: true, get: function () { return pgVector_js_1.PgVectorSchemaError; } });
+// Amazon S3 Vectors: a durable corpus with nothing to run, that can be added to
+// from a cron job rather than at the next deploy. Lazy-requires
+// `@aws-sdk/client-s3vectors` at the first call.
+var s3Vectors_js_1 = require("./adapters/memory/s3Vectors.js");
+Object.defineProperty(exports, "s3VectorsStore", { enumerable: true, get: function () { return s3Vectors_js_1.s3VectorsStore; } });
 // Read-only reader for the legacy Bedrock Agents auto session-summary memory.
 // NOT a MemoryStore (Bedrock owns the writes) — see the class docstring.
 var bedrockAgentMemory_js_1 = require("./adapters/memory/bedrockAgentMemory.js");

package/dist/memory-providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../src/memory-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,uDAKoC;AAJlC,sGAAA,UAAU,OAAA;AAMZ,+DAOwC;AANtC,8GAAA,cAAc,OAAA;AACd,0HAAA,0BAA0B,OAAA;AAO5B,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,mDAAmD;AACnD,qEAS2C;AARzC,oHAAA,iBAAiB,OAAA;AACjB,2HAAA,wBAAwB,OAAA;AACxB,wHAAA,qBAAqB,OAAA;AAQvB,6EAA6E;AAC7E,8EAA8E;AAC9E,mEAAoE;AAA3D,8HAAA,sBAAsB,OAAA;AAE/B,8EAA8E;AAC9E,yEAAyE;AACzE,iFAKiD;AAJ/C,2HAAA,kBAAkB,OAAA"}
+{"version":3,"file":"memory-providers.js","sourceRoot":"","sources":["../src/memory-providers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AAEH,sEAAsE;AACtE,sEAAsE;AACtE,wDAAwD;AACxD,uDAKoC;AAJlC,sGAAA,UAAU,OAAA;AAMZ,+DAOwC;AANtC,8GAAA,cAAc,OAAA;AACd,0HAAA,0BAA0B,OAAA;AAO5B,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,mDAAmD;AACnD,qEAQ2C;AAPzC,oHAAA,iBAAiB,OAAA;AACjB,2HAAA,wBAAwB,OAAA;AAQ1B,6EAA6E;AAC7E,8EAA8E;AAC9E,mEAAoE;AAA3D,8HAAA,sBAAsB,OAAA;AAE/B,6EAA6E;AAC7E,2EAA2E;AAC3E,+EAA+E;AAC/E,2EAA2E;AAC3E,sDAAsD;AACtD,iEAAkE;AAAzD,4HAAA,qBAAqB,OAAA;AAE9B,gFAAgF;AAChF,+EAA+E;AAC/E,+DAA+D;AAC/D,6DASuC;AARrC,4GAAA,aAAa,OAAA;AACb,kHAAA,mBAAmB,OAAA;AASrB,gFAAgF;AAChF,gEAAgE;AAChE,iDAAiD;AACjD,+DAMwC;AALtC,8GAAA,cAAc,OAAA;AAOhB,8EAA8E;AAC9E,yEAAyE;AACzE,iFAKiD;AAJ/C,2HAAA,kBAAkB,OAAA"}

package/dist/types/adapters/memory/pgVector.d.ts

@@ -0,0 +1,244 @@
+/**
+ * adapters/memory/pgVector — the target our own port has named since 2.x.
+ *
+ * `MemoryStore`'s docstring has listed the backends it was designed for from
+ * the beginning — *"Every storage backend (InMemory, Redis, DynamoDB,
+ * **Postgres**, Bedrock AgentCore) implements this interface"* — and named the
+ * query, twice, in the places an implementer would look: *"**Postgres**:
+ * multi-row INSERT … ON CONFLICT DO UPDATE"* for `putMany`, *"**pgvector**:
+ * `ORDER BY embedding <=> query LIMIT k`"* for `search`. Every one of those
+ * sentences was true about the design and false about the shipped package.
+ * This is the adapter that makes them the same sentence.
+ *
+ * It matters more than one row in a table of backends. Postgres is the database
+ * most teams already run, `pgvector` is an extension away, and a corpus that
+ * lives beside the application's own data inherits its backups, its failover,
+ * its access control and its migrations. `sqliteVectorStore` is one machine;
+ * `s3VectorsStore` is serverless and eventually consistent; this is the one for
+ * a fleet that already has a database.
+ *
+ * ── The table, and why this does not create it ──────────────────────────────
+ * A `vector(N)` column fixes N at creation, and N is a fact about your
+ * embedder. Creating the table implicitly would pick that number — and the
+ * index type, and the operator class — on your behalf, in a migration you never
+ * reviewed, in a database whose DDL is usually somebody's job. So the schema is
+ * yours to run, and this store REFUSES a table that is missing rather than
+ * silently answering "no matches" against nothing:
+ *
+ * ```sql
+ * CREATE EXTENSION IF NOT EXISTS vector;
+ *
+ * -- 1024 = your embedder's dimensions. bedrockEmbedder() default: 1024.
+ * --        openaiEmbedder() default: 1536. staticEmbedder(): 256.
+ * CREATE TABLE af_vectors (
+ *   namespace        TEXT    NOT NULL,
+ *   id               TEXT    NOT NULL,
+ *   value            JSONB   NOT NULL,
+ *   metadata         JSONB,
+ *   embedding        vector(1024),
+ *   embedder_fp      TEXT,
+ *   version          INTEGER NOT NULL,
+ *   created_at       BIGINT  NOT NULL,
+ *   updated_at       BIGINT  NOT NULL,
+ *   last_accessed_at BIGINT  NOT NULL,
+ *   access_count     INTEGER NOT NULL,
+ *   ttl              BIGINT,
+ *   tier             TEXT,
+ *   source           JSONB,
+ *   embedding_model  TEXT,
+ *   PRIMARY KEY (namespace, id)
+ * );
+ *
+ * -- Cosine, because that is the score this port reports and every threshold
+ * -- in this library is calibrated on. Match the operator class to the metric.
+ * CREATE INDEX af_vectors_hnsw ON af_vectors
+ *   USING hnsw (embedding vector_cosine_ops);
+ * CREATE INDEX af_vectors_ns ON af_vectors (namespace);
+ *
+ * -- Recognition (`seen`/`recordSignature`), usefulness feedback, and the
+ * -- per-namespace embedder fingerprint. Small, and each one is a port method
+ * -- that would otherwise have to be refused.
+ * CREATE TABLE af_signatures (
+ *   namespace TEXT NOT NULL, signature TEXT NOT NULL,
+ *   PRIMARY KEY (namespace, signature)
+ * );
+ * CREATE TABLE af_feedback (
+ *   namespace TEXT NOT NULL, id TEXT NOT NULL,
+ *   total DOUBLE PRECISION NOT NULL, count INTEGER NOT NULL,
+ *   PRIMARY KEY (namespace, id)
+ * );
+ * CREATE TABLE af_index_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+ * ```
+ *
+ * Every table and column name above is an OPTION with that value as its
+ * default, so this drops into a schema that already has naming conventions —
+ * see {@link PgVectorStoreOptions}. Identifiers are validated and quoted; a
+ * name that is not a plain SQL identifier is refused rather than interpolated.
+ *
+ * ── Cosine, and only cosine ─────────────────────────────────────────────────
+ * `search` is `1 - (embedding <=> $query::vector)` — pgvector's cosine
+ * DISTANCE, converted to the cosine SIMILARITY the port reports and
+ * `defineRAG`'s 0.7 default is calibrated on. `<->` (L2) and `<#>` (inner
+ * product) are deliberately not options: their ranges are not that range, and a
+ * number that reads like a cosine and is not one is the failure mode the whole
+ * fingerprint machinery exists to prevent. Build the HNSW index with
+ * `vector_cosine_ops` so the operator and the index agree — with the wrong
+ * operator class the query still returns the right answer, slowly, by scanning.
+ *
+ * ── One statement at a time, on purpose ─────────────────────────────────────
+ * The client here is anything with `query()` — a `pg.Pool` is the expected one,
+ * and a Pool hands each `query()` its own connection. `BEGIN` on one and the
+ * next statement on another is a transaction that silently is not one, so this
+ * adapter never writes multi-statement transactions. Everything that must be
+ * atomic is ONE statement: `putMany` is one multi-row upsert, `putIfVersion` is
+ * one conditional upsert, `forget` is one statement with CTEs across all four
+ * tables. That is a constraint that made the code better.
+ *
+ * ── Lazy peer dependency ────────────────────────────────────────────────────
+ * `pg` is an OPTIONAL peer dependency, required at construction time. Importing
+ * `agentfootprint/memory` costs nothing for consumers who never build one of
+ * these. Pass `client` to reuse the pool your app already has — which is the
+ * recommended shape, because a second pool to the same database is a second set
+ * of connections nobody counted.
+ */
+import type { MemoryIdentity } from '../../memory/identity/index.js';
+import type { MemoryStore } from '../../memory/store/types.js';
+/** One result set, as this adapter reads it. */
+export interface PgQueryResult {
+    readonly rows: readonly Record<string, unknown>[];
+}
+/**
+ * The slice of a `pg` client this adapter calls.
+ *
+ * Structural, so a `Pool`, a `Client`, a pgBouncer-fronted wrapper or a test
+ * double all satisfy it without this package taking a hard type dependency on
+ * the optional peer.
+ */
+export interface PgLikeClient {
+    query(text: string, params?: readonly unknown[]): Promise<PgQueryResult>;
+    /** Optional — awaited by {@link PgVectorStore.close} when this store built the pool. */
+    end?(): Promise<void>;
+}
+/** The one constructor this adapter needs out of `pg`. */
+export interface PgSdkModule {
+    readonly Pool?: new (config: {
+        connectionString?: string;
+    }) => PgLikeClient;
+}
+/**
+ * Column names, so this store fits a schema that already has conventions.
+ * Every one defaults to the name in the `CREATE TABLE` above.
+ */
+export interface PgVectorColumns {
+    readonly namespace?: string;
+    readonly id?: string;
+    readonly value?: string;
+    readonly metadata?: string;
+    readonly embedding?: string;
+    readonly embedderFp?: string;
+    readonly version?: string;
+    readonly createdAt?: string;
+    readonly updatedAt?: string;
+    readonly lastAccessedAt?: string;
+    readonly accessCount?: string;
+    readonly ttl?: string;
+    readonly tier?: string;
+    readonly source?: string;
+    readonly embeddingModel?: string;
+}
+export interface PgVectorStoreOptions {
+    /**
+     * Postgres connection string, used only when this store builds its own pool.
+     * Prefer `client` — a second pool to one database is a second set of
+     * connections nobody counted.
+     */
+    readonly connectionString?: string;
+    /** A pre-built `pg.Pool` (or anything with `query`). Recommended. */
+    readonly client?: PgLikeClient;
+    /** Schema the tables live in. Default `'public'`. */
+    readonly schema?: string;
+    /** The vectors table. Default `'af_vectors'`. */
+    readonly table?: string;
+    /** The recognition-set table (`seen`/`recordSignature`). Default `'af_signatures'`. */
+    readonly signaturesTable?: string;
+    /** The usefulness-aggregate table. Default `'af_feedback'`. */
+    readonly feedbackTable?: string;
+    /** The key/value table holding one embedder fingerprint per namespace. Default `'af_index_meta'`. */
+    readonly metaTable?: string;
+    /** Column names inside {@link table}. Each defaults to the documented one. */
+    readonly columns?: PgVectorColumns;
+    /**
+     * Rows per multi-row upsert. Default 500.
+     *
+     * Postgres caps a statement at 65,535 bound parameters and this store binds
+     * 15 per row, so 500 leaves an order of magnitude of headroom. Raising it
+     * trades round-trips for a statement that fails all-or-nothing on a bigger
+     * unit.
+     */
+    readonly batchSize?: number;
+    /** @internal Test injection — skips the `pg` require entirely. */
+    readonly _client?: PgLikeClient;
+    /** @internal Test injection — the `pg` module (exercises the real shim with a mock module). */
+    readonly _pg?: PgSdkModule;
+}
+/** A Postgres-backed vector store, plus the two things it owns beyond the port. */
+export interface PgVectorStore extends MemoryStore {
+    /**
+     * The embedder fingerprint (`'<id>@<dims>'`) a namespace was built with, or
+     * `undefined` when nothing with a vector has been written to it yet.
+     *
+     * Read this before an embedder swap: it is the fact `EmbedderMismatchError`
+     * refuses on, available up front instead of at the first failed write.
+     */
+    fingerprintOf(identity: MemoryIdentity): Promise<string | undefined>;
+    /**
+     * Release the pool, if this store built one. Idempotent. A client you passed
+     * in is yours and is left alone.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Raised when the database is reachable but its schema is not this store's.
+ *
+ * The law `sqliteVectorStore` states for a file, one backend over: **an
+ * unreadable index and an empty one are different facts, and only one of them
+ * is safe to answer with "no matches".** A store that treated a missing table
+ * as an empty corpus would answer every question from the model's own weights
+ * and log nothing.
+ */
+export declare class PgVectorSchemaError extends Error {
+    readonly code: "ERR_PGVECTOR_SCHEMA";
+    /** The schema-qualified table that could not be used. */
+    readonly table: string;
+    /** Columns this store needs and did not find. Empty when the table is absent entirely. */
+    readonly missingColumns: readonly string[];
+    constructor(table: string, missingColumns: readonly string[], detail: string);
+}
+/**
+ * Open a `MemoryStore` over an existing Postgres + pgvector table.
+ *
+ * @throws when `pg` is absent and no `client` was passed.
+ * @throws PgVectorSchemaError on the first call, when the table or a column it
+ *         needs is not there.
+ * @throws EmbedderMismatchError from `put`/`putMany`/`search` when a vector
+ *         meets a namespace built by a different embedder.
+ *
+ * @example  A corpus beside the application's own data
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { defineRAG, indexDocuments } from 'agentfootprint';
+ * import { pgVectorStore } from 'agentfootprint/memory';
+ * import { openaiEmbedder } from 'agentfootprint/providers';
+ *
+ * const store = pgVectorStore({ client: new Pool({ connectionString: process.env.DATABASE_URL }) });
+ * const embedder = openaiEmbedder();
+ *
+ * await indexDocuments(store, embedder, docs, { embedderId: embedder.id });
+ *
+ * const agent = Agent.create({ provider })
+ *   .rag(defineRAG({ id: 'docs', store, embedder, embedderId: embedder.id }))
+ *   .build();
+ * ```
+ */
+export declare function pgVectorStore(options?: PgVectorStoreOptions): PgVectorStore;
+//# sourceMappingURL=pgVector.d.ts.map

package/dist/types/adapters/memory/pgVector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgVector.d.ts","sourceRoot":"","sources":["../../../../src/adapters/memory/pgVector.ts"],"names":[],"mappings":"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"}