agentfootprint 9.2.0 → 9.3.0

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

@@ -0,0 +1,243 @@
+/**
+ * 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;