family-ai-agent 1.0.6 → 1.0.7

package/dist/database/vector/similarity.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Vector Similarity Functions
+ *
+ * Mathematical utilities for computing vector similarity.
+ * Used for in-memory vector search in SQLite mode.
+ */
+/**
+ * Compute cosine similarity between two vectors
+ * Returns a value between -1 and 1, where 1 means identical direction
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Compute Euclidean distance between two vectors
+ */
+export declare function euclideanDistance(a: number[], b: number[]): number;
+/**
+ * Compute dot product of two vectors
+ */
+export declare function dotProduct(a: number[], b: number[]): number;
+/**
+ * Compute L2 norm (magnitude) of a vector
+ */
+export declare function l2Norm(v: number[]): number;
+/**
+ * Normalize a vector to unit length
+ */
+export declare function normalize(v: number[]): number[];
+/**
+ * Parse embedding from JSON string or array
+ */
+export declare function parseEmbedding(value: string | number[] | null | undefined): number[] | null;
+/**
+ * Serialize embedding to JSON string
+ */
+export declare function serializeEmbedding(embedding: number[]): string;
+/**
+ * Compute hash of embedding for caching
+ */
+export declare function hashEmbedding(embedding: number[]): string;
+/**
+ * Quantize embedding to reduce memory usage
+ * Converts float32 to int8 (-128 to 127)
+ */
+export declare function quantize(embedding: number[]): Int8Array;
+/**
+ * Dequantize int8 back to float
+ */
+export declare function dequantize(quantized: Int8Array): number[];
+/**
+ * Cosine similarity for quantized vectors (faster)
+ */
+export declare function quantizedCosineSimilarity(a: Int8Array, b: Int8Array): number;
+declare const _default: {
+    cosineSimilarity: typeof cosineSimilarity;
+    euclideanDistance: typeof euclideanDistance;
+    dotProduct: typeof dotProduct;
+    l2Norm: typeof l2Norm;
+    normalize: typeof normalize;
+    parseEmbedding: typeof parseEmbedding;
+    serializeEmbedding: typeof serializeEmbedding;
+    hashEmbedding: typeof hashEmbedding;
+    quantize: typeof quantize;
+    dequantize: typeof dequantize;
+    quantizedCosineSimilarity: typeof quantizedCosineSimilarity;
+};
+export default _default;
+//# sourceMappingURL=similarity.d.ts.map

package/dist/database/vector/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../../src/database/vector/similarity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAoBjE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAYlE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAW3D;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAM1C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAM/C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,CA0B3F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE9D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAKzD;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,SAAS,CAOvD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,SAAS,GAAG,MAAM,EAAE,CAMzD;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAoB5E;;;;;;;;;;;;;;AAED,wBAYE"}

package/dist/database/vector/similarity.js

@@ -0,0 +1,176 @@
+/**
+ * Vector Similarity Functions
+ *
+ * Mathematical utilities for computing vector similarity.
+ * Used for in-memory vector search in SQLite mode.
+ */
+/**
+ * Compute cosine similarity between two vectors
+ * Returns a value between -1 and 1, where 1 means identical direction
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+ * Compute Euclidean distance between two vectors
+ */
+export function euclideanDistance(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        const diff = a[i] - b[i];
+        sum += diff * diff;
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Compute dot product of two vectors
+ */
+export function dotProduct(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let sum = 0;
+    for (let i = 0; i < a.length; i++) {
+        sum += a[i] * b[i];
+    }
+    return sum;
+}
+/**
+ * Compute L2 norm (magnitude) of a vector
+ */
+export function l2Norm(v) {
+    let sum = 0;
+    for (let i = 0; i < v.length; i++) {
+        sum += v[i] * v[i];
+    }
+    return Math.sqrt(sum);
+}
+/**
+ * Normalize a vector to unit length
+ */
+export function normalize(v) {
+    const norm = l2Norm(v);
+    if (norm === 0) {
+        return v.slice();
+    }
+    return v.map((x) => x / norm);
+}
+/**
+ * Parse embedding from JSON string or array
+ */
+export function parseEmbedding(value) {
+    if (!value)
+        return null;
+    if (Array.isArray(value)) {
+        return value;
+    }
+    try {
+        // Try parsing as JSON array
+        const parsed = JSON.parse(value);
+        if (Array.isArray(parsed)) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        // Try parsing as PostgreSQL vector format: [0.1, 0.2, ...]
+        const match = value.match(/^\[(.+)\]$/);
+        if (match) {
+            try {
+                return match[1].split(',').map((s) => parseFloat(s.trim()));
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Serialize embedding to JSON string
+ */
+export function serializeEmbedding(embedding) {
+    return JSON.stringify(embedding);
+}
+/**
+ * Compute hash of embedding for caching
+ */
+export function hashEmbedding(embedding) {
+    // Simple hash using first and last few elements + length
+    const first = embedding.slice(0, 4).map((n) => n.toFixed(4)).join(',');
+    const last = embedding.slice(-4).map((n) => n.toFixed(4)).join(',');
+    return `${embedding.length}:${first}:${last}`;
+}
+/**
+ * Quantize embedding to reduce memory usage
+ * Converts float32 to int8 (-128 to 127)
+ */
+export function quantize(embedding) {
+    const quantized = new Int8Array(embedding.length);
+    for (let i = 0; i < embedding.length; i++) {
+        // Scale from [-1, 1] to [-128, 127]
+        quantized[i] = Math.round(Math.max(-128, Math.min(127, embedding[i] * 127)));
+    }
+    return quantized;
+}
+/**
+ * Dequantize int8 back to float
+ */
+export function dequantize(quantized) {
+    const result = new Array(quantized.length);
+    for (let i = 0; i < quantized.length; i++) {
+        result[i] = quantized[i] / 127;
+    }
+    return result;
+}
+/**
+ * Cosine similarity for quantized vectors (faster)
+ */
+export function quantizedCosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+export default {
+    cosineSimilarity,
+    euclideanDistance,
+    dotProduct,
+    l2Norm,
+    normalize,
+    parseEmbedding,
+    serializeEmbedding,
+    hashEmbedding,
+    quantize,
+    dequantize,
+    quantizedCosineSimilarity,
+};
+//# sourceMappingURL=similarity.js.map

package/dist/database/vector/similarity.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "family-ai-agent",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Multi-agent AI system with memory and autonomous capabilities",
   "type": "module",
   "main": "dist/index.js",
@@ -50,7 +50,9 @@
     "jsdom": "^25.0.1",
     "validator": "^13.12.0",
     "dockerode": "^4.0.2",
-    "marked": "^15.0.4"
+    "marked": "^15.0.4",
+    "sql.js": "^1.11.0",
+    "better-sqlite3": "^11.6.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",
@@ -65,7 +67,8 @@
     "prettier": "^3.4.2",
     "drizzle-kit": "^0.30.1",
     "@typescript-eslint/eslint-plugin": "^8.18.1",
-    "@typescript-eslint/parser": "^8.18.1"
+    "@typescript-eslint/parser": "^8.18.1",
+    "@types/better-sqlite3": "^7.6.11"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/database/adapters/base-adapter.ts

@@ -0,0 +1,171 @@
+/**
+ * Base Database Adapter
+ *
+ * Abstract base class for database adapters.
+ * Provides common functionality and interface contract.
+ */
+
+import type {
+  DatabaseAdapter,
+  DatabaseType,
+  QueryResult,
+  TransactionClient,
+  PoolStats,
+} from '../types.js';
+import { createLogger } from '../../utils/logger.js';
+import { MemoryError } from '../../utils/errors.js';
+
+const logger = createLogger('DatabaseAdapter');
+
+/**
+ * Abstract base adapter class
+ */
+export abstract class BaseAdapter implements DatabaseAdapter {
+  abstract readonly type: DatabaseType;
+  protected _isInitialized = false;
+
+  get isInitialized(): boolean {
+    return this._isInitialized;
+  }
+
+  /**
+   * Initialize the database connection
+   */
+  abstract initialize(): Promise<void>;
+
+  /**
+   * Execute a raw SQL query
+   */
+  abstract query<T extends Record<string, any> = Record<string, any>>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<QueryResult<T>>;
+
+  /**
+   * Execute a transaction
+   */
+  abstract transaction<T>(
+    callback: (client: TransactionClient) => Promise<T>
+  ): Promise<T>;
+
+  /**
+   * Check database health
+   */
+  abstract healthCheck(): Promise<boolean>;
+
+  /**
+   * Get connection pool statistics
+   */
+  getPoolStats?(): PoolStats;
+
+  /**
+   * Close all connections
+   */
+  abstract close(): Promise<void>;
+
+  /**
+   * Ensure adapter is initialized before operations
+   */
+  protected ensureInitialized(): void {
+    if (!this._isInitialized) {
+      throw new MemoryError('Database adapter not initialized. Call initialize() first.');
+    }
+  }
+
+  /**
+   * Log query execution
+   */
+  protected logQuery(sql: string, durationMs: number, rowCount: number | null): void {
+    logger.debug('Query executed', {
+      database: this.type,
+      duration: durationMs,
+      rows: rowCount,
+      query: sql.slice(0, 100),
+    });
+  }
+
+  /**
+   * Log query error
+   */
+  protected logError(sql: string, error: unknown): void {
+    const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+    logger.error('Query failed', {
+      database: this.type,
+      error: errorMessage,
+      query: sql.slice(0, 100),
+    });
+  }
+
+  /**
+   * Convert PostgreSQL parameter placeholders ($1, $2) to SQLite (?)
+   */
+  protected convertPlaceholders(sql: string): string {
+    return sql.replace(/\$\d+/g, '?');
+  }
+
+  /**
+   * Convert PostgreSQL-specific syntax to SQLite
+   */
+  protected convertToSqlite(sql: string): string {
+    let converted = this.convertPlaceholders(sql);
+
+    // Replace NOW() with CURRENT_TIMESTAMP
+    converted = converted.replace(/NOW\(\)/gi, 'CURRENT_TIMESTAMP');
+
+    // Remove ::type casts
+    converted = converted.replace(/::[a-zA-Z_]+(\[\])?/g, '');
+
+    // Replace JSONB with JSON (SQLite uses text)
+    converted = converted.replace(/JSONB/gi, 'JSON');
+
+    // Replace gen_random_uuid() with a placeholder (handled in code)
+    converted = converted.replace(/gen_random_uuid\(\)/gi, "lower(hex(randomblob(16)))");
+
+    return converted;
+  }
+
+  /**
+   * Extract RETURNING clause from SQL
+   */
+  protected extractReturning(sql: string): string | null {
+    const match = sql.match(/RETURNING\s+(.+?)$/i);
+    return match ? match[1]!.trim() : null;
+  }
+
+  /**
+   * Extract table name from INSERT/UPDATE/DELETE
+   */
+  protected extractTableName(sql: string): string | null {
+    const insertMatch = sql.match(/INSERT\s+INTO\s+["']?(\w+)["']?/i);
+    if (insertMatch) return insertMatch[1]!;
+
+    const updateMatch = sql.match(/UPDATE\s+["']?(\w+)["']?/i);
+    if (updateMatch) return updateMatch[1]!;
+
+    const deleteMatch = sql.match(/DELETE\s+FROM\s+["']?(\w+)["']?/i);
+    if (deleteMatch) return deleteMatch[1]!;
+
+    return null;
+  }
+
+  /**
+   * Check if SQL is a SELECT query
+   */
+  protected isSelectQuery(sql: string): boolean {
+    return sql.trim().toUpperCase().startsWith('SELECT');
+  }
+
+  /**
+   * Check if SQL has RETURNING clause
+   */
+  protected hasReturning(sql: string): boolean {
+    return /RETURNING\s+/i.test(sql);
+  }
+}
+
+/**
+ * Adapter factory function type
+ */
+export type AdapterFactory = () => Promise<DatabaseAdapter>;
+
+export default BaseAdapter;

package/src/database/adapters/index.ts

@@ -0,0 +1,224 @@
+/**
+ * Database Adapter Factory
+ *
+ * Factory for creating database adapters with auto-detection support.
+ * Tries PostgreSQL first, falls back to SQLite automatically.
+ */
+
+import pg from 'pg';
+
+import { PostgresAdapter } from './postgres-adapter.js';
+import { SQLiteAdapter } from './sqlite-adapter.js';
+import { BaseAdapter } from './base-adapter.js';
+import { getDatabaseConfig, buildPostgresUrl, getDefaultSqlitePath } from '../db-config.js';
+import type { DatabaseAdapter, DetectionResult, DatabaseConfig } from '../types.js';
+import { createLogger } from '../../utils/logger.js';
+
+const { Pool } = pg;
+const logger = createLogger('AdapterFactory');
+
+// Singleton adapter instance
+let adapterInstance: DatabaseAdapter | null = null;
+let initPromise: Promise<DatabaseAdapter> | null = null;
+
+/**
+ * Detect which database to use
+ */
+export async function detectDatabase(config: DatabaseConfig): Promise<DetectionResult> {
+  // 1. Check for explicit configuration
+  if (config.type !== 'auto') {
+    if (config.type === 'postgresql') {
+      return {
+        type: 'postgresql',
+        connectionString: config.postgresUrl ?? buildPostgresUrl({
+          DATABASE_URL: config.postgresUrl,
+          DB_HOST: config.postgresHost,
+          DB_PORT: config.postgresPort,
+          DB_USER: config.postgresUser,
+          DB_PASSWORD: config.postgresPassword,
+          DB_NAME: config.postgresDatabase,
+          DB_POOL_MAX: config.postgresPoolMax,
+          DB_POOL_IDLE_TIMEOUT_MS: config.postgresIdleTimeoutMs,
+          DB_POOL_CONNECTION_TIMEOUT_MS: config.postgresConnectionTimeoutMs,
+          DATABASE_TYPE: 'postgresql',
+          SQLITE_PATH: config.sqlitePath,
+          DB_HEALTH_CHECK_INTERVAL_MS: config.healthCheckIntervalMs,
+          DB_CIRCUIT_BREAKER_THRESHOLD: config.circuitBreakerThreshold,
+          DB_CIRCUIT_BREAKER_TIMEOUT_MS: config.circuitBreakerTimeoutMs,
+          DB_CACHE_MAX_SIZE: config.cacheMaxSize,
+          DB_CACHE_TTL_MS: config.cacheTtlMs,
+          VECTOR_DIMENSION: config.vectorDimension,
+          VECTOR_MIN_SIMILARITY: config.vectorMinSimilarity,
+        }),
+        reason: 'Explicit PostgreSQL configuration',
+      };
+    }
+    return {
+      type: 'sqlite',
+      sqlitePath: config.sqlitePath ?? getDefaultSqlitePath(),
+      reason: 'Explicit SQLite configuration',
+    };
+  }
+
+  // 2. Check for DATABASE_URL (usually means PostgreSQL is intended)
+  if (config.postgresUrl) {
+    return {
+      type: 'postgresql',
+      connectionString: config.postgresUrl,
+      reason: 'DATABASE_URL environment variable set',
+    };
+  }
+
+  // 3. Try PostgreSQL connection
+  try {
+    const connectionString = buildPostgresUrl({
+      DATABASE_URL: config.postgresUrl,
+      DB_HOST: config.postgresHost,
+      DB_PORT: config.postgresPort,
+      DB_USER: config.postgresUser,
+      DB_PASSWORD: config.postgresPassword,
+      DB_NAME: config.postgresDatabase,
+      DB_POOL_MAX: config.postgresPoolMax,
+      DB_POOL_IDLE_TIMEOUT_MS: config.postgresIdleTimeoutMs,
+      DB_POOL_CONNECTION_TIMEOUT_MS: config.postgresConnectionTimeoutMs,
+      DATABASE_TYPE: 'auto',
+      SQLITE_PATH: config.sqlitePath,
+      DB_HEALTH_CHECK_INTERVAL_MS: config.healthCheckIntervalMs,
+      DB_CIRCUIT_BREAKER_THRESHOLD: config.circuitBreakerThreshold,
+      DB_CIRCUIT_BREAKER_TIMEOUT_MS: config.circuitBreakerTimeoutMs,
+      DB_CACHE_MAX_SIZE: config.cacheMaxSize,
+      DB_CACHE_TTL_MS: config.cacheTtlMs,
+      VECTOR_DIMENSION: config.vectorDimension,
+      VECTOR_MIN_SIMILARITY: config.vectorMinSimilarity,
+    });
+
+    const pool = new Pool({
+      connectionString,
+      connectionTimeoutMillis: 3000, // Quick timeout for detection
+    });
+
+    try {
+      const client = await pool.connect();
+      await client.query('SELECT 1');
+      client.release();
+      await pool.end();
+
+      logger.info('PostgreSQL connection successful');
+      return {
+        type: 'postgresql',
+        connectionString,
+        reason: 'PostgreSQL connection successful',
+      };
+    } finally {
+      await pool.end().catch(() => {});
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    logger.debug('PostgreSQL not available, falling back to SQLite', { error: message });
+  }
+
+  // 4. Fall back to SQLite
+  const sqlitePath = config.sqlitePath ?? getDefaultSqlitePath();
+  return {
+    type: 'sqlite',
+    sqlitePath,
+    reason: 'PostgreSQL unavailable, using SQLite fallback',
+  };
+}
+
+/**
+ * Create database adapter based on detection result
+ */
+export async function createAdapter(detection: DetectionResult, config: DatabaseConfig): Promise<DatabaseAdapter> {
+  let adapter: DatabaseAdapter;
+
+  if (detection.type === 'postgresql') {
+    adapter = new PostgresAdapter(detection.connectionString!, config);
+  } else {
+    adapter = new SQLiteAdapter(detection.sqlitePath!, config);
+  }
+
+  await adapter.initialize();
+  return adapter;
+}
+
+/**
+ * Get or create the database adapter singleton
+ */
+export async function getAdapter(): Promise<DatabaseAdapter> {
+  if (adapterInstance?.isInitialized) {
+    return adapterInstance;
+  }
+
+  if (!initPromise) {
+    initPromise = initializeAdapter();
+  }
+
+  return initPromise;
+}
+
+/**
+ * Initialize the database adapter
+ */
+async function initializeAdapter(): Promise<DatabaseAdapter> {
+  const config = getDatabaseConfig();
+  const detection = await detectDatabase(config);
+
+  logger.info('Database detected', {
+    type: detection.type,
+    reason: detection.reason,
+    path: detection.sqlitePath,
+  });
+
+  adapterInstance = await createAdapter(detection, config);
+  return adapterInstance;
+}
+
+/**
+ * Close the database adapter
+ */
+export async function closeAdapter(): Promise<void> {
+  if (adapterInstance) {
+    await adapterInstance.close();
+    adapterInstance = null;
+    initPromise = null;
+    logger.info('Database adapter closed');
+  }
+}
+
+/**
+ * Reset adapter (for testing)
+ */
+export function resetAdapter(): void {
+  adapterInstance = null;
+  initPromise = null;
+}
+
+/**
+ * Check if adapter is initialized
+ */
+export function isAdapterInitialized(): boolean {
+  return adapterInstance?.isInitialized ?? false;
+}
+
+/**
+ * Get current adapter type
+ */
+export function getAdapterType(): 'postgresql' | 'sqlite' | null {
+  return adapterInstance?.type ?? null;
+}
+
+// Re-export adapter classes
+export { PostgresAdapter } from './postgres-adapter.js';
+export { SQLiteAdapter } from './sqlite-adapter.js';
+export { BaseAdapter } from './base-adapter.js';
+
+export default {
+  getAdapter,
+  closeAdapter,
+  resetAdapter,
+  detectDatabase,
+  createAdapter,
+  isAdapterInitialized,
+  getAdapterType,
+};