@an5/adapters 0.2.6 → 0.2.9

package/README.md

@@ -11,9 +11,9 @@ Standalone runtime database adapter and query engine for AN5 ORM. Provides conne
 - **Query Builder & Dialects** — Dialect-aware SQL formatting for MSSQL, PostgreSQL, MySQL, and SQLite
 - **Aggregations & GroupBy** — Standard ORM aggregates (`_count`, `_sum`, `_avg`, `_min`, `_max`) and `groupBy`
 - **Field Math Operators** — Atomic updates with `increment`, `decrement`, `multiply`, `divide`, `set`
-- **Vector Search** — Similarity search using pgvector (PostgreSQL), `VECTOR_DISTANCE` (MSSQL), or in-memory cosine/euclidean/dot similarity
+- **Vector Search** — Similarity search using NBase, pgvector (PostgreSQL), `VECTOR_DISTANCE` (MSSQL), or in-memory cosine/euclidean/dot similarity
 - **Real Transactions** — Interactive and callback transactions (`$transaction(async tx => ...)` and `$begin()/$commit()/$rollback()`)
-- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), and Golang
+- **Cross-Language** — Unified API in TypeScript, Python, .NET (C#), Golang, and Rust
 - **Google Sheets Database** — Use spreadsheets as a live database with full CRUD and SQL syntax support
 
 ---
@@ -44,8 +44,102 @@ dotnet add package An5Adapters
 # Included in the npm package under golang/ or via go module
 ```
 
+### Rust
+
+```bash
+cargo add an5-adapters
+```
+
+The crate is driver-agnostic — it depends on `sqlx` with `any`, so the app enables the driver it needs. See [crates.io](https://crates.io/crates/an5-adapters) and [docs.rs](https://docs.rs/an5-adapters).
+
 ---
 
+## NBase — Neural Vector Database
+
+[NBase](https://github.com/N2FlowJS/nbase) is a partitioned vector database with
+HNSW, LSH and KNN indexing behind a REST API. an5 can run vector search there
+instead of loading every row into memory, which matters once a table holds
+millions of embeddings.
+
+The rows stay in your relational table: only the vectors move to NBase, each one
+tagged with its row id, and search results are hydrated from the table.
+
+### Configure
+
+NBase is configured through the connection string, like every other backend:
+
+```ts
+import { createAn5Adapter } from '@an5/adapters';
+
+const db = createAn5Adapter({ connectionString: 'nbase://localhost:1307' });
+await db.$connect(); // probes NBase
+```
+
+Accepted forms:
+
+| Form | Result |
+|------|--------|
+| `nbase://localhost:1307` | `http://localhost:1307` |
+| `nbase:localhost:1307` | `http://localhost:1307` |
+| `nbase:http://localhost:1307` | `http://localhost:1307` |
+| `nbase:https://vectors.example.com` | `https://vectors.example.com` |
+| `nbase://localhost:1307?token=t&timeoutMs=500&method=hnsw` | options applied |
+
+`?token`, `?timeoutMs`, `?method`, `?idField` and `?modelField` are read from the
+query string, and a path is kept as a base path for deployments behind a
+reverse proxy.
+
+This adapter is **vector-only**: it has no relational database, so a search
+returns the NBase hits — id, metadata and `distance` — instead of table rows.
+
+### Search
+
+With an `nbase://` connection string, search returns the hits themselves:
+
+```ts
+const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+// hits[0] = { id: 'Article:42', an5Id: '42', an5Model: 'Article', distance: 0.11 }
+```
+
+### Search rows from your own table
+
+To get real rows back, keep your database connection string and point it at the
+same NBase instance. NBase is still configured with a connection string, never a
+params object:
+
+```ts
+const db = createAn5Adapter({
+  connectionString: 'sqlserver://localhost:1433;database=mydb',
+  nbase: 'nbase://localhost:1307',
+});
+
+await db.table('Article').indexVectorsInNBase({ vectorField: 'embedding' });
+// → { indexed: 1200 }
+
+const hits = await db.table('Article').vectorSearch({ vector: queryEmbedding, take: 5 });
+// hits[0] = { id, title, ..., distance }
+```
+
+Vectors are tagged with their row id, so a hit is hydrated from the table by
+that id and the result keeps the `{ ...row, distance }` shape the other engines
+return.
+
+### Standalone client
+
+```ts
+import { createNBaseVectorClient } from '@an5/adapters/nbase';
+
+const nbase = createNBaseVectorClient({ url: 'http://localhost:1307' });
+await nbase.health();
+await nbase.addVectors([{ id: 'a:1', vector: [0.1, 0.2], metadata: { an5Id: '1' } }]);
+const { results } = await nbase.search([0.1, 0.2], { k: 5, distanceMetric: 'cosine' });
+```
+
+If NBase is unreachable, `vectorSearch` logs a warning and falls back to the
+database's native vector support, then to in-memory similarity, so an outage
+degrades performance rather than breaking queries.
+
+
 ## Usage
 
 ### TypeScript

package/dist/an5Adapter.d.ts

@@ -1,5 +1,6 @@
 import { An5SheetsAdapter, An5SheetsAdapterConfig, SheetsTableClient } from './googlesheets';
 import type { An5AdapterConfig, Dialect, TransactionHandle } from './base/types';
+import { type NBaseAdapterConfig, type NBaseVectorClient } from './nbase';
 export type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from './base/types';
 export { setAdapterMetadata, createAdapterProxy, type AdapterMetadata } from './base/metadata';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
@@ -13,6 +14,23 @@ export declare class An5Adapter {
     private _engineType;
     private _engineConfig;
     sheetsAdapter: An5SheetsAdapter | null;
+    private _nbase;
+    private _nbaseConfig;
+    private _nbaseOnly;
+    /**
+     * Returns the NBase client for this adapter, if the project configured one.
+     * The connection string may also point straight at NBase, which keeps
+     * `DATABASE_URL=nbase://host:port` working on its own.
+     */
+    nbaseClient(): {
+        client: NBaseVectorClient;
+        config: NBaseAdapterConfig;
+    } | null;
+    /**
+     * True when the adapter only knows about NBase, so there is no relational
+     * database to read rows from.
+     */
+    get nbaseOnly(): boolean;
     get dialect(): Dialect;
     constructor(adapterConfig: An5AdapterConfig | An5SheetsAdapterConfig);
     private requireEngine;
@@ -25,6 +43,15 @@ export declare class An5Adapter {
     $executeRaw(query: string, ...values: any[]): Promise<number>;
     $executeRawUnsafe(query: string, ...values: any[]): Promise<number>;
     $connect(): Promise<void>;
+    /**
+     * Health check for the configured NBase instance, or the database when the
+     * adapter has none.
+     */
+    $nbaseHealth(): Promise<{
+        connected: boolean;
+        endpoint?: string;
+        error?: string;
+    }>;
     $disconnect(): Promise<void>;
     /** Real transaction with BEGIN / COMMIT / ROLLBACK */
     $transaction<R>(fn: (tx: An5AdapterTx) => Promise<R>, options?: {
@@ -179,6 +206,36 @@ export declare class AdapterTableClient<T = any> {
     }): Promise<T>;
     aggregate(args: any): Promise<any>;
     groupBy(args: any): Promise<any[]>;
+    /**
+     * Runs similarity search in NBase and hydrates the matching rows from the
+     * relational table, keeping the `{ ...row, distance }` shape the other
+     * engines return.
+     */
+    private searchViaNBase;
+    /**
+     * Vector search for an adapter configured with only an NBase connection
+     * string. The hit id and metadata are the result, since there is no
+     * relational row to hydrate.
+     */
+    private searchViaNBaseOnly;
+    /** The primary key column registered for this model, falling back to `id`. */
+    private primaryKeyColumn;
+    /** Scalar column names known for this model from the generated metadata. */
+    private modelFields;
+    /**
+     * Pushes a table's embedding column into NBase so it can be searched there.
+     *
+     * Each vector keeps the row id in its metadata, which is what lets
+     * `vectorSearch` return real rows instead of bare vector ids.
+     */
+    indexVectorsInNBase(args?: {
+        vectorField?: string;
+        where?: any;
+        take?: number;
+        batchSize?: number;
+    }): Promise<{
+        indexed: number;
+    }>;
     vectorSearch(args: {
         vector: number[];
         take?: number;

package/dist/an5Adapter.js

@@ -7,6 +7,15 @@ exports.executorFromAdapter = executorFromAdapter;
 const uuid_1 = require("./base/uuid");
 const googlesheets_1 = require("./googlesheets");
 const parseConnectionString_1 = require("./googlesheets/parseConnectionString");
+/**
+ * File extensions that mean SQLite when a connection string has no scheme.
+ *
+ * `.sqlite3` is here as well as in `@an5/orm`'s `detectProvider`, because the ORM
+ * validates field types and writes the DDL from the provider this file picks: if the
+ * two lists differed, a `.sqlite3` file would be pushed as SQL Server DDL.
+ */
+const SQLITE_FILE_SUFFIXES = ['.sqlite', '.sqlite3', '.db'];
+const nbase_1 = require("./nbase");
 const sql_1 = require("./base/sql");
 const metadata_1 = require("./base/metadata");
 var metadata_2 = require("./base/metadata");
@@ -171,6 +180,29 @@ async function resolveIncludes(modelName, rows, include, adapter) {
 }
 // ─── An5Adapter ────────────────────────────────────────────────────────────────────
 class An5Adapter {
+    /**
+     * Returns the NBase client for this adapter, if the project configured one.
+     * The connection string may also point straight at NBase, which keeps
+     * `DATABASE_URL=nbase://host:port` working on its own.
+     */
+    nbaseClient() {
+        if (this._nbase && this._nbaseConfig)
+            return { client: this._nbase, config: this._nbaseConfig };
+        if (!this._nbaseConfig)
+            return null;
+        const config = this._nbaseConfig;
+        const client = (0, nbase_1.createNBaseVectorClient)(config);
+        this._nbase = client;
+        this._nbaseConfig = config;
+        return { client, config };
+    }
+    /**
+     * True when the adapter only knows about NBase, so there is no relational
+     * database to read rows from.
+     */
+    get nbaseOnly() {
+        return this._nbaseOnly === true;
+    }
     get dialect() {
         if (this.sheetsAdapter)
             return 'googlesheets';
@@ -189,12 +221,32 @@ class An5Adapter {
         this._engineType = null;
         this._engineConfig = null;
         this.sheetsAdapter = null;
+        this._nbase = null;
+        this._nbaseConfig = null;
+        this._nbaseOnly = false;
         this._listeners = {};
         this._middlewares = [];
         if (isSheetsConfig(adapterConfig)) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter(adapterConfig);
             return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
+        // Keep the config even when the caller supplies its own engine: the NBase
+        // settings and anything else on the config are read from it later.
+        this._engineConfig = adapterConfig;
+        // `nbase://host:port` as the connection string configures the vector store
+        // on its own: there is no relational database, so the adapter is
+        // vector-only. The same string passed as `nbase` keeps the database from
+        // `connectionString` as the source of rows.
+        const rawConnectionString = String(this._engineConfig.connectionString ?? '').trim();
+        if ((0, nbase_1.isNBaseConnectionString)(rawConnectionString)) {
+            this._nbaseConfig = (0, nbase_1.parseNBaseConnectionString)(rawConnectionString);
+            this._nbaseOnly = true;
+            return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
+        }
+        const attached = this._engineConfig.nbase;
+        if (attached && (0, nbase_1.isNBaseConnectionString)(attached)) {
+            this._nbaseConfig = (0, nbase_1.parseNBaseConnectionString)(attached);
+        }
         if (adapterConfig.engine) {
             this._engine = adapterConfig.engine;
             this._engineType = this._engine?.dialect || 'sqlite';
@@ -206,19 +258,25 @@ class An5Adapter {
             this._engineType = 'sqlite';
             return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
+        // Lower-cased for the dialect test only; the connection string itself keeps its
+        // case for the driver. A URI scheme is case-insensitive, and `@an5/orm` reads the
+        // provider the same way to validate field types and write DDL — if the two
+        // disagreed, a schema would be checked against one database and run on another.
         const cs = (adapterConfig.connectionString || '').trim();
-        if (cs.startsWith('googlesheets://')) {
+        const forDialect = cs.toLowerCase();
+        if (forDialect.startsWith('googlesheets://')) {
             this.sheetsAdapter = new googlesheets_1.An5SheetsAdapter((0, parseConnectionString_1.parseSheetsConnectionString)(cs));
             return (0, metadata_1.createAdapterProxy)(this, (name) => this.table(name));
         }
         this._engineConfig = adapterConfig;
-        if (cs.startsWith('postgres://') || cs.startsWith('postgresql://')) {
+        if (forDialect.startsWith('postgres://') || forDialect.startsWith('postgresql://')) {
             this._engineType = 'postgres';
         }
-        else if (cs.startsWith('mysql://') || cs.startsWith('mariadb://')) {
+        else if (forDialect.startsWith('mysql://') || forDialect.startsWith('mariadb://')) {
             this._engineType = 'mysql';
         }
-        else if (cs.startsWith('sqlite://') || cs.endsWith('.sqlite') || cs.endsWith('.db')) {
+        else if (forDialect.startsWith('sqlite://')
+            || SQLITE_FILE_SUFFIXES.some((suffix) => forDialect.endsWith(suffix))) {
             this._engineType = 'sqlite';
         }
         else {
@@ -310,8 +368,36 @@ class An5Adapter {
     async $connect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$connect();
+        if (this._nbaseOnly) {
+            // NBase is stateless over HTTP, so there is nothing to open. Report the
+            // endpoint so a misconfiguration is obvious.
+            const config = this.nbaseClient()?.config;
+            if (config)
+                await this.nbaseClient().client.health();
+            return;
+        }
         await (await this.requireEngine()).connect();
     }
+    /**
+     * Health check for the configured NBase instance, or the database when the
+     * adapter has none.
+     */
+    async $nbaseHealth() {
+        const nbase = this.nbaseClient();
+        if (!nbase)
+            return { connected: false, error: 'No NBase instance configured.' };
+        try {
+            const health = await nbase.client.health();
+            return { connected: health.status === 'ok', endpoint: nbase.config.url };
+        }
+        catch (err) {
+            return {
+                connected: false,
+                endpoint: nbase.config.url,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
     async $disconnect() {
         if (this.sheetsAdapter)
             return this.sheetsAdapter.$disconnect();
@@ -1001,6 +1087,158 @@ class AdapterTableClient {
         }
         return this.doExec(query, params);
     }
+    /**
+     * Runs similarity search in NBase and hydrates the matching rows from the
+     * relational table, keeping the `{ ...row, distance }` shape the other
+     * engines return.
+     */
+    async searchViaNBase(nbase, args, metric, take) {
+        const { client, config } = nbase;
+        const idField = config.idField ?? 'an5Id';
+        const modelField = config.modelField ?? 'an5Model';
+        const results = await client.search(args.vector, {
+            k: take,
+            // NBase implements cosine and euclidean; a dot-product request falls back
+            // to cosine, which still orders the results sensibly.
+            distanceMetric: metric === 'euclidean' ? 'euclidean' : 'cosine',
+            includeMetadata: true,
+            ...(config.method ? { method: config.method } : {}),
+        });
+        // Map each hit back to its row id. Ids are written as `Model:id`, and the
+        // metadata key is honoured for projects that index vectors themselves.
+        const ids = [];
+        const distances = new Map();
+        for (const hit of results) {
+            const fromMetadata = hit.metadata?.[idField];
+            const rawId = fromMetadata !== undefined && fromMetadata !== null
+                ? String(fromMetadata)
+                : (0, nbase_1.parseVectorId)(hit.id).id;
+            if (!rawId)
+                continue;
+            const model = hit.metadata?.[modelField] ?? (0, nbase_1.parseVectorId)(hit.id).model;
+            ids.push(model === this.modelName ? rawId : `${model}:${rawId}`);
+            distances.set(ids[ids.length - 1], hit.dist);
+        }
+        if (ids.length === 0)
+            return [];
+        const pk = this.primaryKeyColumn();
+        const inList = ids.map((_, i) => `@nbase_id_${i}`).join(', ');
+        const idParams = {};
+        ids.forEach((id, i) => { idParams[`nbase_id_${i}`] = id; });
+        idParams.take = take;
+        const selectColumns = this.modelFields().map((f) => (0, sql_1.quote)(f, this.dialect)).join(', ');
+        const columns = selectColumns ? `${selectColumns}, ${(0, sql_1.quote)(pk, this.dialect)} AS __an5_nbase_key` : `${(0, sql_1.quote)(pk, this.dialect)} AS __an5_nbase_key`;
+        const query = `SELECT ${columns} FROM ${this.tableName} WHERE ${(0, sql_1.quote)(pk, this.dialect)} IN (${inList})`;
+        const rows = await this.adapter.exec(query, idParams);
+        const byKey = new Map();
+        for (const row of rows ?? []) {
+            byKey.set(String(row.__an5_nbase_key), row);
+        }
+        const hydrated = [];
+        for (const id of ids) {
+            const row = byKey.get(id);
+            if (!row)
+                continue;
+            const { __an5_nbase_key, ...rest } = row;
+            hydrated.push({ ...rest, distance: distances.get(id) ?? 0 });
+            if (hydrated.length >= take)
+                break;
+        }
+        return hydrated;
+    }
+    /**
+     * Vector search for an adapter configured with only an NBase connection
+     * string. The hit id and metadata are the result, since there is no
+     * relational row to hydrate.
+     */
+    async searchViaNBaseOnly(nbase, args, metric, take) {
+        const { client, config } = nbase;
+        const idField = config.idField ?? 'an5Id';
+        const results = await client.search(args.vector, {
+            k: take,
+            distanceMetric: metric === 'euclidean' ? 'euclidean' : 'cosine',
+            includeMetadata: true,
+            ...(config.method ? { method: config.method } : {}),
+        });
+        return results.map((hit) => {
+            const metadata = { ...(hit.metadata ?? {}) };
+            if (metadata[idField] === undefined) {
+                const parsed = (0, nbase_1.parseVectorId)(hit.id);
+                if (parsed.id)
+                    metadata[idField] = parsed.id;
+                if (parsed.model)
+                    metadata[config.modelField ?? 'an5Model'] = parsed.model;
+            }
+            return { id: hit.id, ...metadata, distance: hit.dist };
+        });
+    }
+    /** The primary key column registered for this model, falling back to `id`. */
+    primaryKeyColumn() {
+        const fields = this.modelFields();
+        const marked = fields.find((f) => f === 'id');
+        return marked ?? fields[0] ?? 'id';
+    }
+    /** Scalar column names known for this model from the generated metadata. */
+    modelFields() {
+        const fields = (0, metadata_1.getFieldsForModel)(this.modelName);
+        if (fields && typeof fields === 'object' && !Array.isArray(fields)) {
+            return Object.keys(fields);
+        }
+        return [];
+    }
+    /**
+     * Pushes a table's embedding column into NBase so it can be searched there.
+     *
+     * Each vector keeps the row id in its metadata, which is what lets
+     * `vectorSearch` return real rows instead of bare vector ids.
+     */
+    async indexVectorsInNBase(args = {}) {
+        const nbase = this.adapter.nbaseClient?.() ?? null;
+        if (!nbase) {
+            throw new Error('No NBase instance configured. Use a nbase:// connection string, e.g. createAn5Adapter({ connectionString: "nbase://localhost:1307" }).');
+        }
+        if (this.adapter.nbaseOnly) {
+            throw new Error('indexVectorsInNBase reads the vectors from a table, but this adapter was created with an nbase:// connection string and has no database. ' +
+                'Create the adapter with your database connection string to index, or add the vectors with the NBase client directly.');
+        }
+        const vectorField = args.vectorField || 'embedding';
+        const batchSize = args.batchSize ?? 200;
+        const pk = this.primaryKeyColumn();
+        const rows = await this.findMany({ ...(args.where ? { where: args.where } : {}), ...(args.take ? { take: args.take } : {}) });
+        let indexed = 0;
+        for (let i = 0; i < rows.length; i += batchSize) {
+            const batch = rows.slice(i, i + batchSize);
+            const vectors = batch
+                .map((row) => {
+                const raw = row[vectorField];
+                if (raw === undefined || raw === null)
+                    return null;
+                let vector;
+                try {
+                    vector = typeof raw === 'string' ? JSON.parse(raw) : raw;
+                }
+                catch {
+                    return null;
+                }
+                if (!Array.isArray(vector) || vector.length === 0)
+                    return null;
+                return {
+                    id: (0, nbase_1.buildVectorId)(this.modelName, String(row[pk])),
+                    vector,
+                    metadata: {
+                        [nbase.config.idField ?? 'an5Id']: String(row[pk]),
+                        [nbase.config.modelField ?? 'an5Model']: this.modelName,
+                    },
+                };
+            })
+                .filter((v) => v !== null);
+            if (vectors.length === 0)
+                continue;
+            const result = await nbase.client.addVectors(vectors);
+            indexed += result.count;
+        }
+        return { indexed };
+    }
     async vectorSearch(args) {
         const vectorField = args.vectorField || 'embedding';
         const METRICS = ['cosine', 'euclidean', 'dot'];
@@ -1012,6 +1250,26 @@ class AdapterTableClient {
         const vectorJson = JSON.stringify(args.vector);
         const col = (0, sql_1.quote)(vectorField, this.dialect);
         const params = { query_vector: vectorJson };
+        // 0. NBase, when the project configured one: the vectors live in the vector
+        //    database, so the search never loads the table into memory.
+        const nbase = this.adapter.nbaseClient?.() ?? null;
+        if (nbase) {
+            try {
+                // With an NBase-only connection string there is no table to read rows
+                // from, so the hits are returned as the vector metadata itself.
+                if (this.adapter.nbaseOnly) {
+                    return (await this.searchViaNBaseOnly(nbase, args, metric, take));
+                }
+                return await this.searchViaNBase(nbase, args, metric, take);
+            }
+            catch (err) {
+                if (!(err instanceof nbase_1.NBaseError))
+                    throw err;
+                // A NBase outage must not take vector search down with it; fall through
+                // to the database instead of failing the query.
+                console.warn(`[an5] NBase vector search unavailable (${err.message}); falling back to ${this.dialect}.`);
+            }
+        }
         // 1. Try native dialect execution
         if (this.dialect === 'postgres') {
             const op = metric === 'cosine' ? '<=>' : metric === 'dot' ? '<#>' : '<->';

package/dist/base/types.d.ts

@@ -1,6 +1,12 @@
 export type Dialect = 'mssql' | 'postgres' | 'mysql' | 'sqlite' | 'googlesheets';
 export interface An5AdapterConfig {
     connectionString?: string;
+    /**
+     * NBase (Neural Vector Database) endpoint, written as a connection string,
+     * e.g. `nbase://localhost:1307`. Attach it here when vector search should
+     * run in NBase while the rows stay in `connectionString`'s database.
+     */
+    nbase?: string;
     engine?: QueryEngine;
     db?: any;
     driver?: any;

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { An5Adapter, AdapterTableClient, createAn5Adapter, createAdapterProxy, executorFromAdapter, setAdapterMetadata, } from './an5Adapter';
 export { parseWhere, buildOrderBy, quote } from './base/sql';
+export { NBaseVectorClient, NBaseError, createNBaseVectorClient, createNBaseClient, parseNBaseConnectionString, buildVectorId, parseVectorId, } from './nbase';
+export type { NBaseAdapterConfig, NBaseClientConfig, NBaseVector, NBaseSearchOptions, NBaseSearchResult, NBaseStats, } from './nbase';
 export type { An5AdapterConfig, AdapterMetadata, Dialect, } from './an5Adapter';
 export type { TypedAn5Adapter, AdapterAPI } from './typed';
 export { getLlmConfig, setLlmConfig, getEmbeddingConfig, setEmbeddingConfig, resetAdapter, } from './config';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
+exports.parseSheetsConnectionString = exports.createAn5SheetsAdapter = exports.SheetsTableClient = exports.An5SheetsAdapter = exports.resetAdapter = exports.setEmbeddingConfig = exports.getEmbeddingConfig = exports.setLlmConfig = exports.getLlmConfig = exports.parseVectorId = exports.buildVectorId = exports.parseNBaseConnectionString = exports.createNBaseClient = exports.createNBaseVectorClient = exports.NBaseError = exports.NBaseVectorClient = exports.quote = exports.buildOrderBy = exports.parseWhere = exports.setAdapterMetadata = exports.executorFromAdapter = exports.createAdapterProxy = exports.createAn5Adapter = exports.AdapterTableClient = exports.An5Adapter = void 0;
 var an5Adapter_1 = require("./an5Adapter");
 Object.defineProperty(exports, "An5Adapter", { enumerable: true, get: function () { return an5Adapter_1.An5Adapter; } });
 Object.defineProperty(exports, "AdapterTableClient", { enumerable: true, get: function () { return an5Adapter_1.AdapterTableClient; } });
@@ -12,6 +12,14 @@ var sql_1 = require("./base/sql");
 Object.defineProperty(exports, "parseWhere", { enumerable: true, get: function () { return sql_1.parseWhere; } });
 Object.defineProperty(exports, "buildOrderBy", { enumerable: true, get: function () { return sql_1.buildOrderBy; } });
 Object.defineProperty(exports, "quote", { enumerable: true, get: function () { return sql_1.quote; } });
+var nbase_1 = require("./nbase");
+Object.defineProperty(exports, "NBaseVectorClient", { enumerable: true, get: function () { return nbase_1.NBaseVectorClient; } });
+Object.defineProperty(exports, "NBaseError", { enumerable: true, get: function () { return nbase_1.NBaseError; } });
+Object.defineProperty(exports, "createNBaseVectorClient", { enumerable: true, get: function () { return nbase_1.createNBaseVectorClient; } });
+Object.defineProperty(exports, "createNBaseClient", { enumerable: true, get: function () { return nbase_1.createNBaseClient; } });
+Object.defineProperty(exports, "parseNBaseConnectionString", { enumerable: true, get: function () { return nbase_1.parseNBaseConnectionString; } });
+Object.defineProperty(exports, "buildVectorId", { enumerable: true, get: function () { return nbase_1.buildVectorId; } });
+Object.defineProperty(exports, "parseVectorId", { enumerable: true, get: function () { return nbase_1.parseVectorId; } });
 var config_1 = require("./config");
 Object.defineProperty(exports, "getLlmConfig", { enumerable: true, get: function () { return config_1.getLlmConfig; } });
 Object.defineProperty(exports, "setLlmConfig", { enumerable: true, get: function () { return config_1.setLlmConfig; } });

package/dist/nbase/client.d.ts

@@ -0,0 +1,92 @@
+/**
+ * NBase — Neural Vector Database client.
+ *
+ * NBase is a vector database with HNSW/LSH/KNN indexing exposed over a REST
+ * API. an5 uses it to move similarity search out of the database process: the
+ * vectors live in NBase, the rows stay in the relational table, and the search
+ * results are hydrated from the table by the id kept in vector metadata.
+ *
+ * The client only uses the global `fetch`, so it works in Node 18+ and in the
+ * browser without pulling in a dependency.
+ */
+export interface NBaseVector {
+    id: string | number;
+    vector: number[];
+    metadata?: Record<string, unknown>;
+}
+export interface NBaseSearchOptions {
+    /** Number of neighbours to return. */
+    k?: number;
+    /** Distance metric; NBase accepts `cosine` and `euclidean`. */
+    distanceMetric?: 'cosine' | 'euclidean';
+    /** `hnsw` uses the graph index, anything else uses the clustered path. */
+    method?: 'hnsw' | 'clustered';
+    efSearch?: number;
+    filters?: Record<string, unknown> | Array<Record<string, unknown>>;
+    includeMetadata?: boolean;
+    includeVectors?: boolean;
+    skipCache?: boolean;
+    searchTimeoutMs?: number;
+    rerank?: boolean;
+    rerankingMethod?: string;
+    rerankLambda?: number;
+    partitionIds?: string[];
+}
+export interface NBaseSearchResult {
+    id: string | number;
+    /** Distance from the query vector. Lower is more similar. */
+    dist: number;
+    metadata?: Record<string, unknown>;
+    vector?: number[];
+    dimension?: number;
+}
+export interface NBaseClientConfig {
+    /** Base URL, e.g. `http://localhost:1307`. */
+    url: string;
+    /** Optional bearer token, for deployments behind an auth proxy. */
+    token?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Injectable for tests and for runtimes without a global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export interface NBaseStats {
+    vectorCount?: number;
+    metadataCount?: number;
+    memoryUsage?: number;
+    [key: string]: unknown;
+}
+export declare class NBaseError extends Error {
+    readonly status?: number | undefined;
+    readonly body?: unknown;
+    constructor(message: string, status?: number | undefined, body?: unknown);
+}
+export declare class NBaseVectorClient {
+    private readonly config;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(config: NBaseClientConfig);
+    private request;
+    /** Liveness probe. NBase mounts its status routes at the server root. */
+    health(): Promise<{
+        status: string;
+        version?: string;
+    }>;
+    /** Vector count, memory use and other database statistics. */
+    stats(): Promise<NBaseStats>;
+    /** Adds or replaces vectors. NBase accepts a single vector or a bulk array. */
+    addVectors(vectors: NBaseVector[]): Promise<{
+        count: number;
+        ids?: Array<string | number>;
+    }>;
+    /** Nearest-neighbour search. Results are ordered by ascending `dist`. */
+    search(vector: number[], options?: NBaseSearchOptions): Promise<NBaseSearchResult[]>;
+    /** Reads a single vector. Returns undefined when the id is unknown. */
+    get(id: string | number): Promise<NBaseSearchResult | undefined>;
+    exists(id: string | number): Promise<boolean>;
+    delete(id: string | number): Promise<boolean>;
+    updateMetadata(id: string | number, metadata: Record<string, unknown>): Promise<boolean>;
+}
+/** Creates an NBase vector client. */
+export declare function createNBaseVectorClient(config: NBaseClientConfig): NBaseVectorClient;