@an5/adapters 0.2.11 → 0.2.13

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);
 
@@ -1006,10 +1019,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 +1095,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 +1103,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 ──────────────────────────────────────────────────────

package/dotnet/Mssql/MssqlEngine.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Data;
+using System.Globalization;
 using System.Reflection;
 using Microsoft.Data.SqlClient;
 
@@ -11,6 +12,8 @@ namespace An5Orm
     internal class MssqlEngine : IQueryEngine
     {
         public Dialect Dialect => Dialect.Mssql;
+        // Only SQLite has a vector hook; this provider has none to offer.
+        public SqliteVectorSupport VectorSupport => null;
         private readonly string _connectionString;
         private readonly int _commandTimeout;
 
@@ -32,6 +35,33 @@ namespace An5Orm
             return conn;
         }
 
+        /// <summary>
+        /// Converts a value into something SqlClient can bind.
+        /// </summary>
+        /// <remarks>
+        /// A <c>VECTOR</c> column is transmitted as a JSON array over TDS, so a float or
+        /// double array is written in that form. Binding the array itself is not an option:
+        /// SqlClient has no mapping for it, and the failure names the array rather than the
+        /// column. Driver versions before 6.1 have no <c>SqlVector</c> either, so the JSON
+        /// form is what every version accepts.
+        /// </remarks>
+        private static object BindableValue(object value)
+        {
+            if (value is float[] floats)
+            {
+                var parts = new string[floats.Length];
+                for (int i = 0; i < floats.Length; i++) parts[i] = floats[i].ToString("R", CultureInfo.InvariantCulture);
+                return "[" + string.Join(", ", parts) + "]";
+            }
+            if (value is double[] doubles)
+            {
+                var parts = new string[doubles.Length];
+                for (int i = 0; i < doubles.Length; i++) parts[i] = doubles[i].ToString("R", CultureInfo.InvariantCulture);
+                return "[" + string.Join(", ", parts) + "]";
+            }
+            return value;
+        }
+
         private SqlCommand BuildCommand(
             SqlConnection conn, string sql, Dictionary<string, object> parameters)
         {
@@ -42,7 +72,7 @@ namespace An5Orm
                 foreach (var kv in parameters)
                 {
                     var paramName = kv.Key.StartsWith("@") ? kv.Key : "@" + kv.Key;
-                    cmd.Parameters.AddWithValue(paramName, kv.Value ?? DBNull.Value);
+                    cmd.Parameters.AddWithValue(paramName, BindableValue(kv.Value) ?? DBNull.Value);
                 }
             }
             return cmd;
@@ -87,6 +117,19 @@ namespace An5Orm
                         if (!HasColumn(reader, prop.Name)) continue;
                         var val = reader[prop.Name];
                         if (val == DBNull.Value) continue;
+                        // A `VECTOR` column arrives as a JSON array, which no converter
+                        // bridges to the `float[]` the entity declares.
+                        if (prop.PropertyType == typeof(float[]))
+                        {
+                            var vector = SqliteVectors.DecodeVector(val);
+                            if (vector != null)
+                            {
+                                var floats = new float[vector.Count];
+                                for (int i = 0; i < vector.Count; i++) floats[i] = (float)vector[i];
+                                prop.SetValue(item, floats);
+                                continue;
+                            }
+                        }
                         try { prop.SetValue(item, Convert.ChangeType(val, prop.PropertyType)); } catch { }
                     }
                     results.Add(item);

package/dotnet/Postgres/PostgresEngine.cs

@@ -10,6 +10,8 @@ namespace An5Orm
     internal class PostgresEngine : IQueryEngine
     {
         public Dialect Dialect => Dialect.Postgres;
+        // Only SQLite has a vector hook; this provider has none to offer.
+        public SqliteVectorSupport VectorSupport => null;
         private readonly string _connectionString;
         private readonly int _commandTimeout;
 

package/dotnet/Sqlite/SqliteEngine.cs

@@ -18,13 +18,15 @@ namespace An5Orm
     internal class SqliteEngine : IQueryEngine
     {
         public Dialect Dialect => Dialect.Sqlite;
+        public SqliteVectorSupport VectorSupport { get; }
         private readonly string _connectionString;
         private readonly int _commandTimeout;
 
-        public SqliteEngine(string connectionString, int commandTimeout)
+        public SqliteEngine(string connectionString, int commandTimeout, SqliteVectorSupport vectorSupport = null)
         {
             _connectionString = SqliteConnectionString.Normalize(connectionString);
             _commandTimeout = commandTimeout;
+            VectorSupport = vectorSupport ?? new SqliteVectorSupport();
         }
 
         // Set while a transaction is open; statements then join it instead of
@@ -40,9 +42,71 @@ namespace An5Orm
             using var pragma = conn.CreateCommand();
             pragma.CommandText = "PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON;";
             pragma.ExecuteNonQuery();
+            PrepareVectorSearch(conn);
             return conn;
         }
 
+        /// <summary>
+        /// Registers the distance functions and loads sqlite-vec so a `VECTOR(n)`
+        /// column is ranked by SQLite instead of by the client. Neither is
+        /// required: a connection that refuses both falls back to `json_each`, or
+        /// to scoring in C#.
+        ///
+        /// This runs per connection because the engine opens one per statement,
+        /// and a user function only exists for the connection that declared it.
+        /// </summary>
+        private void PrepareVectorSearch(Microsoft.Data.Sqlite.SqliteConnection conn)
+        {
+            var support = VectorSupport;
+            if (support == null) return;
+
+            var hasVec = false;
+            if (!string.IsNullOrWhiteSpace(support.SqliteVecPath))
+            {
+                try { conn.LoadExtension(support.SqliteVecPath); }
+                catch { /* the extension is optional */ }
+            }
+            if (!hasVec)
+            {
+                try
+                {
+                    using var probe = conn.CreateCommand();
+                    probe.CommandText = "SELECT vec_version()";
+                    probe.ExecuteScalar();
+                    hasVec = true;
+                }
+                catch { /* not loaded */ }
+            }
+
+            var hasUdf = false;
+            try {
+                using var native = conn.CreateCommand();
+                native.CommandText = "SELECT an5_vector_version()";
+                native.ExecuteScalar();
+                support.Report(false, true, true);
+                return;
+            } catch { /* no AN5 native extension */ }
+            try
+            {
+                foreach (var metric in SqliteVectors.An5Functions.Keys)
+                {
+                    var name = SqliteVectors.An5Functions[metric];
+                    var distance = SqliteVectors.MakeDistanceFunction(metric);
+                    // The metric is baked into `distance`; the empty state is
+                    // only there to satisfy the delegate shape.
+                    conn.CreateFunction<object[], object>(
+                        name,
+                        Array.Empty<object>(),
+                        (_state, args) => distance(args),
+                        true);
+                }
+                hasUdf = true;
+            }
+            catch { /* the bundle may not allow user functions */ }
+
+            support.Report(hasVec, hasUdf, true);
+        }
+
         private ConnectionScope<Microsoft.Data.Sqlite.SqliteConnection> Acquire()
             => _txnConn != null
                 ? new ConnectionScope<Microsoft.Data.Sqlite.SqliteConnection>(_txnConn, owned: false)
@@ -67,7 +131,9 @@ namespace An5Orm
                     param.ParameterName = paramName;
                     // A JSON vector or a bool needs a type SQLite will store in a
                     // column rather than coerce to an integer.
-                    if (value is bool flag) param.Value = flag ? 1 : 0;
+                    if (value is float[] || value is double[] || value is List<double>)
+                        param.Value = SqliteVectors.EncodeVector(SqliteVectors.DecodeVector(value));
+                    else if (value is bool flag) param.Value = flag ? 1 : 0;
                     else param.Value = value;
                     cmd.Parameters.Add(param);
                 }
@@ -108,6 +174,20 @@ namespace An5Orm
                     if (!HasColumn(reader, prop.Name)) continue;
                     var val = reader[prop.Name];
                     if (val == DBNull.Value) continue;
+                    // A `VECTOR(n)` column stores a float32 BLOB (and older ones a
+                    // JSON text column) while the entity declares it as float[],
+                    // which no converter bridges.
+                    if (prop.PropertyType == typeof(float[]))
+                    {
+                        var vector = SqliteVectors.DecodeVector(val);
+                        if (vector != null)
+                        {
+                            var floats = new float[vector.Count];
+                            for (int i = 0; i < vector.Count; i++) floats[i] = (float)vector[i];
+                            prop.SetValue(item, floats);
+                            continue;
+                        }
+                    }
                     try { prop.SetValue(item, Convert.ChangeType(val, prop.PropertyType)); } catch { }
                 }
                 results.Add(item);