@kb-labs/rest-api-app 1.3.0

package/src/routes/adapters.ts

@@ -0,0 +1,1206 @@
+/**
+ * @module @kb-labs/rest-api-app/routes/adapters
+ * Platform adapter analytics endpoints
+ */
+
+import type { FastifyInstance } from 'fastify';
+import type { RestApiConfig } from '@kb-labs/rest-api-core';
+import { normalizeBasePath, resolvePaths } from '../utils/path-helpers';
+import { platform } from '@kb-labs/core-runtime';
+
+/**
+ * LLM usage statistics response
+ */
+interface LLMUsageStats {
+  totalRequests: number;
+  totalTokens: number;
+  totalCost: number;
+  costPer1KTokens: number; // Enhanced: Cost efficiency metric
+  // Cache savings
+  totalCacheReadTokens: number;
+  totalBillableTokens: number;
+  totalCacheSavingsUsd: number;
+  byModel: Record<
+    string,
+    {
+      requests: number;
+      promptTokens: number;
+      completionTokens: number;
+      totalTokens: number;
+      cost: number;
+      costPer1KTokens: number; // Enhanced: Cost per 1K tokens for this model
+      tokensPerRequest: number; // Enhanced: Average tokens per request
+      errorRate: number; // Enhanced: Error rate percentage (0-100)
+      avgDurationMs: number;
+      // Enhanced: Latency percentiles
+      p50DurationMs: number;
+      p95DurationMs: number;
+      p99DurationMs: number;
+      // Cache savings per model
+      cacheReadTokens: number;
+      billableTokens: number;
+      cacheSavingsUsd: number;
+    }
+  >;
+  errors: number;
+  // Enhanced: Error breakdown by type
+  errorBreakdown: {
+    timeout: number;
+    rateLimit: number;
+    invalidRequest: number;
+    serverError: number;
+    other: number;
+  };
+  timeRange: {
+    from: string;
+    to: string;
+  };
+}
+
+/**
+ * Helper to get event data, supporting both kb.v1 (payload) and legacy (properties) formats
+ */
+function getEventData(event: any): Record<string, unknown> {
+  // kb.v1 format uses 'payload'
+  if (event.schema === 'kb.v1' && event.payload) {
+    return event.payload as Record<string, unknown>;
+  }
+  // Legacy format uses 'properties'
+  return (event.properties as Record<string, unknown>) || {};
+}
+
+/**
+ * Extract date range from query parameters
+ */
+function extractDateRange(query: any): { from?: string; to?: string } {
+  // Handle null/undefined query
+  if (!query) {
+    return { from: undefined, to: undefined };
+  }
+
+  const from = query.from as string | undefined;
+  const to = query.to as string | undefined;
+
+  // Validate ISO 8601 format
+  if (from && !isValidISODate(from)) {
+    throw new Error('Invalid "from" date format. Expected ISO 8601 datetime (e.g., 2026-01-01T00:00:00Z)');
+  }
+  if (to && !isValidISODate(to)) {
+    throw new Error('Invalid "to" date format. Expected ISO 8601 datetime (e.g., 2026-01-31T23:59:59Z)');
+  }
+
+  return { from, to };
+}
+
+/**
+ * Extract model filter from query parameters
+ * Supports both single model (?models=gpt-4) and multiple (?models=gpt-4,claude-sonnet)
+ */
+function extractModelFilter(query: any): string[] | undefined {
+  if (!query || !query.models) {
+    return undefined;
+  }
+
+  const modelsParam = query.models as string;
+
+  // Split by comma and trim whitespace
+  const models = modelsParam
+    .split(',')
+    .map((m) => m.trim())
+    .filter((m) => m.length > 0);
+
+  return models.length > 0 ? models : undefined;
+}
+
+/**
+ * Extract StatsQuery fields (groupBy, breakdownBy, metrics) from query parameters.
+ * These are optional — adapters silently ignore fields they don't support.
+ */
+function extractStatsOptions(query: any): {
+  groupBy?: 'hour' | 'day' | 'week' | 'month';
+  breakdownBy?: string;
+  metrics?: string[];
+} {
+  if (!query) {return {};}
+
+  const groupBy = query.groupBy as string | undefined;
+  const validGroupBy = ['hour', 'day', 'week', 'month'];
+  const resolvedGroupBy =
+    groupBy && validGroupBy.includes(groupBy)
+      ? (groupBy as 'hour' | 'day' | 'week' | 'month')
+      : undefined;
+
+  const breakdownBy = query.breakdownBy as string | undefined;
+
+  const metricsParam = query.metrics as string | undefined;
+  const metrics = metricsParam
+    ? metricsParam
+        .split(',')
+        .map((m) => m.trim())
+        .filter((m) => m.length > 0)
+    : undefined;
+
+  return {
+    groupBy: resolvedGroupBy,
+    breakdownBy: breakdownBy || undefined,
+    metrics: metrics && metrics.length > 0 ? metrics : undefined,
+  };
+}
+
+/**
+ * Fetch all events for a given query in batches to avoid memory issues.
+ *
+ * Backend handles pagination internally:
+ * - PAGE_SIZE: 10,000 events per request
+ * - MAX_EVENTS: 100,000 total events to process
+ *
+ * Frontend just sends date range, backend fetches all events in that range.
+ *
+ * @param analytics - Analytics adapter
+ * @param query - Event query (type, from, to)
+ * @param fastify - Fastify instance for logging
+ * @returns All events (up to MAX_EVENTS)
+ */
+async function fetchAllEventsBatched(
+  analytics: any,
+  query: { type: string | string[]; from?: string; to?: string },
+  fastify: FastifyInstance
+): Promise<any[]> {
+  const PAGE_SIZE = 10000;
+  const MAX_EVENTS = 100000;
+
+  const allEvents: any[] = [];
+  let offset = 0;
+  let hasMore = true;
+
+  while (hasMore && allEvents.length < MAX_EVENTS) {
+    const response = await analytics.getEvents({
+      ...query,
+      limit: PAGE_SIZE,
+      offset,
+    });
+
+    allEvents.push(...response.events);
+    hasMore = response.hasMore;
+    offset += PAGE_SIZE;
+
+    // Stop if we've fetched all events or page not full
+    if (!hasMore || response.events.length < PAGE_SIZE) {
+      break;
+    }
+  }
+
+  // Warn if we hit the safety limit
+  if (allEvents.length >= MAX_EVENTS) {
+    fastify.log.warn({ query }, `Hit max events limit (${MAX_EVENTS}) for query. Some events excluded from stats.`);
+  }
+
+  return allEvents;
+}
+
+/**
+ * Basic ISO 8601 validation
+ */
+function isValidISODate(dateString: string): boolean {
+  // Check if it's a string
+  if (typeof dateString !== 'string' || dateString.length === 0) {
+    return false;
+  }
+
+  const date = new Date(dateString);
+  return !isNaN(date.getTime());
+}
+
+/**
+ * Register platform adapter analytics routes
+ */
+export async function registerAdaptersRoutes(
+  fastify: FastifyInstance,
+  config: RestApiConfig
+): Promise<void> {
+  const basePath = normalizeBasePath(config.basePath);
+
+  // GET /api/v1/adapters/llm/usage
+  // Returns aggregated LLM usage statistics
+  const llmUsagePaths = resolvePaths(basePath, '/adapters/llm/usage');
+  for (const path of llmUsagePaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      // Check if analytics supports reading
+      if (!analytics.getEvents) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support reading events',
+          },
+        });
+      }
+
+      try {
+        // Extract and validate date range
+        const dateRange = extractDateRange(request.query);
+
+        // Fetch ALL LLM completion events in batches (backend handles pagination)
+        const completedEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: ['llm.completion.completed', 'llm.chatWithTools.completed'],
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        // Fetch ALL error events in batches
+        const errorEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: ['llm.completion.error', 'llm.chatWithTools.error'],
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        // Aggregate statistics
+        const stats: LLMUsageStats = {
+          totalRequests: 0,
+          totalTokens: 0,
+          totalCost: 0,
+          costPer1KTokens: 0,
+          totalCacheReadTokens: 0,
+          totalBillableTokens: 0,
+          totalCacheSavingsUsd: 0,
+          byModel: {},
+          errors: errorEvents.length,
+          errorBreakdown: {
+            timeout: 0,
+            rateLimit: 0,
+            invalidRequest: 0,
+            serverError: 0,
+            other: 0,
+          },
+          timeRange: {
+            from: '',
+            to: '',
+          },
+        };
+
+        // Collect durations per model for percentile calculation
+        const durationsByModel: Record<string, number[]> = {};
+
+        // Track errors per model
+        const errorsByModel: Record<string, number> = {};
+
+        // Process completed events
+        for (const event of completedEvents) {
+          const props = getEventData(event);
+
+          const model = (props.model || 'unknown') as string;
+          const promptTokens = Number(props.promptTokens || 0);
+          const completionTokens = Number(props.completionTokens || 0);
+          const totalTokens = Number(props.totalTokens || promptTokens + completionTokens);
+          const estimatedCost = Number(props.estimatedCost || 0);
+          const durationMs = Number(props.durationMs || 0);
+          const cacheReadTokens = Number(props.cacheReadTokens || 0);
+          const billableTokens = Number(props.billableTotalTokens || totalTokens);
+          const cacheSavingsUsd = Number(props.estimatedCacheSavingsUsd || 0);
+
+          stats.totalRequests++;
+          stats.totalTokens += totalTokens;
+          stats.totalCost += estimatedCost;
+          stats.totalCacheReadTokens += cacheReadTokens;
+          stats.totalBillableTokens += billableTokens;
+          stats.totalCacheSavingsUsd += cacheSavingsUsd;
+
+          if (!stats.byModel[model]) {
+            stats.byModel[model] = {
+              requests: 0,
+              promptTokens: 0,
+              completionTokens: 0,
+              totalTokens: 0,
+              cost: 0,
+              costPer1KTokens: 0,
+              tokensPerRequest: 0,
+              errorRate: 0,
+              avgDurationMs: 0,
+              p50DurationMs: 0,
+              p95DurationMs: 0,
+              p99DurationMs: 0,
+              cacheReadTokens: 0,
+              billableTokens: 0,
+              cacheSavingsUsd: 0,
+            };
+            durationsByModel[model] = [];
+          }
+
+          const modelStats = stats.byModel[model]!;
+          modelStats.requests++;
+          modelStats.promptTokens += promptTokens;
+          modelStats.completionTokens += completionTokens;
+          modelStats.totalTokens += totalTokens;
+          modelStats.cost += estimatedCost;
+          modelStats.cacheReadTokens += cacheReadTokens;
+          modelStats.billableTokens += billableTokens;
+          modelStats.cacheSavingsUsd += cacheSavingsUsd;
+          modelStats.avgDurationMs =
+            (modelStats.avgDurationMs * (modelStats.requests - 1) + durationMs) / modelStats.requests;
+
+          // Collect duration for percentile calculation
+          durationsByModel[model]!.push(durationMs);
+        }
+
+        // Process error events for breakdown
+        for (const event of errorEvents) {
+          const props = getEventData(event);
+          const errorType = String(props.errorType || props.errorCode || '').toLowerCase();
+          const errorMessage = String(props.error || props.message || '').toLowerCase();
+          const model = (props.model || 'unknown') as string;
+
+          // Track errors per model
+          errorsByModel[model] = (errorsByModel[model] || 0) + 1;
+
+          // Categorize error by type
+          if (errorType.includes('timeout') || errorMessage.includes('timeout') || errorMessage.includes('timed out')) {
+            stats.errorBreakdown.timeout++;
+          } else if (errorType.includes('rate') || errorType.includes('quota') || errorMessage.includes('rate limit') || errorMessage.includes('quota exceeded')) {
+            stats.errorBreakdown.rateLimit++;
+          } else if (errorType.includes('invalid') || errorType.includes('validation') || errorMessage.includes('invalid request') || errorMessage.includes('bad request')) {
+            stats.errorBreakdown.invalidRequest++;
+          } else if (errorType.includes('server') || errorType.includes('5xx') || errorMessage.includes('internal error') || errorMessage.includes('server error')) {
+            stats.errorBreakdown.serverError++;
+          } else {
+            stats.errorBreakdown.other++;
+          }
+        }
+
+        // Calculate percentiles and cost per 1K tokens for each model
+        for (const [model, durations] of Object.entries(durationsByModel)) {
+          const modelStats = stats.byModel[model]!;
+
+          // Calculate percentiles
+          if (durations.length > 0) {
+            const sorted = durations.slice().sort((a, b) => a - b);
+            const p50Index = Math.floor(sorted.length * 0.5);
+            const p95Index = Math.floor(sorted.length * 0.95);
+            const p99Index = Math.floor(sorted.length * 0.99);
+
+            modelStats.p50DurationMs = sorted[p50Index] ?? 0;
+            modelStats.p95DurationMs = sorted[p95Index] ?? 0;
+            modelStats.p99DurationMs = sorted[p99Index] ?? 0;
+          }
+
+          // Calculate cost per 1K tokens
+          if (modelStats.totalTokens > 0) {
+            modelStats.costPer1KTokens = (modelStats.cost / modelStats.totalTokens) * 1000;
+          }
+
+          // Calculate tokens per request
+          if (modelStats.requests > 0) {
+            modelStats.tokensPerRequest = modelStats.totalTokens / modelStats.requests;
+          }
+
+          // Calculate error rate percentage
+          const modelErrors = errorsByModel[model] || 0;
+          const totalModelRequests = modelStats.requests + modelErrors;
+          if (totalModelRequests > 0) {
+            modelStats.errorRate = (modelErrors / totalModelRequests) * 100;
+          }
+        }
+
+        // Calculate overall cost per 1K tokens
+        if (stats.totalTokens > 0) {
+          stats.costPer1KTokens = (stats.totalCost / stats.totalTokens) * 1000;
+        }
+
+        // Calculate time range
+        const allTimestamps = completedEvents.map((e) => e.ts);
+        if (allTimestamps.length > 0) {
+          stats.timeRange.from = allTimestamps[allTimestamps.length - 1]!; // oldest
+          stats.timeRange.to = allTimestamps[0]!; // newest
+        }
+
+        return {
+          ok: true,
+          data: stats,
+          meta: {
+            source: 'analytics-adapter',
+            totalEvents: completedEvents.length,
+          },
+        };
+      } catch (error) {
+        // Handle validation errors
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: {
+              code: 'INVALID_DATE_RANGE',
+              message: error.message,
+            },
+          });
+        }
+
+        platform.logger.error('Failed to fetch LLM usage stats', error instanceof Error ? error : new Error(String(error)));
+
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'LLM_USAGE_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch LLM usage statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/llm/daily-stats
+  // Returns time-bucketed aggregated LLM statistics for time-series visualization
+  // Query params: from, to, groupBy (hour|day|week|month), breakdownBy (dot-path), metrics (csv), models (csv, legacy filter)
+  const llmDailyStatsPaths = resolvePaths(basePath, '/adapters/llm/daily-stats');
+  for (const path of llmDailyStatsPaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getDailyStats) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support daily statistics',
+          },
+        });
+      }
+
+      try {
+        const dateRange = extractDateRange(request.query);
+        const statsOptions = extractStatsOptions(request.query);
+        const modelFilter = extractModelFilter(request.query);
+
+        const dailyStats = await analytics.getDailyStats({
+          type: ['llm.completion.completed', 'llm.chatWithTools.completed'],
+          from: dateRange.from,
+          to: dateRange.to,
+          limit: 50000,
+          // Legacy ?models= filter maps to source filter via getEvents inside the adapter.
+          // When breakdownBy is provided explicitly it takes precedence.
+          // Models filter is handled post-aggregation below for backward compat.
+          ...statsOptions,
+        });
+
+        // Legacy model filter: post-filter rows by breakdown value when models param is used
+        // without an explicit breakdownBy (backward compatibility with existing Studio pages)
+        const result =
+          modelFilter && modelFilter.length > 0 && !statsOptions.breakdownBy
+            ? dailyStats.filter((s) => !s.breakdown || modelFilter.includes(s.breakdown))
+            : dailyStats;
+
+        return reply.send({ ok: true, data: result });
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: { code: 'INVALID_DATE_RANGE', message: error.message },
+          });
+        }
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch daily statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/embeddings/daily-stats
+  // Returns time-bucketed aggregated Embeddings statistics for time-series visualization
+  // Query params: from, to, groupBy (hour|day|week|month), breakdownBy (dot-path), metrics (csv)
+  const embeddingsDailyStatsPaths = resolvePaths(basePath, '/adapters/embeddings/daily-stats');
+  for (const path of embeddingsDailyStatsPaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getDailyStats) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support daily statistics',
+          },
+        });
+      }
+
+      try {
+        const dateRange = extractDateRange(request.query);
+        const statsOptions = extractStatsOptions(request.query);
+
+        const dailyStats = await analytics.getDailyStats({
+          type: ['embeddings.embed.completed', 'embeddings.embedBatch.completed'],
+          from: dateRange.from,
+          to: dateRange.to,
+          limit: 50000,
+          ...statsOptions,
+        });
+
+        return reply.send({ ok: true, data: dailyStats });
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: { code: 'INVALID_DATE_RANGE', message: error.message },
+          });
+        }
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch daily statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/embeddings/usage
+  // Returns aggregated Embeddings usage statistics
+  const embeddingsUsagePaths = resolvePaths(basePath, '/adapters/embeddings/usage');
+  for (const path of embeddingsUsagePaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getEvents) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support reading events',
+          },
+        });
+      }
+
+      try {
+        // Extract and validate date range
+        const dateRange = extractDateRange(request.query);
+
+        const completedEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: ['embeddings.embed.completed', 'embeddings.embedBatch.completed'],
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const errorEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: ['embeddings.embed.error', 'embeddings.embedBatch.error'],
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const stats = {
+          totalRequests: completedEvents.length,
+          totalTextLength: 0,
+          totalCost: 0,
+          costPer1KChars: 0, // Enhanced: Cost efficiency metric
+          errors: errorEvents.length,
+          // Enhanced: Error breakdown by type
+          errorBreakdown: {
+            timeout: 0,
+            rateLimit: 0,
+            invalidRequest: 0,
+            serverError: 0,
+            other: 0,
+          },
+          avgDurationMs: 0,
+          // Enhanced: Latency percentiles
+          p50DurationMs: 0,
+          p95DurationMs: 0,
+          p99DurationMs: 0,
+          batchRequests: 0,
+          singleRequests: 0,
+          avgBatchSize: 0,
+        };
+
+        let totalDuration = 0;
+        let totalBatchSize = 0;
+        const durations: number[] = [];
+
+        for (const event of completedEvents) {
+          const props = getEventData(event);
+
+          const textLength = Number(props.textLength || props.totalTextLength || 0);
+          const cost = Number(props.estimatedCost || 0);
+          const duration = Number(props.durationMs || 0);
+          const batchSize = Number(props.batchSize || 1);
+
+          stats.totalTextLength += textLength;
+          stats.totalCost += cost;
+          totalDuration += duration;
+          durations.push(duration);
+
+          if (batchSize > 1) {
+            stats.batchRequests++;
+            totalBatchSize += batchSize;
+          } else {
+            stats.singleRequests++;
+          }
+        }
+
+        stats.avgDurationMs = stats.totalRequests > 0 ? totalDuration / stats.totalRequests : 0;
+        stats.avgBatchSize = stats.batchRequests > 0 ? totalBatchSize / stats.batchRequests : 0;
+
+        // Calculate percentiles
+        if (durations.length > 0) {
+          const sorted = durations.slice().sort((a, b) => a - b);
+          const p50Index = Math.floor(sorted.length * 0.5);
+          const p95Index = Math.floor(sorted.length * 0.95);
+          const p99Index = Math.floor(sorted.length * 0.99);
+
+          stats.p50DurationMs = sorted[p50Index] ?? 0;
+          stats.p95DurationMs = sorted[p95Index] ?? 0;
+          stats.p99DurationMs = sorted[p99Index] ?? 0;
+        }
+
+        // Calculate cost per 1K characters
+        if (stats.totalTextLength > 0) {
+          stats.costPer1KChars = (stats.totalCost / stats.totalTextLength) * 1000;
+        }
+
+        // Process error events for breakdown
+        for (const event of errorEvents) {
+          const props = getEventData(event);
+          const errorType = String(props.errorType || props.errorCode || '').toLowerCase();
+          const errorMessage = String(props.error || props.message || '').toLowerCase();
+
+          // Categorize error by type
+          if (errorType.includes('timeout') || errorMessage.includes('timeout') || errorMessage.includes('timed out')) {
+            stats.errorBreakdown.timeout++;
+          } else if (errorType.includes('rate') || errorType.includes('quota') || errorMessage.includes('rate limit') || errorMessage.includes('quota exceeded')) {
+            stats.errorBreakdown.rateLimit++;
+          } else if (errorType.includes('invalid') || errorType.includes('validation') || errorMessage.includes('invalid request') || errorMessage.includes('bad request')) {
+            stats.errorBreakdown.invalidRequest++;
+          } else if (errorType.includes('server') || errorType.includes('5xx') || errorMessage.includes('internal error') || errorMessage.includes('server error')) {
+            stats.errorBreakdown.serverError++;
+          } else {
+            stats.errorBreakdown.other++;
+          }
+        }
+
+        return { ok: true, data: stats, meta: { source: 'analytics-adapter' } };
+      } catch (error) {
+        // Handle validation errors
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: {
+              code: 'INVALID_DATE_RANGE',
+              message: error.message,
+            },
+          });
+        }
+
+        platform.logger.error('Failed to fetch Embeddings usage stats', error instanceof Error ? error : new Error(String(error)));
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'EMBEDDINGS_USAGE_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch embeddings statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/vectorstore/daily-stats
+  // Returns time-bucketed aggregated VectorStore statistics for time-series visualization
+  // Query params: from, to, groupBy (hour|day|week|month), breakdownBy (dot-path), metrics (csv)
+  const vectorstoreDailyStatsPaths = resolvePaths(basePath, '/adapters/vectorstore/daily-stats');
+  for (const path of vectorstoreDailyStatsPaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getDailyStats) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support daily statistics',
+          },
+        });
+      }
+
+      try {
+        const dateRange = extractDateRange(request.query);
+        const statsOptions = extractStatsOptions(request.query);
+
+        const dailyStats = await analytics.getDailyStats({
+          type: ['vectorstore.search.completed', 'vectorstore.upsert.completed', 'vectorstore.delete.completed'],
+          from: dateRange.from,
+          to: dateRange.to,
+          limit: 50000,
+          ...statsOptions,
+        });
+
+        return reply.send({ ok: true, data: dailyStats });
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: { code: 'INVALID_DATE_RANGE', message: error.message },
+          });
+        }
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch daily statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/vectorstore/usage
+  // Returns aggregated VectorStore usage statistics
+  const vectorstoreUsagePaths = resolvePaths(basePath, '/adapters/vectorstore/usage');
+  for (const path of vectorstoreUsagePaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getEvents) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support reading events',
+          },
+        });
+      }
+
+      try {
+        // Extract and validate date range
+        const dateRange = extractDateRange(request.query);
+
+        const searchEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'vectorstore.search.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const upsertEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'vectorstore.upsert.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const deleteEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'vectorstore.delete.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const stats = {
+          searchQueries: searchEvents.length,
+          upsertOperations: upsertEvents.length,
+          deleteOperations: deleteEvents.length,
+          avgSearchDuration: 0,
+          // Enhanced: Search latency percentiles
+          p50SearchDuration: 0,
+          p95SearchDuration: 0,
+          p99SearchDuration: 0,
+          avgSearchScore: 0,
+          avgResultsCount: 0,
+          totalVectorsUpserted: 0,
+          totalVectorsDeleted: 0,
+        };
+
+        let totalSearchDuration = 0;
+        let totalSearchScore = 0;
+        let totalResultsCount = 0;
+        const searchDurations: number[] = [];
+
+        for (const event of searchEvents) {
+          const props = getEventData(event);
+
+          const duration = Number(props.durationMs || 0);
+          const avgScore = Number(props.avgScore || 0);
+          const resultsCount = Number(props.resultsCount || 0);
+
+          totalSearchDuration += duration;
+          totalSearchScore += avgScore;
+          totalResultsCount += resultsCount;
+          searchDurations.push(duration);
+        }
+
+        stats.avgSearchDuration = stats.searchQueries > 0 ? totalSearchDuration / stats.searchQueries : 0;
+        stats.avgSearchScore = stats.searchQueries > 0 ? totalSearchScore / stats.searchQueries : 0;
+        stats.avgResultsCount = stats.searchQueries > 0 ? totalResultsCount / stats.searchQueries : 0;
+
+        // Calculate search latency percentiles
+        if (searchDurations.length > 0) {
+          const sorted = searchDurations.slice().sort((a, b) => a - b);
+          const p50Index = Math.floor(sorted.length * 0.5);
+          const p95Index = Math.floor(sorted.length * 0.95);
+          const p99Index = Math.floor(sorted.length * 0.99);
+
+          stats.p50SearchDuration = sorted[p50Index] ?? 0;
+          stats.p95SearchDuration = sorted[p95Index] ?? 0;
+          stats.p99SearchDuration = sorted[p99Index] ?? 0;
+        }
+
+        for (const event of upsertEvents) {
+          const props = getEventData(event);
+          stats.totalVectorsUpserted += Number(props.vectorCount || 0);
+        }
+
+        for (const event of deleteEvents) {
+          const props = getEventData(event);
+          stats.totalVectorsDeleted += Number(props.idsCount || 0);
+        }
+
+        return { ok: true, data: stats, meta: { source: 'analytics-adapter' } };
+      } catch (error) {
+        // Handle validation errors
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: {
+              code: 'INVALID_DATE_RANGE',
+              message: error.message,
+            },
+          });
+        }
+
+        platform.logger.error('Failed to fetch VectorStore usage stats', error instanceof Error ? error : new Error(String(error)));
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'VECTORSTORE_USAGE_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch vectorstore statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/cache/daily-stats
+  // Returns time-bucketed aggregated Cache statistics for time-series visualization
+  // Query params: from, to, groupBy (hour|day|week|month), breakdownBy (dot-path), metrics (csv)
+  const cacheDailyStatsPaths = resolvePaths(basePath, '/adapters/cache/daily-stats');
+  for (const path of cacheDailyStatsPaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getDailyStats) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support daily statistics',
+          },
+        });
+      }
+
+      try {
+        const dateRange = extractDateRange(request.query);
+        const statsOptions = extractStatsOptions(request.query);
+
+        const dailyStats = await analytics.getDailyStats({
+          type: ['cache.get.hit', 'cache.get.miss', 'cache.set.completed'],
+          from: dateRange.from,
+          to: dateRange.to,
+          limit: 50000,
+          ...statsOptions,
+        });
+
+        return reply.send({ ok: true, data: dailyStats });
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: { code: 'INVALID_DATE_RANGE', message: error.message },
+          });
+        }
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch daily statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/cache/usage
+  // Returns aggregated Cache usage statistics
+  const cacheUsagePaths = resolvePaths(basePath, '/adapters/cache/usage');
+  for (const path of cacheUsagePaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getEvents) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support reading events',
+          },
+        });
+      }
+
+      try {
+        // Extract and validate date range
+        const dateRange = extractDateRange(request.query);
+
+        const hitEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'cache.get.hit',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+        const missEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'cache.get.miss',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+        const setEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'cache.set.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const totalGets = hitEvents.length + missEvents.length;
+        const hitRate = totalGets > 0 ? (hitEvents.length / totalGets) * 100 : 0;
+
+        const stats = {
+          totalGets,
+          hits: hitEvents.length,
+          misses: missEvents.length,
+          hitRate,
+          sets: setEvents.length,
+          avgGetDuration: 0,
+          avgSetDuration: 0,
+        };
+
+        let totalGetDuration = 0;
+        for (const event of [...hitEvents, ...missEvents]) {
+          const props = getEventData(event);
+          totalGetDuration += Number(props.durationMs || 0);
+        }
+        stats.avgGetDuration = totalGets > 0 ? totalGetDuration / totalGets : 0;
+
+        let totalSetDuration = 0;
+        for (const event of setEvents) {
+          const props = getEventData(event);
+          totalSetDuration += Number(props.durationMs || 0);
+        }
+        stats.avgSetDuration = stats.sets > 0 ? totalSetDuration / stats.sets : 0;
+
+        return { ok: true, data: stats, meta: { source: 'analytics-adapter' } };
+      } catch (error) {
+        // Handle validation errors
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: {
+              code: 'INVALID_DATE_RANGE',
+              message: error.message,
+            },
+          });
+        }
+
+        platform.logger.error('Failed to fetch Cache usage stats', error instanceof Error ? error : new Error(String(error)));
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'CACHE_USAGE_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch cache statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/storage/daily-stats
+  // Returns time-bucketed aggregated Storage statistics for time-series visualization
+  // Query params: from, to, groupBy (hour|day|week|month), breakdownBy (dot-path), metrics (csv)
+  const storageDailyStatsPaths = resolvePaths(basePath, '/adapters/storage/daily-stats');
+  for (const path of storageDailyStatsPaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getDailyStats) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support daily statistics',
+          },
+        });
+      }
+
+      try {
+        const dateRange = extractDateRange(request.query);
+        const statsOptions = extractStatsOptions(request.query);
+
+        const dailyStats = await analytics.getDailyStats({
+          type: ['storage.read.completed', 'storage.write.completed', 'storage.delete.completed'],
+          from: dateRange.from,
+          to: dateRange.to,
+          limit: 50000,
+          ...statsOptions,
+        });
+
+        return reply.send({ ok: true, data: dailyStats });
+      } catch (error) {
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: { code: 'INVALID_DATE_RANGE', message: error.message },
+          });
+        }
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'DAILY_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch daily statistics',
+          },
+        });
+      }
+    });
+  }
+
+  // GET /api/v1/adapters/storage/usage
+  // Returns aggregated Storage usage statistics
+  const storageUsagePaths = resolvePaths(basePath, '/adapters/storage/usage');
+  for (const path of storageUsagePaths) {
+    fastify.get(path, async (request, reply) => {
+      const analytics = platform.analytics;
+
+      if (!analytics.getEvents) {
+        return reply.code(501).send({
+          ok: false,
+          error: {
+            code: 'ANALYTICS_NOT_IMPLEMENTED',
+            message: 'Analytics adapter does not support reading events',
+          },
+        });
+      }
+
+      try {
+        // Extract and validate date range
+        const dateRange = extractDateRange(request.query);
+
+        const readEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'storage.read.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+        const writeEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'storage.write.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+        const deleteEvents = await fetchAllEventsBatched(
+          analytics,
+          {
+            type: 'storage.delete.completed',
+            from: dateRange.from,
+            to: dateRange.to,
+          },
+          fastify
+        );
+
+        const stats = {
+          readOperations: readEvents.length,
+          writeOperations: writeEvents.length,
+          deleteOperations: deleteEvents.length,
+          totalBytesRead: 0,
+          totalBytesWritten: 0,
+          avgReadDuration: 0,
+          avgWriteDuration: 0,
+        };
+
+        let totalReadDuration = 0;
+        for (const event of readEvents) {
+          const props = getEventData(event);
+          stats.totalBytesRead += Number(props.bytesRead || 0);
+          totalReadDuration += Number(props.durationMs || 0);
+        }
+        stats.avgReadDuration = stats.readOperations > 0 ? totalReadDuration / stats.readOperations : 0;
+
+        let totalWriteDuration = 0;
+        for (const event of writeEvents) {
+          const props = getEventData(event);
+          stats.totalBytesWritten += Number(props.bytesWritten || 0);
+          totalWriteDuration += Number(props.durationMs || 0);
+        }
+        stats.avgWriteDuration = stats.writeOperations > 0 ? totalWriteDuration / stats.writeOperations : 0;
+
+        return { ok: true, data: stats, meta: { source: 'analytics-adapter' } };
+      } catch (error) {
+        // Handle validation errors
+        if (error instanceof Error && error.message.includes('Invalid')) {
+          return reply.code(400).send({
+            ok: false,
+            error: {
+              code: 'INVALID_DATE_RANGE',
+              message: error.message,
+            },
+          });
+        }
+
+        platform.logger.error('Failed to fetch Storage usage stats', error instanceof Error ? error : new Error(String(error)));
+        return reply.code(500).send({
+          ok: false,
+          error: {
+            code: 'STORAGE_USAGE_STATS_ERROR',
+            message: error instanceof Error ? error.message : 'Failed to fetch storage statistics',
+          },
+        });
+      }
+    });
+  }
+
+  fastify.log.info('Platform adapter routes registered');
+}