@snap-agent/analytics 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1143 @@
+// src/storage/MemoryAnalyticsStorage.ts
+var MemoryAnalyticsStorage = class {
+  constructor() {
+    this.requests = [];
+    this.responses = [];
+    this.errors = [];
+  }
+  async saveRequests(requests) {
+    this.requests.push(...requests);
+  }
+  async saveResponses(responses) {
+    this.responses.push(...responses);
+  }
+  async saveErrors(errors) {
+    this.errors.push(...errors);
+  }
+  async getRequests(options) {
+    return this.filterRecords(this.requests, options);
+  }
+  async getResponses(options) {
+    return this.filterRecords(this.responses, options);
+  }
+  async getErrors(options) {
+    return this.filterRecords(this.errors, options);
+  }
+  async getRequestCount(options) {
+    return this.filterRecords(this.requests, options).length;
+  }
+  async getResponseCount(options) {
+    return this.filterRecords(this.responses, options).length;
+  }
+  async getErrorCount(options) {
+    return this.filterRecords(this.errors, options).length;
+  }
+  async deleteOlderThan(date) {
+    const timestamp = date.getTime();
+    const requestsBefore = this.requests.length;
+    this.requests = this.requests.filter((r) => r.timestamp.getTime() >= timestamp);
+    const requestsDeleted = requestsBefore - this.requests.length;
+    const responsesBefore = this.responses.length;
+    this.responses = this.responses.filter((r) => r.timestamp.getTime() >= timestamp);
+    const responsesDeleted = responsesBefore - this.responses.length;
+    const errorsBefore = this.errors.length;
+    this.errors = this.errors.filter((e) => e.timestamp.getTime() >= timestamp);
+    const errorsDeleted = errorsBefore - this.errors.length;
+    return {
+      requests: requestsDeleted,
+      responses: responsesDeleted,
+      errors: errorsDeleted
+    };
+  }
+  async clear() {
+    this.requests = [];
+    this.responses = [];
+    this.errors = [];
+  }
+  async isReady() {
+    return true;
+  }
+  async close() {
+  }
+  /**
+   * Filter records based on query options
+   */
+  filterRecords(records, options) {
+    if (!options) {
+      return [...records];
+    }
+    let filtered = records;
+    if (options.agentId) {
+      filtered = filtered.filter((r) => r.agentId === options.agentId);
+    }
+    if (options.threadId) {
+      filtered = filtered.filter((r) => r.threadId === options.threadId);
+    }
+    if (options.userId) {
+      filtered = filtered.filter((r) => r.userId === options.userId);
+    }
+    if (options.startDate) {
+      const start = options.startDate.getTime();
+      filtered = filtered.filter((r) => r.timestamp.getTime() >= start);
+    }
+    if (options.endDate) {
+      const end = options.endDate.getTime();
+      filtered = filtered.filter((r) => r.timestamp.getTime() <= end);
+    }
+    if (options.offset) {
+      filtered = filtered.slice(options.offset);
+    }
+    if (options.limit) {
+      filtered = filtered.slice(0, options.limit);
+    }
+    return filtered;
+  }
+  /**
+   * Get current storage stats (for debugging)
+   */
+  getStats() {
+    return {
+      requests: this.requests.length,
+      responses: this.responses.length,
+      errors: this.errors.length
+    };
+  }
+};
+
+// src/storage/MongoAnalyticsStorage.ts
+var MongoAnalyticsStorage = class {
+  constructor(config) {
+    this.client = null;
+    this.db = null;
+    this.requestsCollection = null;
+    this.responsesCollection = null;
+    this.errorsCollection = null;
+    this.connectionPromise = null;
+    this.config = {
+      uri: config.uri,
+      database: config.database || "snap-agent-analytics",
+      collectionPrefix: config.collectionPrefix || "analytics",
+      createIndexes: config.createIndexes !== false
+    };
+  }
+  /**
+   * Ensure connection to MongoDB
+   */
+  async ensureConnection() {
+    if (this.db) {
+      return;
+    }
+    if (this.connectionPromise) {
+      return this.connectionPromise;
+    }
+    this.connectionPromise = this.connect();
+    return this.connectionPromise;
+  }
+  async connect() {
+    const { MongoClient } = await import("mongodb");
+    this.client = new MongoClient(this.config.uri);
+    await this.client.connect();
+    this.db = this.client.db(this.config.database);
+    const prefix = this.config.collectionPrefix;
+    this.requestsCollection = this.db.collection(`${prefix}_requests`);
+    this.responsesCollection = this.db.collection(`${prefix}_responses`);
+    this.errorsCollection = this.db.collection(`${prefix}_errors`);
+    if (this.config.createIndexes) {
+      await this.createIndexes();
+    }
+  }
+  async createIndexes() {
+    if (!this.requestsCollection || !this.responsesCollection || !this.errorsCollection) {
+      return;
+    }
+    await this.requestsCollection.createIndexes([
+      { key: { agentId: 1, timestamp: -1 } },
+      { key: { threadId: 1, timestamp: -1 } },
+      { key: { userId: 1, timestamp: -1 } },
+      { key: { timestamp: -1 } }
+    ]);
+    await this.responsesCollection.createIndexes([
+      { key: { agentId: 1, timestamp: -1 } },
+      { key: { threadId: 1, timestamp: -1 } },
+      { key: { userId: 1, timestamp: -1 } },
+      { key: { timestamp: -1 } },
+      { key: { success: 1, timestamp: -1 } }
+    ]);
+    await this.errorsCollection.createIndexes([
+      { key: { agentId: 1, timestamp: -1 } },
+      { key: { errorType: 1, timestamp: -1 } },
+      { key: { timestamp: -1 } }
+    ]);
+  }
+  async saveRequests(requests) {
+    if (requests.length === 0) return;
+    await this.ensureConnection();
+    await this.requestsCollection.insertMany(requests);
+  }
+  async saveResponses(responses) {
+    if (responses.length === 0) return;
+    await this.ensureConnection();
+    await this.responsesCollection.insertMany(responses);
+  }
+  async saveErrors(errors) {
+    if (errors.length === 0) return;
+    await this.ensureConnection();
+    await this.errorsCollection.insertMany(errors);
+  }
+  async getRequests(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    let cursor = this.requestsCollection.find(query).sort({ timestamp: -1 });
+    if (options?.offset) {
+      cursor = cursor.skip(options.offset);
+    }
+    if (options?.limit) {
+      cursor = cursor.limit(options.limit);
+    }
+    return cursor.toArray();
+  }
+  async getResponses(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    let cursor = this.responsesCollection.find(query).sort({ timestamp: -1 });
+    if (options?.offset) {
+      cursor = cursor.skip(options.offset);
+    }
+    if (options?.limit) {
+      cursor = cursor.limit(options.limit);
+    }
+    return cursor.toArray();
+  }
+  async getErrors(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    let cursor = this.errorsCollection.find(query).sort({ timestamp: -1 });
+    if (options?.offset) {
+      cursor = cursor.skip(options.offset);
+    }
+    if (options?.limit) {
+      cursor = cursor.limit(options.limit);
+    }
+    return cursor.toArray();
+  }
+  async getRequestCount(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    return this.requestsCollection.countDocuments(query);
+  }
+  async getResponseCount(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    return this.responsesCollection.countDocuments(query);
+  }
+  async getErrorCount(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    return this.errorsCollection.countDocuments(query);
+  }
+  async deleteOlderThan(date) {
+    await this.ensureConnection();
+    const query = { timestamp: { $lt: date } };
+    const [requestsResult, responsesResult, errorsResult] = await Promise.all([
+      this.requestsCollection.deleteMany(query),
+      this.responsesCollection.deleteMany(query),
+      this.errorsCollection.deleteMany(query)
+    ]);
+    return {
+      requests: requestsResult.deletedCount,
+      responses: responsesResult.deletedCount,
+      errors: errorsResult.deletedCount
+    };
+  }
+  async clear() {
+    await this.ensureConnection();
+    await Promise.all([
+      this.requestsCollection.deleteMany({}),
+      this.responsesCollection.deleteMany({}),
+      this.errorsCollection.deleteMany({})
+    ]);
+  }
+  async isReady() {
+    try {
+      await this.ensureConnection();
+      await this.db.command({ ping: 1 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async close() {
+    if (this.client) {
+      await this.client.close();
+      this.client = null;
+      this.db = null;
+      this.requestsCollection = null;
+      this.responsesCollection = null;
+      this.errorsCollection = null;
+      this.connectionPromise = null;
+    }
+  }
+  /**
+   * Build MongoDB query from options
+   */
+  buildQuery(options) {
+    if (!options) {
+      return {};
+    }
+    const query = {};
+    if (options.agentId) {
+      query.agentId = options.agentId;
+    }
+    if (options.threadId) {
+      query.threadId = options.threadId;
+    }
+    if (options.userId) {
+      query.userId = options.userId;
+    }
+    if (options.startDate || options.endDate) {
+      query.timestamp = {};
+      if (options.startDate) {
+        query.timestamp.$gte = options.startDate;
+      }
+      if (options.endDate) {
+        query.timestamp.$lte = options.endDate;
+      }
+    }
+    return query;
+  }
+  /**
+   * Get aggregated metrics with grouping by time period
+   */
+  async getAggregatedMetrics(options) {
+    await this.ensureConnection();
+    const query = this.buildQuery(options);
+    const [requestCount, responseStats, errorCount] = await Promise.all([
+      this.requestsCollection.countDocuments(query),
+      this.responsesCollection.aggregate([
+        { $match: query },
+        {
+          $group: {
+            _id: null,
+            count: { $sum: 1 },
+            avgLatency: { $avg: "$timings.total" },
+            totalTokens: { $sum: "$tokens.totalTokens" }
+          }
+        }
+      ]).toArray(),
+      this.errorsCollection.countDocuments(query)
+    ]);
+    const stats = responseStats[0] || { count: 0, avgLatency: 0, totalTokens: 0 };
+    return {
+      totalRequests: requestCount,
+      totalResponses: stats.count,
+      totalErrors: errorCount,
+      avgLatency: stats.avgLatency || 0,
+      totalTokens: stats.totalTokens || 0,
+      errorRate: stats.count > 0 ? errorCount / stats.count : 0
+    };
+  }
+};
+
+// src/SnapAgentAnalytics.ts
+var DEFAULT_MODEL_COSTS = {
+  // OpenAI
+  "gpt-4o": { input: 5e-3, output: 0.015 },
+  "gpt-4o-mini": { input: 15e-5, output: 6e-4 },
+  "gpt-4-turbo": { input: 0.01, output: 0.03 },
+  "gpt-4": { input: 0.03, output: 0.06 },
+  "gpt-3.5-turbo": { input: 5e-4, output: 15e-4 },
+  // Anthropic
+  "claude-3-5-sonnet-20241022": { input: 3e-3, output: 0.015 },
+  "claude-3-opus-20240229": { input: 0.015, output: 0.075 },
+  "claude-3-sonnet-20240229": { input: 3e-3, output: 0.015 },
+  "claude-3-haiku-20240307": { input: 25e-5, output: 125e-5 },
+  // Google
+  "gemini-2.0-flash-exp": { input: 0, output: 0 },
+  // Free during preview
+  "gemini-1.5-pro": { input: 125e-5, output: 5e-3 },
+  "gemini-1.5-flash": { input: 75e-6, output: 3e-4 }
+};
+var SnapAgentAnalytics = class {
+  constructor(config = {}) {
+    this.name = "snap-agent-analytics";
+    this.type = "analytics";
+    // In-memory caches (for fast access during aggregation)
+    this.requests = [];
+    this.responses = [];
+    this.errors = [];
+    this.threadStats = /* @__PURE__ */ new Map();
+    this.userSessions = /* @__PURE__ */ new Map();
+    // Counter for IDs
+    this.idCounter = 0;
+    this.pendingRequests = [];
+    this.pendingResponses = [];
+    this.pendingErrors = [];
+    this.isFlushing = false;
+    this.config = {
+      enablePerformance: config.enablePerformance !== false,
+      enableRAG: config.enableRAG !== false,
+      enableCost: config.enableCost !== false,
+      enableConversation: config.enableConversation !== false,
+      enableErrors: config.enableErrors !== false,
+      modelCosts: { ...DEFAULT_MODEL_COSTS, ...config.modelCosts },
+      embeddingCost: config.embeddingCost ?? 1e-4,
+      retentionDays: config.retentionDays ?? 30,
+      flushInterval: config.flushInterval ?? 5e3,
+      onMetric: config.onMetric || (() => {
+      }),
+      storage: config.storage
+    };
+    this.storage = config.storage || new MemoryAnalyticsStorage();
+    if (this.config.retentionDays > 0) {
+      setInterval(() => this.cleanup(), 60 * 60 * 1e3);
+    }
+    if (this.config.storage && this.config.flushInterval > 0) {
+      this.startFlushTimer();
+    }
+  }
+  // ============================================================================
+  // Basic Interface (Backwards Compatible)
+  // ============================================================================
+  /**
+   * Track incoming request (basic)
+   */
+  async trackRequest(data) {
+    await this.trackRequestExtended({
+      agentId: data.agentId,
+      threadId: data.threadId,
+      message: data.message,
+      messageLength: data.message.length,
+      timestamp: data.timestamp
+    });
+  }
+  /**
+   * Track response (basic)
+   */
+  async trackResponse(data) {
+    await this.trackResponseExtended({
+      agentId: data.agentId,
+      threadId: data.threadId,
+      response: data.response,
+      responseLength: data.response.length,
+      timestamp: data.timestamp,
+      timings: { total: data.latency },
+      tokens: {
+        promptTokens: 0,
+        completionTokens: data.tokensUsed || 0,
+        totalTokens: data.tokensUsed || 0
+      },
+      success: true
+    });
+  }
+  // ============================================================================
+  // Extended Interface
+  // ============================================================================
+  /**
+   * Track request with full metadata
+   */
+  async trackRequestExtended(data) {
+    const request = {
+      id: `req-${++this.idCounter}`,
+      agentId: data.agentId,
+      threadId: data.threadId,
+      userId: data.userId,
+      timestamp: data.timestamp,
+      messageLength: data.messageLength,
+      model: data.model,
+      provider: data.provider
+    };
+    this.requests.push(request);
+    this.pendingRequests.push(request);
+    if (this.config.enableConversation && data.threadId) {
+      this.updateThreadStats(data.threadId, data.agentId, data.userId, data.timestamp);
+    }
+    if (data.userId) {
+      this.trackUserSession(data.userId, data.timestamp);
+    }
+    this.config.onMetric({
+      type: "request",
+      timestamp: data.timestamp,
+      data
+    });
+  }
+  /**
+   * Track response with full metrics
+   */
+  async trackResponseExtended(data) {
+    let estimatedCost = 0;
+    if (this.config.enableCost && data.model) {
+      estimatedCost = this.calculateCost(
+        data.model,
+        data.tokens.promptTokens,
+        data.tokens.completionTokens,
+        data.rag?.contextTokens
+      );
+    }
+    const response = {
+      id: `res-${++this.idCounter}`,
+      requestId: `req-${this.idCounter}`,
+      agentId: data.agentId,
+      threadId: data.threadId,
+      userId: data.userId,
+      timestamp: data.timestamp,
+      responseLength: data.responseLength,
+      timings: data.timings,
+      tokens: {
+        ...data.tokens,
+        estimatedCost
+      },
+      rag: data.rag,
+      success: data.success,
+      errorType: data.errorType,
+      model: data.model,
+      provider: data.provider
+    };
+    this.responses.push(response);
+    this.pendingResponses.push(response);
+    if (this.config.enableConversation && data.threadId) {
+      this.updateThreadStats(data.threadId, data.agentId, data.userId, data.timestamp);
+    }
+    if (!data.success && data.errorType) {
+      await this.trackError({
+        agentId: data.agentId,
+        threadId: data.threadId,
+        timestamp: data.timestamp,
+        errorType: data.errorType,
+        errorMessage: data.errorMessage || "Unknown error",
+        component: "llm"
+      });
+    }
+    this.config.onMetric({
+      type: "response",
+      timestamp: data.timestamp,
+      data
+    });
+  }
+  /**
+   * Track errors
+   */
+  async trackError(data) {
+    if (!this.config.enableErrors) return;
+    const error = {
+      id: `err-${++this.idCounter}`,
+      agentId: data.agentId,
+      threadId: data.threadId,
+      timestamp: data.timestamp,
+      errorType: data.errorType,
+      errorMessage: data.errorMessage,
+      component: data.component
+    };
+    this.errors.push(error);
+    this.pendingErrors.push(error);
+    this.config.onMetric({
+      type: "error",
+      timestamp: data.timestamp,
+      data
+    });
+  }
+  // ============================================================================
+  // Metrics Retrieval
+  // ============================================================================
+  /**
+   * Get aggregated metrics
+   */
+  async getMetrics(options) {
+    const startDate = options?.startDate || new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3);
+    const endDate = options?.endDate || /* @__PURE__ */ new Date();
+    const filteredResponses = this.filterResponses(options?.agentId, startDate, endDate);
+    const filteredRequests = this.filterRequests(options?.agentId, startDate, endDate);
+    const filteredErrors = this.filterErrors(options?.agentId, startDate, endDate);
+    return {
+      period: { start: startDate, end: endDate },
+      performance: this.calculatePerformanceMetrics(filteredResponses),
+      rag: this.calculateRAGMetrics(filteredResponses),
+      cost: this.calculateCostMetrics(filteredResponses),
+      conversation: this.calculateConversationMetrics(filteredRequests, options?.agentId),
+      errors: this.calculateErrorMetrics(filteredErrors, filteredResponses.length)
+    };
+  }
+  /**
+   * Get performance metrics
+   */
+  getPerformanceMetrics(options) {
+    const responses = this.filterResponses(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    return this.calculatePerformanceMetrics(responses);
+  }
+  /**
+   * Get RAG metrics
+   */
+  getRAGMetrics(options) {
+    const responses = this.filterResponses(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    return this.calculateRAGMetrics(responses);
+  }
+  /**
+   * Get cost metrics
+   */
+  getCostMetrics(options) {
+    const responses = this.filterResponses(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    return this.calculateCostMetrics(responses);
+  }
+  /**
+   * Get conversation metrics
+   */
+  getConversationMetrics(options) {
+    const requests = this.filterRequests(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    return this.calculateConversationMetrics(requests, options?.agentId);
+  }
+  /**
+   * Get error metrics
+   */
+  getErrorMetrics(options) {
+    const errors = this.filterErrors(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    const responses = this.filterResponses(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    return this.calculateErrorMetrics(errors, responses.length);
+  }
+  /**
+   * Get time series data
+   */
+  getTimeSeries(metric, options) {
+    const groupBy = options?.groupBy || "day";
+    const responses = this.filterResponses(
+      options?.agentId,
+      options?.startDate,
+      options?.endDate
+    );
+    const groups = /* @__PURE__ */ new Map();
+    for (const response of responses) {
+      const key = this.getTimeKey(response.timestamp, groupBy);
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key).push(response);
+    }
+    const series = [];
+    for (const [key, groupResponses] of groups.entries()) {
+      let value = 0;
+      switch (metric) {
+        case "latency":
+          value = this.avg(groupResponses.map((r) => r.timings.total));
+          break;
+        case "tokens":
+          value = groupResponses.reduce((sum, r) => sum + r.tokens.totalTokens, 0);
+          break;
+        case "cost":
+          value = groupResponses.reduce((sum, r) => sum + (r.tokens.estimatedCost || 0), 0);
+          break;
+        case "errors":
+          value = groupResponses.filter((r) => !r.success).length;
+          break;
+        case "requests":
+          value = groupResponses.length;
+          break;
+      }
+      series.push({
+        timestamp: new Date(key),
+        value,
+        metadata: { count: groupResponses.length }
+      });
+    }
+    return series.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+  }
+  // ============================================================================
+  // Private: Calculation Methods
+  // ============================================================================
+  calculatePerformanceMetrics(responses) {
+    if (responses.length === 0) {
+      return this.emptyPerformanceMetrics();
+    }
+    const latencies = responses.map((r) => r.timings.total);
+    const sorted = [...latencies].sort((a, b) => a - b);
+    const llmTimes = responses.map((r) => r.timings.llmApiTime).filter(Boolean);
+    const ragTimes = responses.map((r) => r.timings.ragRetrievalTime).filter(Boolean);
+    const pluginTimes = responses.map((r) => r.timings.pluginExecutionTime).filter(Boolean);
+    const dbTimes = responses.map((r) => r.timings.dbQueryTime).filter(Boolean);
+    const ttft = responses.map((r) => r.timings.timeToFirstToken).filter(Boolean);
+    const ttlt = responses.map((r) => r.timings.timeToLastToken).filter(Boolean);
+    return {
+      totalRequests: responses.length,
+      avgLatency: this.avg(latencies),
+      p50Latency: this.percentile(sorted, 50),
+      p95Latency: this.percentile(sorted, 95),
+      p99Latency: this.percentile(sorted, 99),
+      minLatency: Math.min(...latencies),
+      maxLatency: Math.max(...latencies),
+      avgLLMTime: this.avg(llmTimes),
+      avgRAGTime: this.avg(ragTimes),
+      avgPluginTime: this.avg(pluginTimes),
+      avgDbTime: this.avg(dbTimes),
+      avgTimeToFirstToken: this.avg(ttft),
+      avgTimeToLastToken: this.avg(ttlt),
+      latencyDistribution: {
+        under100ms: latencies.filter((l) => l < 100).length,
+        under500ms: latencies.filter((l) => l >= 100 && l < 500).length,
+        under1s: latencies.filter((l) => l >= 500 && l < 1e3).length,
+        under5s: latencies.filter((l) => l >= 1e3 && l < 5e3).length,
+        over5s: latencies.filter((l) => l >= 5e3).length
+      }
+    };
+  }
+  calculateRAGMetrics(responses) {
+    const ragResponses = responses.filter((r) => r.rag?.enabled);
+    if (ragResponses.length === 0) {
+      return this.emptyRAGMetrics();
+    }
+    const docsRetrieved = ragResponses.map((r) => r.rag.documentsRetrieved || 0);
+    const vectorTimes = ragResponses.map((r) => r.rag.vectorSearchTime).filter(Boolean);
+    const embedTimes = ragResponses.map((r) => r.rag.embeddingTime).filter(Boolean);
+    const similarities = ragResponses.map((r) => r.rag.avgSimilarityScore).filter(Boolean);
+    const rerankTimes = ragResponses.map((r) => r.rag.rerankTime).filter(Boolean);
+    const contextLengths = ragResponses.map((r) => r.rag.contextLength).filter(Boolean);
+    const contextTokens = ragResponses.map((r) => r.rag.contextTokens).filter(Boolean);
+    const sourcesCounts = ragResponses.map((r) => r.rag.sourcesCount).filter(Boolean);
+    const cacheHits = ragResponses.filter((r) => r.rag.cacheHit === true).length;
+    const cacheMisses = ragResponses.filter((r) => r.rag.cacheHit === false).length;
+    const successfulRetrievals = ragResponses.filter((r) => (r.rag.documentsRetrieved || 0) > 0).length;
+    return {
+      totalQueries: ragResponses.length,
+      avgDocumentsRetrieved: this.avg(docsRetrieved),
+      avgVectorSearchTime: this.avg(vectorTimes),
+      avgEmbeddingTime: this.avg(embedTimes),
+      cacheHitRate: cacheHits / (cacheHits + cacheMisses) || 0,
+      cacheMissRate: cacheMisses / (cacheHits + cacheMisses) || 0,
+      avgSimilarityScore: this.avg(similarities),
+      avgRerankTime: this.avg(rerankTimes),
+      avgContextLength: this.avg(contextLengths),
+      avgContextTokens: this.avg(contextTokens),
+      avgSourcesCount: this.avg(sourcesCounts),
+      retrievalSuccessRate: successfulRetrievals / ragResponses.length
+    };
+  }
+  calculateCostMetrics(responses) {
+    if (responses.length === 0) {
+      return this.emptyCostMetrics();
+    }
+    const totalCost = responses.reduce((sum, r) => sum + (r.tokens.estimatedCost || 0), 0);
+    const totalTokens = responses.reduce((sum, r) => sum + r.tokens.totalTokens, 0);
+    const totalPromptTokens = responses.reduce((sum, r) => sum + r.tokens.promptTokens, 0);
+    const totalCompletionTokens = responses.reduce((sum, r) => sum + r.tokens.completionTokens, 0);
+    const totalEmbeddingTokens = responses.reduce((sum, r) => sum + (r.rag?.contextTokens || 0), 0);
+    const totalEmbeddingCost = totalEmbeddingTokens * this.config.embeddingCost / 1e3;
+    const costByModel = {};
+    const tokensByModel = {};
+    for (const r of responses) {
+      const model = r.model || "unknown";
+      costByModel[model] = (costByModel[model] || 0) + (r.tokens.estimatedCost || 0);
+      tokensByModel[model] = (tokensByModel[model] || 0) + r.tokens.totalTokens;
+    }
+    const costByAgent = {};
+    for (const r of responses) {
+      costByAgent[r.agentId] = (costByAgent[r.agentId] || 0) + (r.tokens.estimatedCost || 0);
+    }
+    const dailyCosts = {};
+    for (const r of responses) {
+      const day = r.timestamp.toISOString().split("T")[0];
+      dailyCosts[day] = (dailyCosts[day] || 0) + (r.tokens.estimatedCost || 0);
+    }
+    return {
+      totalCost,
+      totalTokens,
+      totalPromptTokens,
+      totalCompletionTokens,
+      avgTokensPerRequest: totalTokens / responses.length,
+      avgCostPerRequest: totalCost / responses.length,
+      tokenEfficiency: totalCompletionTokens / (totalPromptTokens || 1),
+      costByModel,
+      costByAgent,
+      tokensByModel,
+      totalEmbeddingTokens,
+      totalEmbeddingCost,
+      dailyCosts
+    };
+  }
+  calculateConversationMetrics(requests, agentId) {
+    const relevantThreads = agentId ? Array.from(this.threadStats.values()).filter((t) => t.agentId === agentId) : Array.from(this.threadStats.values());
+    if (relevantThreads.length === 0) {
+      return this.emptyConversationMetrics();
+    }
+    const messageCounts = relevantThreads.map((t) => t.messageCount);
+    const durations = relevantThreads.map(
+      (t) => t.lastMessage.getTime() - t.firstMessage.getTime()
+    );
+    const abandonedThreads = relevantThreads.filter((t) => t.messageCount === 1);
+    const inputLengths = requests.map((r) => r.messageLength);
+    const shortInputs = inputLengths.filter((l) => l < 50).length;
+    const mediumInputs = inputLengths.filter((l) => l >= 50 && l < 200).length;
+    const longInputs = inputLengths.filter((l) => l >= 200 && l < 500).length;
+    const veryLongInputs = inputLengths.filter((l) => l >= 500).length;
+    let returnRate = 0;
+    if (this.userSessions.size > 0) {
+      const returningUsers = Array.from(this.userSessions.values()).filter(
+        (sessions) => sessions.length > 1
+      ).length;
+      returnRate = returningUsers / this.userSessions.size;
+    }
+    return {
+      totalThreads: relevantThreads.length,
+      totalMessages: messageCounts.reduce((a, b) => a + b, 0),
+      avgMessagesPerThread: this.avg(messageCounts),
+      avgThreadDuration: this.avg(durations),
+      avgSessionLength: this.avg(durations),
+      // Same as thread duration for now
+      userReturnRate: returnRate,
+      threadAbandonmentRate: abandonedThreads.length / relevantThreads.length,
+      avgInputLength: this.avg(inputLengths),
+      avgOutputLength: 0,
+      // Would need to track from responses
+      inputLengthDistribution: {
+        short: shortInputs,
+        medium: mediumInputs,
+        long: longInputs,
+        veryLong: veryLongInputs
+      }
+    };
+  }
+  calculateErrorMetrics(errors, totalRequests) {
+    const errorsByType = {};
+    for (const e of errors) {
+      errorsByType[e.errorType] = (errorsByType[e.errorType] || 0) + 1;
+    }
+    const llmErrors = errors.filter((e) => e.component === "llm").length;
+    const ragErrors = errors.filter((e) => e.component === "rag").length;
+    const pluginErrors = errors.filter((e) => e.component === "plugin").length;
+    const dbErrors = errors.filter((e) => e.component === "database").length;
+    const networkErrors = errors.filter((e) => e.component === "network").length;
+    const timeoutErrors = errors.filter((e) => e.errorType === "timeout").length;
+    const rateLimitHits = errors.filter((e) => e.errorType === "rate_limit").length;
+    const recentErrors = errors.slice(-10).reverse().map((e) => ({
+      timestamp: e.timestamp,
+      type: e.errorType,
+      message: e.errorMessage,
+      agentId: e.agentId
+    }));
+    return {
+      totalErrors: errors.length,
+      errorRate: totalRequests > 0 ? errors.length / totalRequests : 0,
+      errorsByType,
+      llmErrors,
+      ragErrors,
+      pluginErrors,
+      dbErrors,
+      networkErrors,
+      timeoutErrors,
+      rateLimitHits,
+      successRate: totalRequests > 0 ? (totalRequests - errors.length) / totalRequests : 1,
+      retryCount: 0,
+      // Would need to track this separately
+      fallbackUsage: 0,
+      // Would need to track this separately
+      recentErrors
+    };
+  }
+  // ============================================================================
+  // Private: Helper Methods
+  // ============================================================================
+  calculateCost(model, promptTokens, completionTokens, embeddingTokens) {
+    const modelCost = this.config.modelCosts[model];
+    if (!modelCost) return 0;
+    const inputCost = promptTokens / 1e3 * modelCost.input;
+    const outputCost = completionTokens / 1e3 * modelCost.output;
+    const embedCost = embeddingTokens ? embeddingTokens / 1e3 * this.config.embeddingCost : 0;
+    return inputCost + outputCost + embedCost;
+  }
+  updateThreadStats(threadId, agentId, userId, timestamp) {
+    const existing = this.threadStats.get(threadId);
+    if (existing) {
+      existing.messageCount++;
+      existing.lastMessage = timestamp;
+    } else {
+      this.threadStats.set(threadId, {
+        threadId,
+        agentId,
+        userId,
+        messageCount: 1,
+        firstMessage: timestamp,
+        lastMessage: timestamp
+      });
+    }
+  }
+  trackUserSession(userId, timestamp) {
+    const sessions = this.userSessions.get(userId) || [];
+    sessions.push(timestamp);
+    this.userSessions.set(userId, sessions);
+  }
+  filterResponses(agentId, startDate, endDate) {
+    return this.responses.filter((r) => {
+      if (agentId && r.agentId !== agentId) return false;
+      if (startDate && r.timestamp < startDate) return false;
+      if (endDate && r.timestamp > endDate) return false;
+      return true;
+    });
+  }
+  filterRequests(agentId, startDate, endDate) {
+    return this.requests.filter((r) => {
+      if (agentId && r.agentId !== agentId) return false;
+      if (startDate && r.timestamp < startDate) return false;
+      if (endDate && r.timestamp > endDate) return false;
+      return true;
+    });
+  }
+  filterErrors(agentId, startDate, endDate) {
+    return this.errors.filter((e) => {
+      if (agentId && e.agentId !== agentId) return false;
+      if (startDate && e.timestamp < startDate) return false;
+      if (endDate && e.timestamp > endDate) return false;
+      return true;
+    });
+  }
+  getTimeKey(date, groupBy) {
+    const d = new Date(date);
+    switch (groupBy) {
+      case "hour":
+        d.setMinutes(0, 0, 0);
+        return d.toISOString();
+      case "day":
+        d.setHours(0, 0, 0, 0);
+        return d.toISOString();
+      case "week":
+        const day = d.getDay();
+        d.setDate(d.getDate() - day);
+        d.setHours(0, 0, 0, 0);
+        return d.toISOString();
+      default:
+        return d.toISOString();
+    }
+  }
+  avg(numbers) {
+    if (numbers.length === 0) return 0;
+    return numbers.reduce((a, b) => a + b, 0) / numbers.length;
+  }
+  percentile(sorted, p) {
+    if (sorted.length === 0) return 0;
+    const index = Math.ceil(p / 100 * sorted.length) - 1;
+    return sorted[Math.max(0, index)];
+  }
+  async cleanup() {
+    if (this.config.retentionDays <= 0) return;
+    const cutoff = new Date(Date.now() - this.config.retentionDays * 24 * 60 * 60 * 1e3);
+    this.requests = this.requests.filter((r) => r.timestamp > cutoff);
+    this.responses = this.responses.filter((r) => r.timestamp > cutoff);
+    this.errors = this.errors.filter((e) => e.timestamp > cutoff);
+    for (const [threadId, stats] of this.threadStats.entries()) {
+      if (stats.lastMessage < cutoff) {
+        this.threadStats.delete(threadId);
+      }
+    }
+    if (this.config.storage) {
+      await this.storage.deleteOlderThan(cutoff);
+    }
+  }
+  // Empty metrics for when there's no data
+  emptyPerformanceMetrics() {
+    return {
+      totalRequests: 0,
+      avgLatency: 0,
+      p50Latency: 0,
+      p95Latency: 0,
+      p99Latency: 0,
+      minLatency: 0,
+      maxLatency: 0,
+      avgLLMTime: 0,
+      avgRAGTime: 0,
+      avgPluginTime: 0,
+      avgDbTime: 0,
+      avgTimeToFirstToken: 0,
+      avgTimeToLastToken: 0,
+      latencyDistribution: { under100ms: 0, under500ms: 0, under1s: 0, under5s: 0, over5s: 0 }
+    };
+  }
+  emptyRAGMetrics() {
+    return {
+      totalQueries: 0,
+      avgDocumentsRetrieved: 0,
+      avgVectorSearchTime: 0,
+      avgEmbeddingTime: 0,
+      cacheHitRate: 0,
+      cacheMissRate: 0,
+      avgSimilarityScore: 0,
+      avgRerankTime: 0,
+      avgContextLength: 0,
+      avgContextTokens: 0,
+      avgSourcesCount: 0,
+      retrievalSuccessRate: 0
+    };
+  }
+  emptyCostMetrics() {
+    return {
+      totalCost: 0,
+      totalTokens: 0,
+      totalPromptTokens: 0,
+      totalCompletionTokens: 0,
+      avgTokensPerRequest: 0,
+      avgCostPerRequest: 0,
+      tokenEfficiency: 0,
+      costByModel: {},
+      costByAgent: {},
+      tokensByModel: {},
+      totalEmbeddingTokens: 0,
+      totalEmbeddingCost: 0,
+      dailyCosts: {}
+    };
+  }
+  emptyConversationMetrics() {
+    return {
+      totalThreads: 0,
+      totalMessages: 0,
+      avgMessagesPerThread: 0,
+      avgThreadDuration: 0,
+      avgSessionLength: 0,
+      userReturnRate: 0,
+      threadAbandonmentRate: 0,
+      avgInputLength: 0,
+      avgOutputLength: 0,
+      inputLengthDistribution: { short: 0, medium: 0, long: 0, veryLong: 0 }
+    };
+  }
+  // ============================================================================
+  // Public: Utility Methods
+  // ============================================================================
+  /**
+   * Get raw data for export
+   */
+  exportData() {
+    return {
+      requests: [...this.requests],
+      responses: [...this.responses],
+      errors: [...this.errors]
+    };
+  }
+  /**
+   * Clear all analytics data
+   */
+  clear() {
+    this.requests = [];
+    this.responses = [];
+    this.errors = [];
+    this.pendingRequests = [];
+    this.pendingResponses = [];
+    this.pendingErrors = [];
+    this.threadStats.clear();
+    this.userSessions.clear();
+  }
+  /**
+   * Get summary statistics
+   */
+  getSummary() {
+    return {
+      totalRequests: this.requests.length,
+      totalResponses: this.responses.length,
+      totalErrors: this.errors.length,
+      totalThreads: this.threadStats.size,
+      totalUsers: this.userSessions.size,
+      dataRange: {
+        oldest: this.requests[0]?.timestamp,
+        newest: this.requests[this.requests.length - 1]?.timestamp
+      }
+    };
+  }
+  // ============================================================================
+  // Flush Mechanism
+  // ============================================================================
+  /**
+   * Start the flush timer
+   */
+  startFlushTimer() {
+    if (this.flushTimer) {
+      return;
+    }
+    this.flushTimer = setInterval(() => {
+      this.flush().catch((err) => {
+        console.error("[SnapAgentAnalytics] Flush error:", err);
+      });
+    }, this.config.flushInterval);
+  }
+  /**
+   * Stop the flush timer
+   */
+  stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+  }
+  /**
+   * Flush pending data to external storage via onFlush callback
+   * @returns Promise that resolves when flush is complete
+   */
+  async flush() {
+    if (this.isFlushing) {
+      return;
+    }
+    if (this.pendingRequests.length === 0 && this.pendingResponses.length === 0 && this.pendingErrors.length === 0) {
+      return;
+    }
+    this.isFlushing = true;
+    try {
+      const flushData = {
+        requests: [...this.pendingRequests],
+        responses: [...this.pendingResponses],
+        errors: [...this.pendingErrors],
+        timestamp: /* @__PURE__ */ new Date()
+      };
+      this.pendingRequests = [];
+      this.pendingResponses = [];
+      this.pendingErrors = [];
+      if (this.config.storage) {
+        await Promise.all([
+          this.storage.saveRequests(flushData.requests),
+          this.storage.saveResponses(flushData.responses),
+          this.storage.saveErrors(flushData.errors)
+        ]);
+      }
+    } finally {
+      this.isFlushing = false;
+    }
+  }
+  /**
+   * Stop the analytics plugin and flush remaining data
+   * Call this before shutting down to ensure all data is persisted
+   */
+  async stop() {
+    this.stopFlushTimer();
+    await this.flush();
+    await this.storage.close();
+  }
+  /**
+   * Get count of pending (unflushed) items
+   */
+  getPendingCount() {
+    return {
+      requests: this.pendingRequests.length,
+      responses: this.pendingResponses.length,
+      errors: this.pendingErrors.length
+    };
+  }
+};
+export {
+  MemoryAnalyticsStorage,
+  MongoAnalyticsStorage,
+  SnapAgentAnalytics
+};