@revealui/ai 0.1.0

package/dist/memory/vector/vector-memory-service.js

@@ -0,0 +1,335 @@
+/**
+ * Vector Memory Service
+ *
+ * Service for managing agent memories in Supabase with vector search capabilities.
+ * Uses pgvector for semantic similarity search.
+ *
+ * @example
+ * ```typescript
+ * import { VectorMemoryService } from '@revealui/ai/memory/vector/vector-memory-service'
+ *
+ * const service = new VectorMemoryService()
+ * const memories = await service.searchSimilar(embedding, { siteId: 'site-123', limit: 10 })
+ * ```
+ */
+import { getVectorClient } from '@revealui/db/client';
+import { agentMemories } from '@revealui/db/schema/vector';
+import { and, eq, sql } from 'drizzle-orm';
+/**
+ * Vector Memory Service for semantic search operations.
+ */
+export class VectorMemoryService {
+    _db = null;
+    /**
+     * Lazy-load database client to avoid connection initialization at module import time.
+     * This allows the module to be imported in test environments without triggering database connections.
+     */
+    get db() {
+        if (!this._db) {
+            this._db = getVectorClient();
+        }
+        return this._db;
+    }
+    /**
+     * Search for similar memories using vector similarity.
+     *
+     * @param queryEmbedding - Query embedding vector (768 dimensions — Ollama nomic-embed-text)
+     * @param options - Search options (filtering, limits, etc.)
+     * @returns Array of memories with similarity scores, sorted by similarity (highest first)
+     *
+     * @example
+     * ```typescript
+     * const embedding = await generateEmbedding('user prefers dark theme')
+     * const results = await service.searchSimilar(embedding, {
+     *   siteId: 'site-123',
+     *   limit: 10,
+     *   threshold: 0.7
+     * })
+     * ```
+     */
+    async searchSimilar(queryEmbedding, options = {}) {
+        // Validate embedding dimensions
+        if (queryEmbedding.length !== 768) {
+            throw new Error(`Invalid embedding dimension: expected 768, got ${queryEmbedding.length}`);
+        }
+        // Build where conditions
+        const conditions = [];
+        if (options.siteId) {
+            conditions.push(eq(agentMemories.siteId, options.siteId));
+        }
+        if (options.agentId) {
+            conditions.push(eq(agentMemories.agentId, options.agentId));
+        }
+        if (options.type) {
+            conditions.push(eq(agentMemories.type, options.type));
+        }
+        // Build query with vector similarity
+        // Using cosine distance (<->) operator from pgvector
+        // 1 - distance = similarity (higher is better)
+        const query = this.db
+            .select({
+            id: agentMemories.id,
+            version: agentMemories.version,
+            content: agentMemories.content,
+            type: agentMemories.type,
+            source: agentMemories.source,
+            embedding: agentMemories.embedding,
+            embeddingMetadata: agentMemories.embeddingMetadata,
+            metadata: agentMemories.metadata,
+            accessCount: agentMemories.accessCount,
+            accessedAt: agentMemories.accessedAt,
+            verified: agentMemories.verified,
+            verifiedBy: agentMemories.verifiedBy,
+            verifiedAt: agentMemories.verifiedAt,
+            siteId: agentMemories.siteId,
+            agentId: agentMemories.agentId,
+            createdAt: agentMemories.createdAt,
+            expiresAt: agentMemories.expiresAt,
+            // Calculate similarity: 1 - cosine_distance
+            // Cosine distance returns 0-2, where 0 is identical
+            // We convert to similarity: 1 - (distance / 2) gives us 0-1 range
+            similarity: sql `1 - (embedding <-> ${JSON.stringify(queryEmbedding)}::vector) / 2`,
+        })
+            .from(agentMemories)
+            .where(and(
+        // Only search memories with embeddings
+        sql `embedding IS NOT NULL`, 
+        // Apply filters
+        ...conditions, 
+        // Apply similarity threshold if provided
+        options.threshold !== undefined
+            ? sql `1 - (embedding <-> ${JSON.stringify(queryEmbedding)}::vector) / 2 >= ${options.threshold}`
+            : undefined))
+            .orderBy(sql `embedding <-> ${JSON.stringify(queryEmbedding)}::vector`)
+            .limit(options.limit ?? 10);
+        const results = await query;
+        // Transform results to match AgentMemory schema
+        return results.map((row) => {
+            // Convert embedding from string format to number array if needed
+            let embedding;
+            if (row.embedding) {
+                // Embedding is stored as vector type, Drizzle should handle conversion
+                // But we need to construct the Embedding object
+                const embeddingMetadata = row.embeddingMetadata;
+                if (embeddingMetadata) {
+                    embedding = {
+                        vector: Array.isArray(row.embedding) ? row.embedding : [],
+                        model: embeddingMetadata.model,
+                        dimension: embeddingMetadata.dimension,
+                        generatedAt: embeddingMetadata.generatedAt,
+                    };
+                }
+            }
+            const memory = {
+                id: row.id,
+                version: row.version,
+                content: row.content,
+                type: row.type,
+                source: row.source,
+                embedding,
+                metadata: row.metadata || {},
+                accessCount: row.accessCount || 0,
+                accessedAt: row.accessedAt?.toISOString() || new Date().toISOString(),
+                verified: row.verified ?? false,
+                createdAt: row.createdAt.toISOString(),
+            };
+            return {
+                memory,
+                similarity: row.similarity || 0,
+            };
+        });
+    }
+    /**
+     * Create a new memory in the vector database.
+     *
+     * @param memory - Memory to create (without id, createdAt, accessedAt)
+     * @returns Created memory with generated id and timestamps
+     */
+    async create(memory) {
+        const id = memory.id || `mem-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+        const now = new Date();
+        // Pass embedding vector directly - Drizzle's vector type will handle conversion
+        // The vector custom type has toDriver() that converts number[] to string format
+        const embeddingVector = memory.embedding?.vector || null;
+        const result = await this.db
+            .insert(agentMemories)
+            .values({
+            id,
+            version: memory.version || 1,
+            content: memory.content,
+            type: memory.type,
+            source: memory.source,
+            embedding: embeddingVector,
+            embeddingMetadata: memory.embedding || null,
+            metadata: memory.metadata || {},
+            accessCount: 0,
+            accessedAt: now,
+            verified: memory.verified,
+            verifiedBy: null, // Can be set via update
+            verifiedAt: null,
+            siteId: memory.metadata?.siteId || null,
+            agentId: memory.metadata?.custom?.agentId || null,
+            createdAt: now,
+            expiresAt: memory.metadata?.expiresAt ? new Date(memory.metadata.expiresAt) : null,
+        })
+            .returning();
+        const row = result[0];
+        if (!row) {
+            throw new Error('Failed to create memory');
+        }
+        // Convert back to AgentMemory format
+        let embedding;
+        if (row.embeddingMetadata) {
+            const metadata = row.embeddingMetadata;
+            embedding = {
+                vector: Array.isArray(row.embedding) ? row.embedding : [],
+                model: metadata.model,
+                dimension: metadata.dimension,
+                generatedAt: metadata.generatedAt,
+            };
+        }
+        return {
+            id: row.id,
+            version: row.version,
+            content: row.content,
+            type: row.type,
+            source: row.source,
+            embedding,
+            metadata: row.metadata || {},
+            accessCount: row.accessCount || 0,
+            accessedAt: row.accessedAt?.toISOString() || now.toISOString(),
+            verified: row.verified ?? false,
+            createdAt: row.createdAt.toISOString(),
+        };
+    }
+    /**
+     * Update an existing memory.
+     *
+     * @param id - Memory ID
+     * @param updates - Partial memory updates
+     * @returns Updated memory
+     */
+    async update(id, updates) {
+        const updateData = {};
+        if (updates.content !== undefined)
+            updateData.content = updates.content;
+        if (updates.type !== undefined)
+            updateData.type = updates.type;
+        if (updates.source !== undefined)
+            updateData.source = updates.source;
+        if (updates.metadata !== undefined)
+            updateData.metadata = updates.metadata;
+        if (updates.verified !== undefined)
+            updateData.verified = updates.verified;
+        if (updates.accessCount !== undefined)
+            updateData.accessCount = updates.accessCount;
+        if (updates.accessedAt !== undefined)
+            updateData.accessedAt = new Date(updates.accessedAt);
+        // Handle embedding update
+        // Pass vector directly - Drizzle's vector type will handle conversion
+        if (updates.embedding !== undefined) {
+            if (updates.embedding) {
+                updateData.embedding = updates.embedding.vector; // number[] - Drizzle converts to string
+                updateData.embeddingMetadata = updates.embedding;
+            }
+            else {
+                updateData.embedding = null;
+                updateData.embeddingMetadata = null;
+            }
+        }
+        // Update siteId and agentId from metadata if provided
+        if (updates.metadata?.siteId !== undefined) {
+            updateData.siteId = updates.metadata.siteId || null;
+        }
+        if (updates.metadata?.custom?.agentId !== undefined) {
+            updateData.agentId = updates.metadata.custom.agentId || null;
+        }
+        const result = await this.db
+            .update(agentMemories)
+            .set(updateData)
+            .where(eq(agentMemories.id, id))
+            .returning();
+        const row = result[0];
+        if (!row) {
+            throw new Error(`Memory not found: ${id}`);
+        }
+        // Convert back to AgentMemory format
+        let embedding;
+        if (row.embeddingMetadata) {
+            const metadata = row.embeddingMetadata;
+            embedding = {
+                vector: Array.isArray(row.embedding) ? row.embedding : [],
+                model: metadata.model,
+                dimension: metadata.dimension,
+                generatedAt: metadata.generatedAt,
+            };
+        }
+        return {
+            id: row.id,
+            version: row.version,
+            content: row.content,
+            type: row.type,
+            source: row.source,
+            embedding,
+            metadata: row.metadata || {},
+            accessCount: row.accessCount || 0,
+            accessedAt: row.accessedAt?.toISOString() || new Date().toISOString(),
+            verified: row.verified ?? false,
+            createdAt: row.createdAt.toISOString(),
+        };
+    }
+    /**
+     * Delete a memory by ID.
+     *
+     * @param id - Memory ID to delete
+     * @returns true if memory was deleted
+     */
+    async delete(id) {
+        const result = await this.db.delete(agentMemories).where(eq(agentMemories.id, id)).returning();
+        return result.length > 0;
+    }
+    /**
+     * Get a memory by ID.
+     *
+     * @param id - Memory ID
+     * @returns Memory if found, null otherwise
+     */
+    async getById(id) {
+        const result = await this.db
+            .select()
+            .from(agentMemories)
+            .where(eq(agentMemories.id, id))
+            .limit(1);
+        if (result.length === 0) {
+            return null;
+        }
+        const row = result[0];
+        if (!row) {
+            return null;
+        }
+        // Convert to AgentMemory format
+        let embedding;
+        if (row.embeddingMetadata) {
+            const metadata = row.embeddingMetadata;
+            embedding = {
+                vector: Array.isArray(row.embedding) ? row.embedding : [],
+                model: metadata.model,
+                dimension: metadata.dimension,
+                generatedAt: metadata.generatedAt,
+            };
+        }
+        return {
+            id: row.id,
+            version: row.version,
+            content: row.content,
+            type: row.type,
+            source: row.source,
+            embedding,
+            metadata: row.metadata || {},
+            accessCount: row.accessCount || 0,
+            accessedAt: row.accessedAt?.toISOString() || new Date().toISOString(),
+            verified: row.verified ?? false,
+            createdAt: row.createdAt.toISOString(),
+        };
+    }
+}

package/dist/observability/logger.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @revealui/ai - Agent Event Logger
+ *
+ * Circular buffer event logger for tracking agent operations.
+ * Maintains last N events in memory with optional persistence.
+ */
+import type { AnyAgentEvent, DecisionEvent, ErrorEvent, EventFilter, EventStorage, LLMCallEvent, ToolCallEvent } from './types.js';
+/**
+ * Agent event logger with circular buffer
+ */
+export declare class AgentEventLogger {
+    private events;
+    private maxEvents;
+    private storage?;
+    private autoFlush;
+    private flushInterval?;
+    constructor(options?: {
+        maxEvents?: number;
+        storage?: EventStorage;
+        autoFlush?: boolean;
+        flushIntervalMs?: number;
+    });
+    /**
+     * Log a decision event
+     */
+    logDecision(event: Omit<DecisionEvent, 'eventType'>): void;
+    /**
+     * Log a tool call event
+     */
+    logToolCall(event: Omit<ToolCallEvent, 'eventType'>): void;
+    /**
+     * Log an LLM call event
+     */
+    logLLMCall(event: Omit<LLMCallEvent, 'eventType'>): void;
+    /**
+     * Log an error event
+     */
+    logError(event: Omit<ErrorEvent, 'eventType'>): void;
+    /**
+     * Add event to circular buffer
+     */
+    private addEvent;
+    /**
+     * Get events matching filter
+     */
+    getEvents(filter?: EventFilter): AnyAgentEvent[];
+    /**
+     * Get recent N events
+     */
+    getRecentEvents(count: number): AnyAgentEvent[];
+    /**
+     * Get events by type
+     */
+    getDecisions(): DecisionEvent[];
+    getToolCalls(): ToolCallEvent[];
+    getLLMCalls(): LLMCallEvent[];
+    getErrors(): ErrorEvent[];
+    /**
+     * Get total event count
+     */
+    getCount(filter?: EventFilter): number;
+    /**
+     * Clear all events from buffer
+     */
+    clear(): void;
+    /**
+     * Flush events to storage
+     */
+    flush(): Promise<void>;
+    /**
+     * Load events from storage
+     */
+    load(filter?: EventFilter): Promise<void>;
+    /**
+     * Cleanup resources
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACd,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAQ;IACzB,OAAO,CAAC,OAAO,CAAC,CAAc;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAC,CAAgB;gBAE1B,OAAO,CAAC,EAAE;QACpB,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,CAAC,EAAE,YAAY,CAAA;QACtB,SAAS,CAAC,EAAE,OAAO,CAAA;QACnB,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB;IAYD;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG,IAAI;IAO1D;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,CAAC,GAAG,IAAI;IAO1D;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,CAAC,GAAG,IAAI;IAOxD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,GAAG,IAAI;IAOpD;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,EAAE;IAoChD;;OAEG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE;IAI/C;;OAEG;IACH,YAAY,IAAI,aAAa,EAAE;IAI/B,YAAY,IAAI,aAAa,EAAE;IAI/B,WAAW,IAAI,YAAY,EAAE;IAI7B,SAAS,IAAI,UAAU,EAAE;IAIzB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM;IAOtC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;OAEG;IACH,OAAO,IAAI,IAAI;CAKhB"}

package/dist/observability/logger.js

@@ -0,0 +1,165 @@
+/**
+ * @revealui/ai - Agent Event Logger
+ *
+ * Circular buffer event logger for tracking agent operations.
+ * Maintains last N events in memory with optional persistence.
+ */
+/**
+ * Agent event logger with circular buffer
+ */
+export class AgentEventLogger {
+    events = [];
+    maxEvents;
+    storage;
+    autoFlush;
+    flushInterval;
+    constructor(options) {
+        this.maxEvents = options?.maxEvents ?? 1000;
+        this.storage = options?.storage;
+        this.autoFlush = options?.autoFlush ?? false;
+        if (this.autoFlush && this.storage && options?.flushIntervalMs) {
+            this.flushInterval = setInterval(() => {
+                void this.flush();
+            }, options.flushIntervalMs);
+        }
+    }
+    /**
+     * Log a decision event
+     */
+    logDecision(event) {
+        this.addEvent({
+            ...event,
+            eventType: 'decision',
+        });
+    }
+    /**
+     * Log a tool call event
+     */
+    logToolCall(event) {
+        this.addEvent({
+            ...event,
+            eventType: 'tool_call',
+        });
+    }
+    /**
+     * Log an LLM call event
+     */
+    logLLMCall(event) {
+        this.addEvent({
+            ...event,
+            eventType: 'llm_call',
+        });
+    }
+    /**
+     * Log an error event
+     */
+    logError(event) {
+        this.addEvent({
+            ...event,
+            eventType: 'error',
+        });
+    }
+    /**
+     * Add event to circular buffer
+     */
+    addEvent(event) {
+        this.events.push(event);
+        // Maintain circular buffer size
+        if (this.events.length > this.maxEvents) {
+            this.events.shift();
+        }
+    }
+    /**
+     * Get events matching filter
+     */
+    getEvents(filter) {
+        let filtered = [...this.events];
+        if (!filter) {
+            return filtered;
+        }
+        if (filter.agentId) {
+            filtered = filtered.filter((e) => e.agentId === filter.agentId);
+        }
+        if (filter.sessionId) {
+            filtered = filtered.filter((e) => e.sessionId === filter.sessionId);
+        }
+        if (filter.taskId) {
+            filtered = filtered.filter((e) => e.taskId === filter.taskId);
+        }
+        if (filter.eventType) {
+            filtered = filtered.filter((e) => e.eventType === filter.eventType);
+        }
+        if (filter.startTime) {
+            const startTime = filter.startTime;
+            filtered = filtered.filter((e) => e.timestamp >= startTime);
+        }
+        if (filter.endTime) {
+            const endTime = filter.endTime;
+            filtered = filtered.filter((e) => e.timestamp <= endTime);
+        }
+        return filtered;
+    }
+    /**
+     * Get recent N events
+     */
+    getRecentEvents(count) {
+        return this.events.slice(-count);
+    }
+    /**
+     * Get events by type
+     */
+    getDecisions() {
+        return this.events.filter((e) => e.eventType === 'decision');
+    }
+    getToolCalls() {
+        return this.events.filter((e) => e.eventType === 'tool_call');
+    }
+    getLLMCalls() {
+        return this.events.filter((e) => e.eventType === 'llm_call');
+    }
+    getErrors() {
+        return this.events.filter((e) => e.eventType === 'error');
+    }
+    /**
+     * Get total event count
+     */
+    getCount(filter) {
+        if (!filter) {
+            return this.events.length;
+        }
+        return this.getEvents(filter).length;
+    }
+    /**
+     * Clear all events from buffer
+     */
+    clear() {
+        this.events = [];
+    }
+    /**
+     * Flush events to storage
+     */
+    async flush() {
+        if (!this.storage) {
+            return;
+        }
+        await this.storage.save([...this.events]);
+    }
+    /**
+     * Load events from storage
+     */
+    async load(filter) {
+        if (!this.storage) {
+            return;
+        }
+        const events = await this.storage.load(filter);
+        this.events = events.slice(-this.maxEvents);
+    }
+    /**
+     * Cleanup resources
+     */
+    destroy() {
+        if (this.flushInterval) {
+            clearInterval(this.flushInterval);
+        }
+    }
+}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @revealui/ai - Agent Metrics Collector
+ *
+ * Aggregates statistics from agent events for monitoring and analysis.
+ */
+import type { AgentEventLogger } from './logger.js';
+import type { AgentMetrics, EventFilter, LLMMetrics, MetricsSummary, ToolMetrics } from './types.js';
+/**
+ * Agent metrics collector
+ */
+export declare class AgentMetricsCollector {
+    private logger;
+    private startTime;
+    constructor(logger: AgentEventLogger);
+    /**
+     * Get metrics for a specific agent
+     */
+    getMetrics(agentId: string): AgentMetrics;
+    /**
+     * Calculate tool-specific metrics
+     */
+    private calculateToolMetrics;
+    /**
+     * Calculate LLM-specific metrics
+     */
+    private calculateLLMMetrics;
+    /**
+     * Get summary metrics across all agents
+     */
+    getMetricsSummary(filter?: EventFilter): MetricsSummary;
+    /**
+     * Get tool usage statistics
+     */
+    getToolUsageStats(): Array<{
+        toolName: string;
+        metrics: ToolMetrics;
+    }>;
+    /**
+     * Get LLM usage statistics
+     */
+    getLLMUsageStats(): LLMMetrics;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,KAAK,EACV,YAAY,EAEZ,WAAW,EACX,UAAU,EACV,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAA;AAEnB;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,SAAS,CAAQ;gBAEb,MAAM,EAAE,gBAAgB;IAKpC;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IA+DzC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqC3B;;OAEG;IACH,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc;IA8CvD;;OAEG;IACH,iBAAiB,IAAI,KAAK,CAAC;QACzB,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,EAAE,WAAW,CAAA;KACrB,CAAC;IASF;;OAEG;IACH,gBAAgB,IAAI,UAAU;CAI/B"}