family-ai-agent 1.0.6 → 1.0.8

package/src/database/types.ts

@@ -0,0 +1,324 @@
+/**
+ * Database Layer Types
+ *
+ * Shared TypeScript types for the database abstraction layer.
+ * Supports both PostgreSQL and SQLite backends.
+ */
+
+import type { DrizzleConfig } from 'drizzle-orm';
+
+/**
+ * Supported database types
+ */
+export type DatabaseType = 'postgresql' | 'sqlite';
+
+/**
+ * Database detection modes
+ */
+export type DatabaseDetectionMode = 'auto' | 'postgresql' | 'sqlite';
+
+/**
+ * Query result row constraint (compatible with pg.QueryResultRow)
+ */
+export type QueryResultRow = Record<string, any>;
+
+/**
+ * Query result interface (compatible with pg.QueryResult)
+ */
+export interface QueryResult<T extends QueryResultRow = Record<string, any>> {
+  rows: T[];
+  rowCount: number | null;
+}
+
+/**
+ * Transaction client interface
+ */
+export interface TransactionClient {
+  query<T extends QueryResultRow = Record<string, any>>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<QueryResult<T>>;
+}
+
+/**
+ * Connection pool statistics
+ */
+export interface PoolStats {
+  total: number;
+  idle: number;
+  waiting: number;
+}
+
+/**
+ * Database health status
+ */
+export interface DatabaseHealth {
+  status: 'healthy' | 'degraded' | 'unhealthy';
+  type: DatabaseType;
+  latencyMs: number;
+  poolStats?: PoolStats;
+  circuitState: CircuitBreakerState;
+  lastCheck: Date;
+  errors: string[];
+}
+
+/**
+ * Circuit breaker states
+ */
+export type CircuitBreakerState = 'closed' | 'open' | 'half-open';
+
+/**
+ * Migration result
+ */
+export interface MigrationResult {
+  version: number;
+  name: string;
+  success: boolean;
+  error?: string;
+  durationMs: number;
+}
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  size: number;
+  maxSize: number;
+  hitCount: number;
+  missCount: number;
+  hitRate: number;
+}
+
+/**
+ * Vector search options
+ */
+export interface VectorSearchOptions {
+  userId?: string;
+  memoryType?: string;
+  limit?: number;
+  minSimilarity?: number;
+}
+
+/**
+ * Vector search result
+ */
+export interface VectorSearchResult {
+  id: string;
+  content: string;
+  similarity: number;
+  memoryType: string;
+  metadata: Record<string, unknown>;
+}
+
+/**
+ * Embedding entry for vector index
+ */
+export interface EmbeddingEntry {
+  id: string;
+  vector: number[];
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Database adapter interface
+ */
+export interface DatabaseAdapter {
+  /** Database type */
+  readonly type: DatabaseType;
+
+  /** Whether the adapter is initialized */
+  readonly isInitialized: boolean;
+
+  /**
+   * Initialize the database connection
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Execute a raw SQL query
+   */
+  query<T extends QueryResultRow = Record<string, any>>(
+    sql: string,
+    params?: unknown[]
+  ): Promise<QueryResult<T>>;
+
+  /**
+   * Execute a transaction
+   */
+  transaction<T>(
+    callback: (client: TransactionClient) => Promise<T>
+  ): Promise<T>;
+
+  /**
+   * Check database health
+   */
+  healthCheck(): Promise<boolean>;
+
+  /**
+   * Get connection pool statistics (PostgreSQL only)
+   */
+  getPoolStats?(): PoolStats;
+
+  /**
+   * Close all connections
+   */
+  close(): Promise<void>;
+}
+
+/**
+ * Vector search engine interface
+ */
+export interface VectorSearchEngine {
+  /**
+   * Initialize the vector index
+   */
+  initialize(): Promise<void>;
+
+  /**
+   * Store an embedding
+   */
+  store(
+    id: string,
+    embedding: number[],
+    metadata?: Record<string, unknown>
+  ): Promise<void>;
+
+  /**
+   * Search for similar embeddings
+   */
+  search(
+    queryEmbedding: number[],
+    options?: VectorSearchOptions
+  ): Promise<VectorSearchResult[]>;
+
+  /**
+   * Remove an embedding
+   */
+  remove(id: string): Promise<void>;
+
+  /**
+   * Rebuild the vector index
+   */
+  rebuildIndex(): Promise<void>;
+
+  /**
+   * Get index statistics
+   */
+  getStats(): { size: number; dimension: number };
+}
+
+/**
+ * Database detection result
+ */
+export interface DetectionResult {
+  type: DatabaseType;
+  connectionString?: string;
+  sqlitePath?: string;
+  reason: string;
+}
+
+/**
+ * Migration definition
+ */
+export interface Migration {
+  version: number;
+  name: string;
+  up: (adapter: DatabaseAdapter) => Promise<void>;
+  down: (adapter: DatabaseAdapter) => Promise<void>;
+}
+
+/**
+ * Cache entry
+ */
+export interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+  hits: number;
+}
+
+/**
+ * Query cache options
+ */
+export interface QueryCacheOptions {
+  maxSize: number;
+  defaultTtlMs: number;
+}
+
+/**
+ * Circuit breaker options
+ */
+export interface CircuitBreakerOptions {
+  failureThreshold: number;
+  resetTimeoutMs: number;
+  halfOpenMaxAttempts: number;
+}
+
+/**
+ * Health monitor options
+ */
+export interface HealthMonitorOptions {
+  checkIntervalMs: number;
+  errorThreshold: number;
+}
+
+/**
+ * Database configuration
+ */
+export interface DatabaseConfig {
+  // Detection mode
+  type: DatabaseDetectionMode;
+
+  // PostgreSQL settings
+  postgresUrl?: string;
+  postgresHost: string;
+  postgresPort: number;
+  postgresUser: string;
+  postgresPassword: string;
+  postgresDatabase: string;
+  postgresPoolMax: number;
+  postgresIdleTimeoutMs: number;
+  postgresConnectionTimeoutMs: number;
+
+  // SQLite settings
+  sqlitePath?: string;
+
+  // Health monitoring
+  healthCheckIntervalMs: number;
+  circuitBreakerThreshold: number;
+  circuitBreakerTimeoutMs: number;
+
+  // Cache settings
+  cacheMaxSize: number;
+  cacheTtlMs: number;
+
+  // Vector settings
+  vectorDimension: number;
+  vectorMinSimilarity: number;
+}
+
+/**
+ * Memory types for vector storage
+ */
+export type MemoryType = 'semantic' | 'episodic' | 'procedural';
+
+/**
+ * Message roles
+ */
+export type MessageRole = 'user' | 'assistant' | 'system';
+
+/**
+ * Task status
+ */
+export type TaskStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * Audit log action types
+ */
+export type AuditActionType =
+  | 'chat_message'
+  | 'memory_store'
+  | 'memory_search'
+  | 'document_upload'
+  | 'agent_invocation'
+  | 'tool_execution'
+  | 'safety_block';

package/src/database/vector/embedding-cache.ts

@@ -0,0 +1,234 @@
+/**
+ * Embedding Cache
+ *
+ * LRU cache for embeddings to avoid redundant database queries.
+ * Improves performance for frequently accessed vectors.
+ */
+
+import { createLogger } from '../../utils/logger.js';
+
+const logger = createLogger('EmbeddingCache');
+
+/**
+ * Cache entry with metadata
+ */
+interface CacheEntry {
+  embedding: number[];
+  metadata?: Record<string, unknown>;
+  accessCount: number;
+  lastAccessed: number;
+  addedAt: number;
+}
+
+/**
+ * Cache statistics
+ */
+export interface EmbeddingCacheStats {
+  size: number;
+  maxSize: number;
+  hitCount: number;
+  missCount: number;
+  hitRate: number;
+  memoryUsageBytes: number;
+}
+
+/**
+ * LRU cache for embeddings
+ */
+export class EmbeddingCache {
+  private cache: Map<string, CacheEntry> = new Map();
+  private maxSize: number;
+  private hitCount: number = 0;
+  private missCount: number = 0;
+  private dimension: number;
+
+  constructor(options: { maxSize?: number; dimension?: number } = {}) {
+    this.maxSize = options.maxSize ?? 10000;
+    this.dimension = options.dimension ?? 1536;
+  }
+
+  /**
+   * Get embedding from cache
+   */
+  get(id: string): number[] | undefined {
+    const entry = this.cache.get(id);
+
+    if (!entry) {
+      this.missCount++;
+      return undefined;
+    }
+
+    // Update access metadata
+    entry.accessCount++;
+    entry.lastAccessed = Date.now();
+
+    // Move to end for LRU
+    this.cache.delete(id);
+    this.cache.set(id, entry);
+
+    this.hitCount++;
+    return entry.embedding;
+  }
+
+  /**
+   * Set embedding in cache
+   */
+  set(id: string, embedding: number[], metadata?: Record<string, unknown>): void {
+    // Evict if at capacity
+    if (this.cache.size >= this.maxSize && !this.cache.has(id)) {
+      this.evictLRU();
+    }
+
+    const entry: CacheEntry = {
+      embedding,
+      metadata,
+      accessCount: 1,
+      lastAccessed: Date.now(),
+      addedAt: Date.now(),
+    };
+
+    // Delete first to ensure it's at the end
+    this.cache.delete(id);
+    this.cache.set(id, entry);
+  }
+
+  /**
+   * Check if ID is in cache
+   */
+  has(id: string): boolean {
+    return this.cache.has(id);
+  }
+
+  /**
+   * Remove embedding from cache
+   */
+  delete(id: string): boolean {
+    return this.cache.delete(id);
+  }
+
+  /**
+   * Clear the cache
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hitCount = 0;
+    this.missCount = 0;
+    logger.debug('Embedding cache cleared');
+  }
+
+  /**
+   * Evict least recently used entry
+   */
+  private evictLRU(): void {
+    // First entry is LRU due to Map ordering
+    const firstKey = this.cache.keys().next().value;
+    if (firstKey) {
+      this.cache.delete(firstKey);
+    }
+  }
+
+  /**
+   * Evict entries matching a pattern
+   */
+  evictPattern(pattern: (id: string) => boolean): number {
+    let count = 0;
+    for (const id of this.cache.keys()) {
+      if (pattern(id)) {
+        this.cache.delete(id);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Get multiple embeddings (batch)
+   */
+  getMany(ids: string[]): Map<string, number[]> {
+    const result = new Map<string, number[]>();
+    for (const id of ids) {
+      const embedding = this.get(id);
+      if (embedding) {
+        result.set(id, embedding);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Set multiple embeddings (batch)
+   */
+  setMany(entries: Array<{ id: string; embedding: number[]; metadata?: Record<string, unknown> }>): void {
+    for (const { id, embedding, metadata } of entries) {
+      this.set(id, embedding, metadata);
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): EmbeddingCacheStats {
+    const totalRequests = this.hitCount + this.missCount;
+    const memoryUsageBytes = this.cache.size * this.dimension * 4; // 4 bytes per float32
+
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hitCount: this.hitCount,
+      missCount: this.missCount,
+      hitRate: totalRequests > 0 ? this.hitCount / totalRequests : 0,
+      memoryUsageBytes,
+    };
+  }
+
+  /**
+   * Get cache size
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Preload embeddings from database records
+   */
+  preload(records: Array<{ id: string; embedding: number[] | string }>): void {
+    for (const record of records) {
+      let embedding: number[];
+
+      if (typeof record.embedding === 'string') {
+        try {
+          embedding = JSON.parse(record.embedding);
+        } catch {
+          continue;
+        }
+      } else {
+        embedding = record.embedding;
+      }
+
+      this.set(record.id, embedding);
+    }
+
+    logger.debug('Embeddings preloaded', { count: records.length });
+  }
+
+  /**
+   * Trim cache to a smaller size
+   */
+  trim(newMaxSize: number): void {
+    if (newMaxSize >= this.cache.size) return;
+
+    const toRemove = this.cache.size - newMaxSize;
+    let removed = 0;
+
+    for (const id of this.cache.keys()) {
+      if (removed >= toRemove) break;
+      this.cache.delete(id);
+      removed++;
+    }
+
+    this.maxSize = newMaxSize;
+    logger.debug('Cache trimmed', { removed, newSize: this.cache.size });
+  }
+}
+
+export default EmbeddingCache;