@an5/adapters 0.2.11 → 0.2.14

package/dist/sqlite/vector.js

@@ -0,0 +1,432 @@
+"use strict";
+// ─── SQLite vector search ──────────────────────────────────────────────────────────
+//
+// SQLite has no vector type, so `VECTOR(n)` columns are stored as a BLOB of
+// little-endian float32 values (see `encodeVector`) and searched in one of four
+// ways. The order is fixed so every runtime that speaks SQLite can implement it:
+//
+//   1. sqlite-vec   native scalar distance functions, if the extension loads.
+//   2. udf          `an5_vec_cosine` / `an5_vec_l2` / `an5_vec_ip` registered by
+//                   the driver. Reads the BLOB and the legacy JSON text.
+//   3. sql          `json_each` brute force in plain SQL. No UDF needed, so it
+//                   works in browsers and on JDBC, but only for JSON text.
+//   4. memory       the adapter loads the column and scores it in the client.
+//
+// Strategies 1-3 rank in the database and only transfer the `take` rows that
+// match, which is the reason they are preferred over the in-memory path.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SqliteVectorSupport = exports.AN5_VECTOR_FUNCTIONS = exports.SQLITE_VEC_FUNCTIONS = void 0;
+exports.parseVector = parseVector;
+exports.decodeVector = decodeVector;
+exports.encodeVector = encodeVector;
+exports.needsVectorEncoding = needsVectorEncoding;
+exports.isVectorField = isVectorField;
+exports.vectorDistance = vectorDistance;
+exports.buildSqliteVectorQuery = buildSqliteVectorQuery;
+exports.planSqliteVectorStrategies = planSqliteVectorStrategies;
+exports.readSqliteColumnType = readSqliteColumnType;
+exports.runSqliteVectorSearch = runSqliteVectorSearch;
+/** Scalar functions shipped by the sqlite-vec extension. */
+exports.SQLITE_VEC_FUNCTIONS = {
+    cosine: 'vec_distance_cosine',
+    euclidean: 'vec_distance_l2',
+    dot: 'vec_distance_ip',
+};
+/** Scalar functions the adapter registers itself when the driver allows it. */
+exports.AN5_VECTOR_FUNCTIONS = {
+    cosine: 'an5_vec_cosine',
+    euclidean: 'an5_vec_l2',
+    dot: 'an5_vec_ip',
+};
+const BYTES_PER_FLOAT = 4;
+function normalizeMetric(metric) {
+    return metric === 'euclidean' || metric === 'dot' ? metric : 'cosine';
+}
+// ─── Codec ─────────────────────────────────────────────────────────────────────────
+function toBytes(value) {
+    if (value instanceof Uint8Array)
+        return value;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))
+        return value;
+    if (ArrayBuffer.isView(value)) {
+        const view = value;
+        return new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    }
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    return null;
+}
+/** Read a numeric array out of the shapes a driver can hand back. */
+function parseVector(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (Array.isArray(value)) {
+        const out = new Array(value.length);
+        for (let i = 0; i < value.length; i++) {
+            const n = Number(value[i]);
+            if (!Number.isFinite(n))
+                return null;
+            out[i] = n;
+        }
+        return out.length ? out : null;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.startsWith('['))
+            return null;
+        try {
+            return parseVector(JSON.parse(trimmed));
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Decode a stored vector: a float32 BLOB, a legacy JSON text column, or an
+ * array the caller already decoded.
+ */
+function decodeVector(value) {
+    const direct = parseVector(value);
+    if (direct)
+        return direct;
+    const bytes = toBytes(value);
+    if (!bytes || bytes.length === 0 || bytes.length % BYTES_PER_FLOAT !== 0)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const out = new Array(bytes.length / BYTES_PER_FLOAT);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = view.getFloat32(i * BYTES_PER_FLOAT, true);
+        if (!Number.isFinite(out[i]))
+            return null;
+    }
+    return out;
+}
+/** Encode a vector as the little-endian float32 BLOB `VECTOR(n)` columns store. */
+function encodeVector(values) {
+    const buf = typeof Buffer !== 'undefined'
+        ? Buffer.alloc(values.length * BYTES_PER_FLOAT)
+        : new Uint8Array(values.length * BYTES_PER_FLOAT);
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    for (let i = 0; i < values.length; i++) {
+        if (!Number.isFinite(values[i]))
+            throw new TypeError('Vector elements must be finite numbers');
+        view.setFloat32(i * BYTES_PER_FLOAT, values[i], true);
+        if (!Number.isFinite(view.getFloat32(i * BYTES_PER_FLOAT, true))) {
+            throw new RangeError('Vector element exceeds float32 range');
+        }
+    }
+    return buf;
+}
+/** True when the value still needs encoding on its way into a `VECTOR(n)` column. */
+function needsVectorEncoding(value) {
+    return Array.isArray(value) || value instanceof Float32Array || value instanceof Float64Array;
+}
+/** True when a generated metadata entry describes a `VECTOR(n)` column. */
+function isVectorField(def) {
+    if (!def)
+        return false;
+    if (typeof def === 'string')
+        return def.includes('[]') || /^VECTOR\b/i.test(def.trim());
+    const record = def;
+    if (record.kind === 'vector')
+        return true;
+    const sql = String(record.sql ?? record.type ?? '');
+    if (/^VECTOR\s*(\(|$)/i.test(sql.trim()))
+        return true;
+    return String(record.ts ?? '').includes('[]');
+}
+// ─── Distance ──────────────────────────────────────────────────────────────────────
+/**
+ * Distance between two equal-length vectors, lower is closer. Mirrors the
+ * functions registered on the drivers so a search ranks the same way whichever
+ * strategy ran.
+ */
+function vectorDistance(a, b, metric) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length === 0 || a.length !== b.length)
+        return null;
+    let dot = 0;
+    let magA = 0;
+    let magB = 0;
+    for (let i = 0; i < a.length; i++) {
+        const av = Number(a[i]) || 0;
+        const bv = Number(b[i]) || 0;
+        dot += av * bv;
+        magA += av * av;
+        magB += bv * bv;
+    }
+    const resolved = normalizeMetric(metric);
+    if (resolved === 'euclidean') {
+        let sum = 0;
+        for (let i = 0; i < a.length; i++) {
+            const diff = (Number(a[i]) || 0) - (Number(b[i]) || 0);
+            sum += diff * diff;
+        }
+        return Math.sqrt(sum);
+    }
+    if (resolved === 'dot')
+        return -dot;
+    return magA && magB ? 1 - dot / (Math.sqrt(magA) * Math.sqrt(magB)) : 1;
+}
+// ─── Query builders ────────────────────────────────────────────────────────────────
+/** `json_valid` fails on a float32 BLOB, so the JSON path needs this guard. */
+function jsonText(column) {
+    return `CASE WHEN json_valid(${column}) THEN ${column} ELSE '[]' END`;
+}
+function jsonDistanceExpr(metric, column) {
+    const row = jsonText(column);
+    const sameLength = `(SELECT COUNT(*) FROM json_each(${row})) = (SELECT COUNT(*) FROM q)`;
+    const terms = {
+        cosine: `1.0 - (SELECT SUM(je.value * q.v) FROM json_each(${row}) je JOIN q ON q.k = je.key)`
+            + ` / NULLIF(sqrt((SELECT SUM(q.v * q.v) FROM q)) * sqrt((SELECT SUM(je.value * je.value) FROM json_each(${row}) je)), 0)`,
+        euclidean: `sqrt((SELECT SUM((je.value - q.v) * (je.value - q.v)) FROM json_each(${row}) je JOIN q ON q.k = je.key))`,
+        dot: `-(SELECT SUM(je.value * q.v) FROM json_each(${row}) je JOIN q ON q.k = je.key)`,
+    };
+    return `CASE WHEN ${sameLength} THEN ${terms[metric]} END`;
+}
+/**
+ * Ranking SQL for one strategy. `sqlite-vec` and `udf` bind the query vector as
+ * a float32 BLOB; `sql` binds it as JSON text because `json_each` reads text.
+ */
+function buildSqliteVectorQuery(args) {
+    const { strategy, metric, table, column, take } = args;
+    const params = args.params;
+    const tail = args.tail ?? '';
+    const queryVector = args.vector;
+    // A row whose stored vector cannot be scored (a NULL, a text column, another
+    // dimension) yields a NULL distance; those rows are dropped rather than
+    // reported, so a caller never has to sort them out of the result.
+    const rank = (inner) => `SELECT * FROM (${inner}) AS an5_ranked WHERE distance IS NOT NULL ORDER BY distance ASC LIMIT ${take}`;
+    if (strategy === 'sqlite-vec') {
+        params.an5_vector = encodeVector(queryVector);
+        params.an5_vector_bytes = queryVector.length * BYTES_PER_FLOAT;
+        const fn = exports.SQLITE_VEC_FUNCTIONS[metric];
+        const stored = `vec_f32(${column})`;
+        const distance = `CASE WHEN vec_length(${stored}) = ${queryVector.length} THEN ${fn}(${stored}, @an5_vector) END`;
+        // vec_f32 accepts JSON text and float32 BLOBs, preserving legacy rows.
+        return {
+            sql: rank(`SELECT *, ${distance} AS distance FROM ${table}${tail ? `${tail} AND` : ' WHERE'} ${column} IS NOT NULL`),
+            params,
+        };
+    }
+    if (strategy === 'udf') {
+        params.an5_vector = encodeVector(queryVector);
+        const distance = `${exports.AN5_VECTOR_FUNCTIONS[metric]}(${column}, @an5_vector)`;
+        return { sql: rank(`SELECT *, ${distance} AS distance FROM ${table}${tail}`), params };
+    }
+    params.an5_vector_json = JSON.stringify(queryVector);
+    const distance = jsonDistanceExpr(metric, column);
+    return {
+        sql: 'WITH q AS (SELECT je.key AS k, CAST(je.value AS REAL) AS v FROM json_each(@an5_vector_json) je) '
+            + rank(`SELECT *, ${distance} AS distance FROM ${table}${tail}`),
+        params,
+    };
+}
+function probed(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the ordered list of strategies to try for this connection.
+ *
+ * `declaredType` is the column's DDL type: the JSON strategy only reaches rows
+ * stored as text, so a `BLOB` column drops it from the order.
+ */
+function planSqliteVectorStrategies(caps, declaredType, preference) {
+    const wanted = preference && preference !== 'auto' ? [preference] : [];
+    const available = [];
+    if (caps.native && caps.udf)
+        available.push('udf');
+    if (caps.vec)
+        available.push('sqlite-vec');
+    if (caps.udf && !caps.native)
+        available.push('udf');
+    if (caps.json1)
+        available.push('sql');
+    if (wanted.length > 0)
+        return wanted.filter((s) => s !== 'memory');
+    const plan = available;
+    // A BLOB column has no JSON to read, so `json_each` can only produce NULLs.
+    const type = String(declaredType ?? '').toUpperCase();
+    if (type && !/TEXT|CHAR|CLOB|STRING|JSON/.test(type)) {
+        return plan.filter((s) => s !== 'sql');
+    }
+    return plan;
+}
+/**
+ * Register `an5_vec_*` on a driver and load sqlite-vec when a path is configured.
+ * Safe to call repeatedly; each driver hook is used at most once.
+ */
+class SqliteVectorSupport {
+    constructor(hooks, options = {}) {
+        this.hooks = hooks;
+        this.options = options;
+        this.caps = null;
+        /**
+         * Declared column types and the "any binary row" probe, keyed by column.
+         *
+         * Both cost a query, and neither changes while a schema is in use. A stale
+         * answer is still safe: the probe only decides which strategy to try first, and
+         * a strategy that fails falls through to the next one rather than reporting a
+         * wrong result.
+         */
+        this.columnTypes = new Map();
+        this.binaryRows = new Map();
+    }
+    async capabilities() {
+        if (this.caps)
+            return this.caps;
+        const caps = { vec: false, udf: false, json1: false };
+        const native = probed(() => this.hooks.native?.());
+        if (native) {
+            if (this.options.sqliteVec) {
+                probed(() => native.loadExtension(this.options.sqliteVec));
+            }
+            if (probed(() => native.prepare('SELECT vec_version()').get()) !== null)
+                caps.vec = true;
+            if (probed(() => native.prepare('SELECT an5_vector_version()').get()) !== null) {
+                caps.native = true;
+                caps.udf = true;
+            }
+        }
+        const register = this.hooks.registerFunction;
+        if (register && !caps.native) {
+            // better-sqlite3 takes an options object where every other driver takes a
+            // plain function, so both shapes are offered and the driver picks.
+            const names = Object.values(exports.AN5_VECTOR_FUNCTIONS);
+            const impls = Object.keys(exports.AN5_VECTOR_FUNCTIONS).map((metric) => {
+                const fn = (...args) => {
+                    const a = decodeVector(args[0]);
+                    const b = decodeVector(args[1]);
+                    return a && b ? vectorDistance(a, b, metric) : null;
+                };
+                return { name: exports.AN5_VECTOR_FUNCTIONS[metric], fn };
+            });
+            let all = true;
+            for (const { name, fn } of impls) {
+                if (probed(() => register(name, fn)) === null) {
+                    all = false;
+                    break;
+                }
+            }
+            // A driver that accepts the registration is trusted here; a query that
+            // still fails falls through to the next strategy.
+            caps.udf = all && names.length > 0;
+        }
+        this.caps = caps;
+        return caps;
+    }
+    /** Confirms JSON1 and a usable sqlite-vec/UDF before a query is built for them. */
+    async probe(exec) {
+        const caps = await this.capabilities();
+        if (!caps.json1) {
+            try {
+                await exec("SELECT json_valid('[1]') AS an5_json_ok");
+                caps.json1 = true;
+            }
+            catch {
+                caps.json1 = false;
+            }
+        }
+        return caps;
+    }
+    /** The column's declared DDL type, remembered per column. */
+    async columnType(exec, table, column) {
+        const key = `${table}.${column}`;
+        if (!this.columnTypes.has(key)) {
+            const found = await readSqliteColumnType(exec, table, column).catch(() => null);
+            this.columnTypes.set(key, found);
+        }
+        return this.columnTypes.get(key) ?? null;
+    }
+    /**
+     * Whether any row stores raw bytes, which `json_each` cannot read.
+     *
+     * Checked only for the `sql` strategy, where a legacy JSON column that has
+     * since taken new float32 rows would otherwise rank just the old ones.
+     */
+    async hasBinaryRows(exec, table, column, tail, params) {
+        const rows = await exec(`SELECT 1 FROM ${table}${tail ? `${tail} AND` : ' WHERE'} typeof(${column}) = 'blob' LIMIT 1`, params).catch(() => []);
+        return rows.length > 0;
+    }
+    reset() {
+        this.caps = null;
+        this.columnTypes.clear();
+        this.binaryRows.clear();
+    }
+}
+exports.SqliteVectorSupport = SqliteVectorSupport;
+/** Reads a vector column's declared DDL type, or null when it cannot be found. */
+async function readSqliteColumnType(exec, table, column) {
+    const rows = await exec("SELECT type FROM pragma_table_info(@an5_table) WHERE name = @an5_column", {
+        an5_table: table,
+        an5_column: column,
+    });
+    const value = rows?.[0]?.type;
+    return value ? String(value) : null;
+}
+/**
+ * Rank a SQLite table by distance inside the database, trying each available
+ * strategy in order. Returns null when the connection offers none, so the
+ * caller can fall back to scoring in memory.
+ */
+async function runSqliteVectorSearch(args) {
+    if (!Array.isArray(args.vector) || args.vector.length === 0)
+        return null;
+    const caps = args.vectorSupport
+        ? await args.vectorSupport.probe(args.exec)
+        : { vec: false, udf: false, json1: false };
+    if (!args.vectorSupport) {
+        try {
+            await args.exec("SELECT json_valid('[1]') AS an5_json_ok");
+            caps.json1 = true;
+        }
+        catch {
+            caps.json1 = false;
+        }
+    }
+    let declaredType = null;
+    try {
+        declaredType = args.vectorSupport
+            ? await args.vectorSupport.columnType(args.exec, args.rawTable, args.rawColumn)
+            : await readSqliteColumnType(args.exec, args.rawTable, args.rawColumn);
+    }
+    catch {
+        declaredType = null;
+    }
+    for (const strategy of planSqliteVectorStrategies(caps, declaredType, args.preference)) {
+        if (strategy === 'sql') {
+            const binary = args.vectorSupport
+                ? await args.vectorSupport.hasBinaryRows(args.exec, args.table, args.column, args.tail ?? '', args.params)
+                : (await args.exec(`SELECT 1 FROM ${args.table}${args.tail ? `${args.tail} AND` : ' WHERE'} typeof(${args.column}) = 'blob' LIMIT 1`, args.params)).length > 0;
+            if (binary)
+                continue;
+        }
+        const params = { ...args.params };
+        const query = buildSqliteVectorQuery({
+            strategy,
+            metric: normalizeMetric(args.metric),
+            table: args.table,
+            column: args.column,
+            vector: args.vector,
+            take: args.take,
+            tail: args.tail ?? '',
+            params,
+        });
+        try {
+            const rows = await args.exec(query.sql, params);
+            return { rows: rows ?? [], strategy };
+        }
+        catch {
+            // The driver advertised the capability but the query failed, e.g. an
+            // extension that did not really load. The next strategy is cheaper than
+            // reporting the failure, and memory is always available as a last resort.
+        }
+    }
+    return null;
+}

package/dotnet/An5Adapter.cs

@@ -19,21 +19,34 @@ namespace An5Orm
         private readonly int _commandTimeout;
 
         public An5Adapter(string connectionString, int commandTimeout = 60)
+            : this(connectionString, commandTimeout, null) { }
+
+        public An5Adapter(string connectionString, int commandTimeout, SqliteVectorSupport vectorSupport)
         {
             ConnectionString = connectionString ?? throw new ArgumentNullException(nameof(connectionString));
             _commandTimeout = commandTimeout;
             _engine = DialectDetector.Detect(connectionString) switch
             {
                 Dialect.Postgres => new PostgresEngine(connectionString, commandTimeout),
-                Dialect.Sqlite => new SqliteEngine(connectionString, commandTimeout),
+                Dialect.Sqlite => new SqliteEngine(connectionString, commandTimeout, vectorSupport),
                 _ => new MssqlEngine(connectionString, commandTimeout)
             };
         }
 
-        public An5Adapter(An5AdapterOptions options) : this(options.ConnectionString, options.CommandTimeout) { }
+        public An5Adapter(An5AdapterOptions options)
+            : this(options.ConnectionString, options.CommandTimeout,
+                   new SqliteVectorSupport { SqliteVecPath = options.SqliteVec, Preference = options.VectorStrategy })
+        { }
 
         // ── Raw query execution ────────────────────────────────────────────────
 
+        /// <summary>
+        /// SQLite only: the vector hooks of the configured connection, or null on
+        /// the other providers. `VectorSearch` needs them to rank a `VECTOR(n)`
+        /// column inside the database.
+        /// </summary>
+        public SqliteVectorSupport VectorSupport => _engine.VectorSupport;
+
         public List<Dictionary<string, object>> QueryRaw(string sql, Dictionary<string, object> parameters = null)
             => _engine.QueryRaw(sql, parameters);
 
@@ -895,7 +908,20 @@ namespace An5Orm
         public List<(T Item, double Distance)> VectorSearch(VectorSearchArgs args)
         {
             args ??= new VectorSearchArgs();
-            return VectorSearch(args.Vector, args.Take, null, null, args.VectorField, args.DistanceMetric);
+            Dictionary<string, object> parameters = null;
+            string whereSql = null;
+            if (args.Where != null)
+            {
+                parameters = new Dictionary<string, object>();
+                whereSql = SqlBuilder.ParseWhere(args.Where, parameters, _dialect);
+            }
+            return VectorSearch(
+                args.Vector,
+                args.Take,
+                string.IsNullOrEmpty(whereSql) ? null : whereSql,
+                parameters,
+                args.VectorField,
+                args.DistanceMetric);
         }
 
         public T FindFirst(string whereClause = null, Dictionary<string, object> parameters = null, string orderBy = null)
@@ -1006,10 +1032,29 @@ namespace An5Orm
             string whereClause = null, Dictionary<string, object> parameters = null,
             string vectorField = "Embedding", string distanceMetric = "cosine")
         {
-            // 1. Primary path: Native database SQL vector query execution (MSSQL VECTOR_DISTANCE / Postgres pgvector)
-            //    SQLite has no vector operator, so it is skipped outright: building the
-            //    statement only to have it rejected costs a round trip and lands on the
-            //    in-memory path below anyway.
+            // 1. SQLite ranks through sqlite-vec, a driver function or json_each,
+            //    whichever this connection supports, so the table never has to
+            //    leave the database.
+            if (_dialect == Dialect.Sqlite)
+            {
+                var p = parameters != null ? new Dictionary<string, object>(parameters) : new Dictionary<string, object>();
+                var quotedVectorField = SqlQuote.QuoteName(vectorField, _dialect);
+                var ranked = SqliteVectors.RunSearch(
+                    _adapter.QueryRaw,
+                    _tableName,
+                    _rawTable.Trim('[', ']'),
+                    quotedVectorField,
+                    vectorField,
+                    vector,
+                    distanceMetric,
+                    take,
+                    string.IsNullOrWhiteSpace(whereClause) ? "" : $" WHERE {whereClause}",
+                    p,
+                    _adapter.VectorSupport);
+                if (ranked != null) return ToRanked(ranked, take);
+            }
+
+            // 2. Primary path: Native database SQL vector query execution (MSSQL VECTOR_DISTANCE / Postgres pgvector)
             if (_dialect != Dialect.Sqlite)
             try
             {
@@ -1063,7 +1108,7 @@ namespace An5Orm
                 // Secondary fallback: In-memory similarity computation if DB instance lacks native vector extension
             }
 
-            // 2. Secondary fallback: In-memory similarity computation
+            // 3. Secondary fallback: In-memory similarity computation
             var rows = FindMany(whereClause, parameters);
             var results = new List<(T, double)>();
             var vectorProp = typeof(T).GetProperty(vectorField, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase);
@@ -1071,33 +1116,59 @@ namespace An5Orm
 
             foreach (var row in rows)
             {
-                var rawVal = vectorProp.GetValue(row);
-                if (rawVal == null) continue;
-                List<double> vec = null;
-                try
-                {
-                    if (rawVal is string s) vec = JsonSerializer.Deserialize<List<double>>(s);
-                }
-                catch { continue; }
+                // A float32 BLOB, a legacy JSON text column or an already-decoded
+                // array all decode the same way.
+                var vec = SqliteVectors.DecodeVector(vectorProp.GetValue(row));
                 if (vec == null || vec.Count != vector.Count) continue;
-
-                double dot = 0, m1 = 0, m2 = 0;
-                for (int i = 0; i < vector.Count; i++)
-                {
-                    dot += vector[i] * vec[i];
-                    m1 += vector[i] * vector[i];
-                    m2 += vec[i] * vec[i];
-                }
-                double cosine = (m1 > 0 && m2 > 0) ? dot / (Math.Sqrt(m1) * Math.Sqrt(m2)) : 0;
-                double dist = distanceMetric.Equals("cosine", StringComparison.OrdinalIgnoreCase) ? 1.0 - cosine :
-                              distanceMetric.Equals("dot", StringComparison.OrdinalIgnoreCase) ? -dot : EuclideanDistance(vector, vec);
-                results.Add((row, dist));
+                var dist = SqliteVectors.VectorDistance(vector, vec, distanceMetric);
+                if (!dist.HasValue) continue;
+                results.Add((row, dist.Value));
             }
 
             results.Sort((a, b) => a.Item2.CompareTo(b.Item2));
             return results.GetRange(0, Math.Min(take, results.Count));
         }
 
+        /// <summary>
+        /// Projects the ranked rows the in-database strategies return into the
+        /// caller's entity type, taking `distance` from the added column.
+        /// </summary>
+        private List<(T, double)> ToRanked(List<Dictionary<string, object>> rows, int take)
+        {
+            var results = new List<(T, double)>();
+            foreach (var row in rows)
+            {
+                var item = Activator.CreateInstance<T>();
+                foreach (var prop in typeof(T).GetProperties(BindingFlags.Public | BindingFlags.Instance))
+                {
+                    if (!row.TryGetValue(prop.Name, out var value) || value == null) continue;
+                    if (prop.Name.Equals("Distance", StringComparison.OrdinalIgnoreCase))
+                    {
+                        if (value is double d) prop.SetValue(item, d);
+                        continue;
+                    }
+                    // A vector column arrives as float32 bytes; the entity declares
+                    // it as float[].
+                    if (prop.PropertyType == typeof(float[]))
+                    {
+                        var vec = SqliteVectors.DecodeVector(value);
+                        if (vec != null)
+                        {
+                            prop.SetValue(item, vec.Select(v => (float)v).ToArray());
+                            continue;
+                        }
+                    }
+                    try { prop.SetValue(item, Convert.ChangeType(value, prop.PropertyType)); } catch { }
+                }
+                double distance = row.TryGetValue("distance", out var raw) && raw != null
+                    ? Convert.ToDouble(raw)
+                    : 0;
+                results.Add((item, distance));
+                if (results.Count >= take) break;
+            }
+            return results;
+        }
+
         private static double EuclideanDistance(List<double> left, List<double> right)
         {
             double sum = 0;

package/dotnet/Base/Core.cs

@@ -18,6 +18,17 @@ public enum Dialect
         public string ConnectionString { get; set; }
         public int CommandTimeout { get; set; } = 60;
         public int ConnectRetryCount { get; set; } = 3;
+        /// <summary>
+        /// SQLite only: path to the sqlite-vec extension binary. Loaded on every
+        /// connection so vector search ranks inside the database. Other
+        /// providers ignore it.
+        /// </summary>
+        public string SqliteVec { get; set; }
+        /// <summary>
+        /// SQLite only: pin one of "sqlite-vec" | "udf" | "sql" | "memory"
+        /// instead of probing for the fastest strategy available.
+        /// </summary>
+        public string VectorStrategy { get; set; }
     }
 
     // ─── Query Engine Interface ────────────────────────────────────────────────
@@ -29,6 +40,9 @@ public enum Dialect
         List<T> QueryRaw<T>(string sql, Dictionary<string, object> parameters) where T : new();
         int ExecuteRaw(string sql, Dictionary<string, object> parameters);
         An5TransactionBase BeginTransaction();
+
+        /// <summary>SQLite only: extension loading and distance-function registration.</summary>
+        SqliteVectorSupport VectorSupport { get; }
     }
 
     // ─── Transaction base ──────────────────────────────────────────────────────