@seanhogg/builderforce-memory 2026.7.14 → 2026.9.27

package/dist/vectorstore/MemoryVectorStore.js.map

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

package/dist/vectorstore/RestVectorStore.d.ts

@@ -0,0 +1,79 @@
+/**
+ * vectorstore/RestVectorStore.ts — ONE adapter for every HTTP vector database.
+ *
+ * The vendor-specific part is the {@link VectorDialect}; everything that is the
+ * same everywhere lives here exactly once: auth headers, batching, retry with
+ * backoff, residual filtering, capability emulation, and text hydration for stores
+ * that hold vectors only.
+ *
+ * The residual pass is the part that matters for correctness. When a dialect
+ * cannot push a filter clause down, the store over-fetches and applies the
+ * remaining clauses locally with the SAME evaluator the in-process store uses. A
+ * clause is therefore never dropped — which on an ACL or tenant clause would be a
+ * data leak, and is precisely the failure mode a naive adapter ships with.
+ */
+import { type VectorDialect } from './dialects.js';
+import type { AccessScope, MetadataFilter, UpsertResult, VectorMatch, VectorQuery, VectorRecord, VectorStore } from './types.js';
+export interface RestVectorStoreOptions {
+    /** Dialect id (`evermind`, `qdrant`, `pinecone`, `vertex-ai`) or an instance. */
+    dialect: string | VectorDialect;
+    /** Service root, e.g. `https://my-cluster.qdrant.io`. */
+    baseUrl: string;
+    /** Collection / index / namespace. */
+    collection: string;
+    /** Static headers — API keys, `Authorization: Bearer …`. */
+    headers?: Record<string, string>;
+    /**
+     * Per-request auth, for credentials that expire. On GCP this is where a
+     * Workload-Identity access token goes, refreshed by the caller's token source
+     * rather than cached here — the store must never own a credential lifecycle.
+     */
+    authorize?: () => Promise<Record<string, string>> | Record<string, string>;
+    /** Dialect-specific deployment values (`index`, `indexEndpoint`, `deployedIndexId`, …). */
+    options?: Record<string, string>;
+    /** Records per upsert request. Default 100. */
+    batchSize?: number;
+    /** Retries on 429/5xx/network failure. Default 2. */
+    maxRetries?: number;
+    /** Base backoff in ms, doubled per attempt. Default 200. */
+    retryBackoffMs?: number;
+    /** Over-fetch multiplier when a residual filter must be applied locally. Default 4. */
+    residualOverfetch?: number;
+    /**
+     * Supplies chunk text for dialects that store vectors only (Vertex AI). In a
+     * GCP reference architecture this reads the chunk table from Firestore or
+     * BigQuery keyed by the same ids the index holds.
+     */
+    textResolver?: (ids: readonly string[]) => Promise<Map<string, string>>;
+    /** Injected for test. Default global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injected for test so retry backoff does not really sleep. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class RestVectorStore implements VectorStore {
+    readonly name: string;
+    readonly dialect: VectorDialect;
+    private readonly _baseUrl;
+    private readonly _ctx;
+    private readonly _headers;
+    private readonly _authorize;
+    private readonly _batchSize;
+    private readonly _maxRetries;
+    private readonly _backoffMs;
+    private readonly _overfetch;
+    private readonly _textResolver;
+    private readonly _fetch;
+    private readonly _sleep;
+    constructor(opts: RestVectorStoreOptions);
+    upsert(records: readonly VectorRecord[]): Promise<UpsertResult>;
+    query(query: VectorQuery): Promise<VectorMatch[]>;
+    keywordSearch(query: VectorQuery): Promise<VectorMatch[]>;
+    fetch(ids: readonly string[]): Promise<VectorRecord[]>;
+    delete(ids: readonly string[]): Promise<number>;
+    deleteByFilter(filter: MetadataFilter, scope?: AccessScope): Promise<number>;
+    count(filter?: MetadataFilter, scope?: AccessScope): Promise<number>;
+    /** Shared query path: translate, over-fetch for the residual, filter, hydrate. */
+    private _search;
+    private _send;
+}
+//# sourceMappingURL=RestVectorStore.d.ts.map

package/dist/vectorstore/RestVectorStore.d.ts.map

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

package/dist/vectorstore/RestVectorStore.js

@@ -0,0 +1,170 @@
+/**
+ * vectorstore/RestVectorStore.ts — ONE adapter for every HTTP vector database.
+ *
+ * The vendor-specific part is the {@link VectorDialect}; everything that is the
+ * same everywhere lives here exactly once: auth headers, batching, retry with
+ * backoff, residual filtering, capability emulation, and text hydration for stores
+ * that hold vectors only.
+ *
+ * The residual pass is the part that matters for correctness. When a dialect
+ * cannot push a filter clause down, the store over-fetches and applies the
+ * remaining clauses locally with the SAME evaluator the in-process store uses. A
+ * clause is therefore never dropped — which on an ACL or tenant clause would be a
+ * data leak, and is precisely the failure mode a naive adapter ships with.
+ */
+import { combineFilters, matchesFilter } from './filter.js';
+import { getDialect } from './dialects.js';
+export class RestVectorStore {
+    name;
+    dialect;
+    _baseUrl;
+    _ctx;
+    _headers;
+    _authorize;
+    _batchSize;
+    _maxRetries;
+    _backoffMs;
+    _overfetch;
+    _textResolver;
+    _fetch;
+    _sleep;
+    constructor(opts) {
+        this.dialect = typeof opts.dialect === 'string' ? getDialect(opts.dialect) : opts.dialect;
+        this.name = `rest:${this.dialect.id}`;
+        this._baseUrl = opts.baseUrl.replace(/\/+$/, '');
+        this._ctx = { collection: opts.collection, options: opts.options ?? {} };
+        this._headers = opts.headers ?? {};
+        this._authorize = opts.authorize;
+        this._batchSize = Math.max(1, opts.batchSize ?? 100);
+        this._maxRetries = Math.max(0, opts.maxRetries ?? 2);
+        this._backoffMs = Math.max(0, opts.retryBackoffMs ?? 200);
+        this._overfetch = Math.max(1, opts.residualOverfetch ?? 4);
+        this._textResolver = opts.textResolver;
+        this._fetch = opts.fetchImpl ?? ((...args) => fetch(...args));
+        this._sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    async upsert(records) {
+        let upserted = 0;
+        let skipped = 0;
+        // Batched because every vendor caps request size, and a 10k-record ingest
+        // that fails at record 9,999 must not lose the first 9,998.
+        for (let i = 0; i < records.length; i += this._batchSize) {
+            const batch = records.slice(i, i + this._batchSize);
+            const json = await this._send(this.dialect.upsert(this._ctx, batch));
+            const result = this.dialect.parseUpsert(json, batch.length);
+            upserted += result.upserted;
+            skipped += result.skipped;
+        }
+        return { upserted, skipped };
+    }
+    async query(query) {
+        return this._search(query, (translated, topK) => this.dialect.query(this._ctx, {
+            ...(query.vector ? { vector: query.vector } : {}),
+            ...(query.text ? { text: query.text } : {}),
+            topK,
+            ...(translated !== undefined ? { filter: translated } : {}),
+            includeVectors: query.includeVectors ?? false,
+        }));
+    }
+    async keywordSearch(query) {
+        const text = query.text?.trim();
+        if (!text || !this.dialect.supportsKeywordSearch || !this.dialect.keywordSearch)
+            return [];
+        const build = this.dialect.keywordSearch.bind(this.dialect);
+        return this._search(query, (translated, topK) => build(this._ctx, { text, topK, ...(translated !== undefined ? { filter: translated } : {}) }));
+    }
+    async fetch(ids) {
+        if (ids.length === 0)
+            return [];
+        const json = await this._send(this.dialect.fetch(this._ctx, ids));
+        const records = this.dialect.parseRecords(json);
+        if (this.dialect.storesText || !this._textResolver)
+            return records;
+        const texts = await this._textResolver(records.map((r) => r.id));
+        return records.map((r) => ({ ...r, text: texts.get(r.id) ?? r.text }));
+    }
+    async delete(ids) {
+        if (ids.length === 0)
+            return 0;
+        for (let i = 0; i < ids.length; i += this._batchSize) {
+            await this._send(this.dialect.deleteByIds(this._ctx, ids.slice(i, i + this._batchSize)));
+        }
+        return ids.length;
+    }
+    async deleteByFilter(filter, scope) {
+        const effective = combineFilters(filter, scope);
+        const translated = this.dialect.translateFilter(effective);
+        // Server-side bulk delete is only safe when the dialect can express the
+        // WHOLE predicate. A residual would mean deleting a superset — so the
+        // emulated path (query, filter locally, delete by id) is used instead.
+        if (this.dialect.supportsDeleteByFilter && this.dialect.deleteByFilter && !translated.residual) {
+            await this._send(this.dialect.deleteByFilter(this._ctx, translated.pushed));
+            return -1; // vendor bulk deletes do not report a count
+        }
+        const doomed = await this.query({ filter, ...(scope ? { scope } : {}), topK: 10_000 });
+        return this.delete(doomed.map((m) => m.id));
+    }
+    async count(filter, scope) {
+        const effective = combineFilters(filter, scope);
+        const translated = effective ? this.dialect.translateFilter(effective) : undefined;
+        if (this.dialect.supportsCount && this.dialect.count && this.dialect.parseCount && !translated?.residual) {
+            const json = await this._send(this.dialect.count(this._ctx, translated?.pushed));
+            return this.dialect.parseCount(json);
+        }
+        const matches = await this.query({ ...(filter ? { filter } : {}), ...(scope ? { scope } : {}), topK: 10_000 });
+        return matches.length;
+    }
+    /** Shared query path: translate, over-fetch for the residual, filter, hydrate. */
+    async _search(query, build) {
+        const topK = Math.max(1, query.topK ?? 10);
+        const effective = combineFilters(query.filter, query.scope);
+        const translated = effective ? this.dialect.translateFilter(effective) : undefined;
+        const wanted = translated?.residual ? topK * this._overfetch : topK;
+        const json = await this._send(build(translated?.pushed, wanted));
+        let matches = this.dialect.parseMatches(json);
+        if (translated?.residual) {
+            const residual = translated.residual;
+            matches = matches.filter((m) => matchesFilter(m.metadata, residual));
+        }
+        if (query.minScore !== undefined) {
+            matches = matches.filter((m) => m.score >= query.minScore);
+        }
+        matches = matches.slice(0, topK);
+        if (!this.dialect.storesText && this._textResolver && matches.length > 0) {
+            const texts = await this._textResolver(matches.map((m) => m.id));
+            matches = matches.map((m) => ({ ...m, text: texts.get(m.id) ?? m.text }));
+        }
+        return matches;
+    }
+    async _send(request) {
+        const dynamic = this._authorize ? await this._authorize() : {};
+        const headers = { 'Content-Type': 'application/json', ...this._headers, ...dynamic };
+        const url = `${this._baseUrl}${request.path}`;
+        let lastError;
+        for (let attempt = 0; attempt <= this._maxRetries; attempt++) {
+            if (attempt > 0)
+                await this._sleep(this._backoffMs * 2 ** (attempt - 1));
+            try {
+                const res = await this._fetch(url, {
+                    method: request.method,
+                    headers,
+                    ...(request.body !== undefined ? { body: JSON.stringify(request.body) } : {}),
+                });
+                if (res.ok)
+                    return await res.json().catch(() => ({}));
+                const detail = await res.text().catch(() => '');
+                lastError = new Error(`${this.name} ${request.method} ${request.path} → ${res.status}: ${detail}`);
+                // 4xx other than rate-limiting is a request the server will reject
+                // identically on retry; failing fast keeps a bad filter from
+                // becoming a retry storm.
+                if (res.status !== 429 && res.status < 500)
+                    break;
+            }
+            catch (err) {
+                lastError = err;
+            }
+        }
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+}
+//# sourceMappingURL=RestVectorStore.js.map

package/dist/vectorstore/RestVectorStore.js.map

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

package/dist/vectorstore/dialects.d.ts

@@ -0,0 +1,101 @@
+/**
+ * vectorstore/dialects.ts — vendor wire shapes, as registry DATA.
+ *
+ * A dialect is everything that differs between vector databases: the URL shape,
+ * the request bodies, the response parsing, and how much of the filter algebra the
+ * vendor's query language can express. Supporting a new database is REGISTERING a
+ * dialect, never editing a branch in the store — which is the whole reason the
+ * adapter is one class over a registry rather than one class per vendor.
+ *
+ * `translateFilter` returns a `residual`: the part of the filter the vendor cannot
+ * express. The store applies the residual locally AFTER the server has done the
+ * part it could push down, and over-fetches to compensate. That is the honest
+ * design — the alternative is silently dropping a clause, which on an ACL clause
+ * is a cross-tenant leak.
+ *
+ * ⚠️ The three vendor dialects here are validated by unit tests that assert the
+ * emitted request bodies and parse recorded response shapes; they have NOT been
+ * run against live services in this repository (no credentials). The `evermind`
+ * dialect is the canonical contract this package defines and owns.
+ */
+import type { MetadataFilter, UpsertResult, VectorMatch, VectorRecord } from './types.js';
+export interface HttpRequest {
+    /** Appended to the adapter's `baseUrl`. */
+    path: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    body?: unknown;
+}
+export interface DialectContext {
+    /** Collection / index / namespace name. */
+    collection: string;
+    /** Extra per-deployment values a dialect needs (project, deployedIndexId, …). */
+    options: Record<string, string>;
+}
+export interface TranslatedFilter {
+    /** The vendor-native filter object, or `undefined` when there is nothing to push. */
+    pushed?: unknown;
+    /** The clauses the vendor could not express — applied locally by the store. */
+    residual?: MetadataFilter;
+}
+export interface VectorDialect {
+    readonly id: string;
+    /**
+     * False when the vendor stores vectors only (Vertex AI Vector Search). The
+     * store then hydrates `text` through its `textResolver`, and says so on the
+     * telemetry span, rather than returning matches with empty text.
+     */
+    readonly storesText: boolean;
+    readonly supportsKeywordSearch: boolean;
+    /** False when `count` must be emulated by a capped query. */
+    readonly supportsCount: boolean;
+    /** False when a filtered bulk delete must be emulated by query-then-delete. */
+    readonly supportsDeleteByFilter: boolean;
+    translateFilter(filter: MetadataFilter): TranslatedFilter;
+    upsert(ctx: DialectContext, records: readonly VectorRecord[]): HttpRequest;
+    parseUpsert(json: unknown, sent: number): UpsertResult;
+    query(ctx: DialectContext, args: {
+        vector?: Float32Array;
+        text?: string;
+        topK: number;
+        filter?: unknown;
+        includeVectors: boolean;
+    }): HttpRequest;
+    parseMatches(json: unknown): VectorMatch[];
+    deleteByIds(ctx: DialectContext, ids: readonly string[]): HttpRequest;
+    fetch(ctx: DialectContext, ids: readonly string[]): HttpRequest;
+    parseRecords(json: unknown): VectorRecord[];
+    keywordSearch?(ctx: DialectContext, args: {
+        text: string;
+        topK: number;
+        filter?: unknown;
+    }): HttpRequest;
+    deleteByFilter?(ctx: DialectContext, filter?: unknown): HttpRequest;
+    count?(ctx: DialectContext, filter?: unknown): HttpRequest;
+    parseCount?(json: unknown): number;
+}
+/**
+ * The canonical gateway contract. A thin service in front of ANY database can
+ * implement it (the BuilderForce.ai gateway does), which keeps a customer's chosen
+ * store behind their own network boundary while this package speaks one protocol.
+ * The filter algebra crosses the wire unchanged, so nothing is ever residual.
+ */
+export declare const evermindDialect: VectorDialect;
+export declare const qdrantDialect: VectorDialect;
+export declare const pineconeDialect: VectorDialect;
+/**
+ * Vertex expresses filters as `restricts` (string namespaces with an allow list)
+ * and `numericRestricts` (numeric comparisons), which is a close fit for this
+ * algebra: `eq`/`in`/`anyOf` on strings become a restrict namespace, and numeric
+ * comparisons become a numeric restrict. Anything else stays residual.
+ *
+ * Vertex stores vectors and restricts, NOT text — hence `storesText: false`. The
+ * store hydrates chunk text through its `textResolver`, which in a real GCP
+ * architecture reads from Firestore, BigQuery or GCS beside the index. Pretending
+ * otherwise would return matches with empty text and an answer with no evidence.
+ */
+export declare const vertexAiDialect: VectorDialect;
+/** Registers (or replaces) a dialect — how a customer adds their own database. */
+export declare function registerDialect(dialect: VectorDialect): void;
+export declare function getDialect(id: string): VectorDialect;
+export declare function listDialects(): string[];
+//# sourceMappingURL=dialects.d.ts.map

package/dist/vectorstore/dialects.d.ts.map

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