@an5/adapters 0.2.5 → 0.2.6

package/golang/an5_adapter.go

@@ -0,0 +1,314 @@
+// Package an5adapters provides standalone database adapter engines for Go applications.
+package an5adapters
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"sort"
+	"strings"
+
+	"an5adapters/base"
+	"an5adapters/mssql"
+	"an5adapters/postgres"
+	"an5adapters/sqlite"
+)
+
+// Re-export core base types and functions for package root convenience.
+type Dialect = base.Dialect
+type AdapterMetadata = base.AdapterMetadata
+type RelationDef = base.RelationDef
+
+const (
+	DialectMssql    = base.DialectMssql
+	DialectPostgres = base.DialectPostgres
+	DialectSqlite   = base.DialectSqlite
+)
+
+func DetectDialect(connStr string) Dialect {
+	return base.DetectDialect(connStr)
+}
+
+func QuoteIdentifier(name string, dialect Dialect) string {
+	return base.QuoteIdentifier(name, dialect)
+}
+
+func QuoteTable(tableName string, dialect Dialect) string {
+	return base.QuoteTable(tableName, dialect)
+}
+
+func CosineSimilarity(v1, v2 []float64) float64 {
+	return base.CosineSimilarity(v1, v2)
+}
+
+func EuclideanDistance(v1, v2 []float64) float64 {
+	return base.EuclideanDistance(v1, v2)
+}
+
+func DotProduct(v1, v2 []float64) float64 {
+	return base.DotProduct(v1, v2)
+}
+
+// SetAdapterMetadata injects model-to-table metadata from the generated client.
+func SetAdapterMetadata(meta AdapterMetadata) {
+	base.SetAdapterMetadata(meta)
+}
+
+// GetModelToTable returns the current model-to-table mapping.
+func GetModelToTable() map[string]string {
+	return base.GetModelToTable()
+}
+
+// GetRelationsForModel returns the relation definitions for the given model name.
+func GetRelationsForModel(modelName string) map[string]RelationDef {
+	return base.GetRelationsForModel(modelName)
+}
+
+// An5Adapter manages runtime database execution for Go applications.
+type An5Adapter struct {
+	DB      *sql.DB
+	Dialect Dialect
+}
+
+// NewAn5Adapter constructs an An5Adapter instance.
+func NewAn5Adapter(db *sql.DB, connStr string) *An5Adapter {
+	return &An5Adapter{
+		DB:      db,
+		Dialect: base.DetectDialect(connStr),
+	}
+}
+
+// Connect validates the database connection (ping).
+func (a *An5Adapter) Connect(ctx context.Context) error {
+	return a.DB.PingContext(ctx)
+}
+
+// Disconnect closes the underlying database connection pool.
+func (a *An5Adapter) Disconnect() error {
+	return a.DB.Close()
+}
+
+// QueryRaw executes a SELECT query and returns rows as maps.
+func (a *An5Adapter) QueryRaw(ctx context.Context, query string, args ...interface{}) ([]map[string]interface{}, error) {
+	rows, err := a.DB.QueryContext(ctx, query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	cols, err := rows.Columns()
+	if err != nil {
+		return nil, err
+	}
+
+	var results []map[string]interface{}
+	for rows.Next() {
+		columns := make([]interface{}, len(cols))
+		columnPointers := make([]interface{}, len(cols))
+		for i := range columns {
+			columnPointers[i] = &columns[i]
+		}
+
+		if err := rows.Scan(columnPointers...); err != nil {
+			return nil, err
+		}
+
+		m := make(map[string]interface{})
+		for i, colName := range cols {
+			val := columnPointers[i].(*interface{})
+			m[colName] = *val
+		}
+		results = append(results, m)
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+	return results, nil
+}
+
+// ExecuteRaw executes an INSERT, UPDATE, or DELETE query and returns affected rows count.
+func (a *An5Adapter) ExecuteRaw(ctx context.Context, query string, args ...interface{}) (int64, error) {
+	res, err := a.DB.ExecContext(ctx, query, args...)
+	if err != nil {
+		return 0, err
+	}
+	return res.RowsAffected()
+}
+
+// Transaction executes a function within a database transaction.
+func (a *An5Adapter) Transaction(ctx context.Context, fn func(tx *sql.Tx) error) error {
+	tx, err := a.DB.BeginTx(ctx, nil)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		if p := recover(); p != nil {
+			_ = tx.Rollback()
+			panic(p)
+		}
+	}()
+
+	if err := fn(tx); err != nil {
+		_ = tx.Rollback()
+		return err
+	}
+	return tx.Commit()
+}
+
+// VectorSearch ranks rows by vector distance using native SQL execution with in-memory fallback.
+func (a *An5Adapter) VectorSearch(ctx context.Context, tableName string, targetVector []float64, take int, whereClause string, vectorField string, distanceMetric string, args ...interface{}) ([]map[string]interface{}, error) {
+	if vectorField == "" {
+		vectorField = "embedding"
+	}
+	if distanceMetric == "" {
+		distanceMetric = "cosine"
+	}
+	dim := len(targetVector)
+	vecBytes, _ := json.Marshal(targetVector)
+	vecStr := string(vecBytes)
+
+	// 1. Primary path: Native database SQL vector query execution via dialect provider (mssql / postgres / sqlite)
+	var sqlQuery string
+	if a.Dialect == base.DialectPostgres {
+		sqlQuery = postgres.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
+	} else if a.Dialect == base.DialectMssql {
+		sqlQuery = mssql.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
+	} else if a.Dialect == base.DialectSqlite {
+		sqlQuery = sqlite.BuildVectorSearchQuery(tableName, vectorField, distanceMetric, dim, take, whereClause)
+	}
+
+	if sqlQuery != "" {
+		queryArgs := append([]interface{}{vecStr}, args...)
+		nativeRows, err := a.QueryRaw(ctx, sqlQuery, queryArgs...)
+		if err == nil {
+			return nativeRows, nil
+		}
+	}
+
+	// 2. Secondary fallback: Fetch rows and compute vector distance in-memory if DB lacks native vector extensions
+	fallbackQuery := "SELECT * FROM " + base.QuoteTable(tableName, a.Dialect)
+	if strings.TrimSpace(whereClause) != "" {
+		fallbackQuery += " WHERE " + whereClause
+	}
+
+	rows, err := a.QueryRaw(ctx, fallbackQuery, args...)
+	if err != nil {
+		return nil, err
+	}
+
+	return VectorSearchFallback(rows, targetVector, take, vectorField, distanceMetric), nil
+}
+
+// VectorSearchFallback ranks rows in-memory.
+func VectorSearchFallback(rows []map[string]interface{}, targetVector []float64, take int, vectorField string, distanceMetric string) []map[string]interface{} {
+	type scored struct {
+		row      map[string]interface{}
+		distance float64
+	}
+	var list []scored
+
+	for _, r := range rows {
+		raw, ok := r[vectorField]
+		if !ok || raw == nil {
+			continue
+		}
+
+		var rowVec []float64
+		switch v := raw.(type) {
+		case string:
+			_ = json.Unmarshal([]byte(v), &rowVec)
+		case []byte:
+			_ = json.Unmarshal(v, &rowVec)
+		case []float64:
+			rowVec = v
+		case []interface{}:
+			for _, item := range v {
+				if f, ok := item.(float64); ok {
+					rowVec = append(rowVec, f)
+				}
+			}
+		}
+
+		if len(rowVec) != len(targetVector) {
+			continue
+		}
+
+		var dist float64
+		switch strings.ToLower(distanceMetric) {
+		case "euclidean":
+			dist = base.EuclideanDistance(targetVector, rowVec)
+		case "dot":
+			dist = -base.DotProduct(targetVector, rowVec)
+		default: // cosine
+			dist = 1.0 - base.CosineSimilarity(targetVector, rowVec)
+		}
+
+		rCopy := make(map[string]interface{})
+		for k, val := range r {
+			rCopy[k] = val
+		}
+		rCopy["distance"] = dist
+		list = append(list, scored{row: rCopy, distance: dist})
+	}
+
+	sort.Slice(list, func(i, j int) bool {
+		return list[i].distance < list[j].distance
+	})
+
+	var result []map[string]interface{}
+	limit := take
+	if limit <= 0 || limit > len(list) {
+		limit = len(list)
+	}
+	for i := 0; i < limit; i++ {
+		result = append(result, list[i].row)
+	}
+	return result
+}
+
+// QueryProc executes a stored procedure and returns the result rows.
+func (a *An5Adapter) QueryProc(ctx context.Context, procName string, args ...interface{}) ([]map[string]interface{}, error) {
+	var sql string
+	if a.Dialect == base.DialectPostgres {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = placeholder(a.Dialect, i+1)
+		}
+		sql = "CALL " + procName + "(" + strings.Join(placeholders, ", ") + ")"
+	} else {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = "?"
+		}
+		if len(placeholders) > 0 {
+			sql = "EXEC " + procName + " " + strings.Join(placeholders, ", ")
+		} else {
+			sql = "EXEC " + procName
+		}
+	}
+	return a.QueryRaw(ctx, sql, args...)
+}
+
+// ExecuteProc executes a stored procedure and returns affected rows.
+func (a *An5Adapter) ExecuteProc(ctx context.Context, procName string, args ...interface{}) (int64, error) {
+	var sql string
+	if a.Dialect == base.DialectPostgres {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = placeholder(a.Dialect, i+1)
+		}
+		sql = "CALL " + procName + "(" + strings.Join(placeholders, ", ") + ")"
+	} else {
+		placeholders := make([]string, len(args))
+		for i := range args {
+			placeholders[i] = "?"
+		}
+		if len(placeholders) > 0 {
+			sql = "EXEC " + procName + " " + strings.Join(placeholders, ", ")
+		} else {
+			sql = "EXEC " + procName
+		}
+	}
+	return a.ExecuteRaw(ctx, sql, args...)
+}
+

package/golang/base/base.go

@@ -0,0 +1,100 @@
+// Package base provides core dialect types, quoting utilities, and vector math for AN5 Go Adapters.
+package base
+
+import (
+	"math"
+	"strings"
+)
+
+// Dialect represents supported database engines.
+type Dialect string
+
+const (
+	DialectMssql    Dialect = "mssql"
+	DialectPostgres Dialect = "postgres"
+	DialectSqlite   Dialect = "sqlite"
+)
+
+// DetectDialect parses connection string to determine database dialect.
+func DetectDialect(connStr string) Dialect {
+	lower := strings.ToLower(strings.TrimSpace(connStr))
+	if strings.HasPrefix(lower, "postgres://") || strings.HasPrefix(lower, "postgresql://") || strings.Contains(lower, "port=5432") {
+		return DialectPostgres
+	}
+	if strings.HasPrefix(lower, "sqlite://") || strings.HasPrefix(lower, "sqlite:") || strings.HasPrefix(lower, "file:") || strings.HasSuffix(lower, ".db") || strings.HasSuffix(lower, ".sqlite") || strings.HasSuffix(lower, ".sqlite3") || lower == ":memory:" {
+		return DialectSqlite
+	}
+	return DialectMssql
+}
+
+// QuoteIdentifier quotes column or identifier names according to dialect.
+func QuoteIdentifier(name string, dialect Dialect) string {
+	raw := stripWrapping(name, "[", "]")
+	if dialect == DialectPostgres || dialect == DialectSqlite {
+		raw = stripWrapping(raw, `"`, `"`)
+		return `"` + strings.ReplaceAll(raw, `"`, `""`) + `"`
+	}
+	return "[" + strings.ReplaceAll(raw, "]", "]]") + "]"
+}
+
+// QuoteTable quotes schema-qualified table names (e.g. "dbo.users" -> "[dbo].[users]").
+func QuoteTable(tableName string, dialect Dialect) string {
+	if strings.HasPrefix(tableName, "[") || strings.HasPrefix(tableName, `"`) {
+		return tableName
+	}
+	parts := strings.Split(tableName, ".")
+	var quoted []string
+	for _, p := range parts {
+		quoted = append(quoted, QuoteIdentifier(p, dialect))
+	}
+	return strings.Join(quoted, ".")
+}
+
+func stripWrapping(name, left, right string) string {
+	if strings.HasPrefix(name, left) && strings.HasSuffix(name, right) {
+		return strings.TrimSuffix(strings.TrimPrefix(name, left), right)
+	}
+	return name
+}
+
+// CosineSimilarity computes cosine similarity between two float64 vectors.
+func CosineSimilarity(v1, v2 []float64) float64 {
+	if len(v1) != len(v2) || len(v1) == 0 {
+		return 0
+	}
+	var dot, m1, m2 float64
+	for i := 0; i < len(v1); i++ {
+		dot += v1[i] * v2[i]
+		m1 += v1[i] * v1[i]
+		m2 += v2[i] * v2[i]
+	}
+	if m1 == 0 || m2 == 0 {
+		return 0
+	}
+	return dot / (math.Sqrt(m1) * math.Sqrt(m2))
+}
+
+// EuclideanDistance computes L2 distance between two float64 vectors.
+func EuclideanDistance(v1, v2 []float64) float64 {
+	if len(v1) != len(v2) || len(v1) == 0 {
+		return 0
+	}
+	var sum float64
+	for i := 0; i < len(v1); i++ {
+		diff := v1[i] - v2[i]
+		sum += diff * diff
+	}
+	return math.Sqrt(sum)
+}
+
+// DotProduct computes inner product of two float64 vectors.
+func DotProduct(v1, v2 []float64) float64 {
+	if len(v1) != len(v2) || len(v1) == 0 {
+		return 0
+	}
+	var dot float64
+	for i := 0; i < len(v1); i++ {
+		dot += v1[i] * v2[i]
+	}
+	return dot
+}

package/golang/base/metadata.go

@@ -0,0 +1,116 @@
+// Package base provides core dialect types, quoting utilities, vector math,
+// and adapter metadata for AN5 Go Adapters.
+package base
+
+import (
+	"strings"
+	"sync"
+)
+
+// RelationDef describes a model relation for eager-loading (include) support.
+type RelationDef struct {
+	ModelName    string
+	RelationType string // "many" | "one"
+	ForeignKey   string
+	LocalKey     string
+}
+
+// AdapterMetadata holds model-to-table, field mapping, and relation mapping injected by generated clients.
+type AdapterMetadata struct {
+	ModelToTable map[string]string
+	ModelFields  map[string]interface{}
+	RelationMap  map[string]map[string]RelationDef
+}
+
+var (
+	metaMu       sync.RWMutex
+	modelToTable = map[string]string{}
+	modelFields  = map[string]interface{}{}
+	relationMap  = map[string]map[string]RelationDef{}
+)
+
+// SetAdapterMetadata stores metadata provided by the generated an5Client.
+// Call this once at application startup after initializing the DB context.
+func SetAdapterMetadata(meta AdapterMetadata) {
+	metaMu.Lock()
+	defer metaMu.Unlock()
+	modelToTable = make(map[string]string, len(meta.ModelToTable))
+	for k, v := range meta.ModelToTable {
+		modelToTable[k] = v
+	}
+	modelFields = make(map[string]interface{}, len(meta.ModelFields))
+	for k, v := range meta.ModelFields {
+		modelFields[k] = v
+	}
+	relationMap = make(map[string]map[string]RelationDef, len(meta.RelationMap))
+	for model, rels := range meta.RelationMap {
+		relationMap[model] = make(map[string]RelationDef, len(rels))
+		for key, def := range rels {
+			relationMap[model][key] = def
+		}
+	}
+}
+
+// GetModelToTable returns the model-to-table mapping (read-only snapshot).
+func GetModelToTable() map[string]string {
+	metaMu.RLock()
+	defer metaMu.RUnlock()
+	out := make(map[string]string, len(modelToTable))
+	for k, v := range modelToTable {
+		out[k] = v
+	}
+	return out
+}
+
+// GetFieldsForModel returns field metadata for the given model name.
+func GetFieldsForModel(modelName string) interface{} {
+	metaMu.RLock()
+	defer metaMu.RUnlock()
+	return modelFields[modelName]
+}
+
+// GetRelationsForModel returns the relation map for the given model name (read-only snapshot).
+func GetRelationsForModel(modelName string) map[string]RelationDef {
+	metaMu.RLock()
+	defer metaMu.RUnlock()
+	rels := relationMap[modelName]
+	if rels == nil {
+		return map[string]RelationDef{}
+	}
+	out := make(map[string]RelationDef, len(rels))
+	for k, v := range rels {
+		out[k] = v
+	}
+	return out
+}
+
+// GetRelationMap returns the full model-to-relations map (read-only snapshot).
+func GetRelationMap() map[string]map[string]RelationDef {
+	metaMu.RLock()
+	defer metaMu.RUnlock()
+	out := make(map[string]map[string]RelationDef, len(relationMap))
+	for model, rels := range relationMap {
+		out[model] = make(map[string]RelationDef, len(rels))
+		for k, v := range rels {
+			out[model][k] = v
+		}
+	}
+	return out
+}
+
+// ResolveTable looks up the physical table name for a model name (case-insensitive fallback).
+func ResolveTable(modelName string) string {
+	metaMu.RLock()
+	defer metaMu.RUnlock()
+	if t, ok := modelToTable[modelName]; ok {
+		return t
+	}
+	// lowercase fallback
+	lower := strings.ToLower(modelName)
+	for k, v := range modelToTable {
+		if strings.ToLower(k) == lower {
+			return v
+		}
+	}
+	return modelName
+}