@kb-labs/studio-app 0.6.0

package/src/modules/analytics/pages/analytics-vectorstore-page.tsx

@@ -0,0 +1,279 @@
+import { useState } from 'react';
+import { UIRow, UICol, UIStatistic, UIAlert, UIProgress } from '@kb-labs/studio-ui-kit';
+import {
+  SearchOutlined,
+  PlusCircleOutlined,
+  DeleteOutlined,
+  ClockCircleOutlined,
+  StarOutlined,
+  FileSearchOutlined,
+  DatabaseOutlined,
+} from '@ant-design/icons';
+import { UIText, UIStatisticsChart, UICard, UIPage, UIPageHeader } from '@kb-labs/studio-ui-kit';
+import { useAdaptersVectorStoreUsage, useAdaptersVectorStoreDailyStats } from '@kb-labs/studio-data-client';
+import { useDataSources } from '../../../providers/data-sources-provider';
+import { AnalyticsDateRangePicker, type DateRangeValue } from '../components/analytics-date-range-picker';
+import dayjs from 'dayjs';
+
+
+/**
+ * Analytics VectorStore Usage Page
+ *
+ * Displays vector database usage statistics:
+ * - Search, upsert, and delete operations
+ * - Search quality metrics (avg score)
+ * - Performance metrics
+ * - Storage growth tracking
+ */
+export function AnalyticsVectorStorePage() {
+  const sources = useDataSources();
+
+  // Date range state (default: last 30 days)
+  const [dateRange, setDateRange] = useState<DateRangeValue>([
+    dayjs().subtract(30, 'days'),
+    dayjs(),
+  ]);
+
+  const {
+    data: stats,
+    isLoading,
+    error,
+    isError,
+  } = useAdaptersVectorStoreUsage(sources.adapters, {
+    from: dateRange[0].toISOString(),
+    to: dateRange[1].toISOString(),
+  });
+
+  const {
+    data: dailyStats,
+    isLoading: dailyStatsLoading,
+  } = useAdaptersVectorStoreDailyStats(sources.adapters, {
+    from: dateRange[0].toISOString(),
+    to: dateRange[1].toISOString(),
+  });
+
+  // Check if analytics is not implemented
+  const analyticsNotImplemented =
+    isError &&
+    error instanceof Error &&
+    (error.message.includes('not support') || error.message.includes('not implement'));
+
+  if (analyticsNotImplemented) {
+    return (
+      <UIPage>
+        <UIPageHeader
+          title="VectorStore Usage"
+          description="Track vector database operations and search quality"
+        />
+        <UIAlert
+          message="Analytics Not Available"
+          description="Analytics adapter does not support reading events. Configure an analytics adapter in kb.config.json that implements getEvents()."
+          variant="info"
+          showIcon
+          style={{ marginTop: 16 }}
+        />
+      </UIPage>
+    );
+  }
+
+  if (isError) {
+    return (
+      <UIPage>
+        <UIPageHeader title="VectorStore Usage" description="Vector database usage analytics" />
+        <UIAlert
+          message="Failed to Load VectorStore Usage"
+          description={error?.message || 'Unknown error occurred'}
+          variant="error"
+          showIcon
+          style={{ marginTop: 16 }}
+        />
+      </UIPage>
+    );
+  }
+
+  // Format helpers
+  const _formatNumber = (num: number) => num.toLocaleString();
+  const _formatDuration = (ms: number) => (ms < 1000 ? `${ms.toFixed(1)}ms` : `${(ms / 1000).toFixed(2)}s`);
+  const _formatScore = (score: number) => (score * 100).toFixed(1) + '%';
+
+  const totalOperations = stats
+    ? stats.searchQueries + stats.upsertOperations + stats.deleteOperations
+    : 0;
+
+  const searchPercentage = stats && totalOperations > 0
+    ? ((stats.searchQueries / totalOperations) * 100).toFixed(1)
+    : 0;
+
+  const scoreStatus = stats && stats.avgSearchScore >= 0.8
+    ? 'success'
+    : stats && stats.avgSearchScore >= 0.6
+    ? 'normal'
+    : 'exception';
+
+  return (
+    <UIPage width="full">
+      <UIPageHeader
+        title="VectorStore Usage Analytics"
+        description="Track vector database operations, search quality, and storage growth"
+        actions={
+          <AnalyticsDateRangePicker
+            value={dateRange}
+            onChange={setDateRange}
+          />
+        }
+      />
+
+      <div style={{ marginTop: 24 }}>
+        {/* Overview Stats */}
+        <UIRow gutter={[16, 16]}>
+          <UICol xs={24} sm={12} lg={6}>
+            <UICard>
+              <UIStatistic
+                title="Search Queries"
+                value={stats?.searchQueries ?? 0}
+                prefix={<SearchOutlined />}
+                loading={isLoading}
+                valueStyle={{ color: 'var(--info)' }}
+              />
+            </UICard>
+          </UICol>
+          <UICol xs={24} sm={12} lg={6}>
+            <UICard>
+              <UIStatistic
+                title="Upsert Operations"
+                value={stats?.upsertOperations ?? 0}
+                prefix={<PlusCircleOutlined />}
+                loading={isLoading}
+                valueStyle={{ color: 'var(--success)' }}
+              />
+            </UICard>
+          </UICol>
+          <UICol xs={24} sm={12} lg={6}>
+            <UICard>
+              <UIStatistic
+                title="Delete Operations"
+                value={stats?.deleteOperations ?? 0}
+                prefix={<DeleteOutlined />}
+                loading={isLoading}
+                valueStyle={{ color: 'var(--warning)' }}
+              />
+            </UICard>
+          </UICol>
+          <UICol xs={24} sm={12} lg={6}>
+            <UICard>
+              <UIStatistic
+                title="Total Operations"
+                value={totalOperations}
+                prefix={<DatabaseOutlined />}
+                loading={isLoading}
+                valueStyle={{ color: 'var(--link)' }}
+              />
+            </UICard>
+          </UICol>
+        </UIRow>
+
+        {/* Search Quality */}
+        <UIRow gutter={[16, 16]} style={{ marginTop: 16 }}>
+          <UICol xs={24} lg={12}>
+            <UICard title="Search Quality">
+              <UIStatistic
+                title="Average Search Score"
+                value={stats?.avgSearchScore ?? 0}
+                precision={3}
+                prefix={<StarOutlined />}
+                loading={isLoading}
+                valueStyle={{
+                  color: scoreStatus === 'success' ? 'var(--success)' : scoreStatus === 'normal' ? 'var(--info)' : 'var(--warning)'
+                }}
+              />
+              <div style={{ marginTop: 16 }}>
+                <UIText color="secondary">Search Quality Rating</UIText>
+                <UIProgress
+                  percent={Number(((stats?.avgSearchScore ?? 0) * 100).toFixed(1))}
+                  status={scoreStatus}
+                  format={(percent) => `${percent}%`}
+                />
+              </div>
+              <div style={{ marginTop: 16 }}>
+                <UIStatistic
+                  title="Avg Results per Query"
+                  value={stats?.avgResultsCount ?? 0}
+                  precision={1}
+                  prefix={<FileSearchOutlined />}
+                  loading={isLoading}
+                />
+              </div>
+            </UICard>
+          </UICol>
+          <UICol xs={24} lg={12}>
+            <UICard title="Performance Metrics">
+              <UIStatistic
+                title="Avg Search Duration"
+                value={stats?.avgSearchDuration ?? 0}
+                prefix={<ClockCircleOutlined />}
+                suffix="ms"
+                precision={1}
+                loading={isLoading}
+              />
+              <div style={{ marginTop: 24 }}>
+                <UIText color="secondary">Operation Distribution</UIText>
+                <UIProgress
+                  percent={Number(searchPercentage)}
+                  format={(percent) => `${percent}% searches`}
+                />
+              </div>
+            </UICard>
+          </UICol>
+        </UIRow>
+
+        {/* Storage Growth */}
+        <UICard title="Storage Statistics" style={{ marginTop: 16 }}>
+          <UIRow gutter={[16, 16]}>
+            <UICol xs={24} sm={8}>
+              <UIStatistic
+                title="Vectors Added"
+                value={stats?.totalVectorsUpserted ?? 0}
+                prefix={<PlusCircleOutlined />}
+                valueStyle={{ color: 'var(--success)' }}
+                loading={isLoading}
+              />
+            </UICol>
+            <UICol xs={24} sm={8}>
+              <UIStatistic
+                title="Vectors Deleted"
+                value={stats?.totalVectorsDeleted ?? 0}
+                prefix={<DeleteOutlined />}
+                valueStyle={{ color: 'var(--error)' }}
+                loading={isLoading}
+              />
+            </UICol>
+            <UICol xs={24} sm={8}>
+              <UIStatistic
+                title="Net Growth"
+                value={(stats?.totalVectorsUpserted ?? 0) - (stats?.totalVectorsDeleted ?? 0)}
+                loading={isLoading}
+                valueStyle={{
+                  color: (stats?.totalVectorsUpserted ?? 0) > (stats?.totalVectorsDeleted ?? 0)
+                    ? 'var(--success)'
+                    : 'var(--error)'
+                }}
+              />
+            </UICol>
+          </UIRow>
+        </UICard>
+
+        {/* Daily Usage Chart */}
+        <UIStatisticsChart
+          data={dailyStats}
+          loading={dailyStatsLoading}
+          title="Daily VectorStore Operations"
+          metrics={[
+            { key: 'totalSearches', label: 'Searches' },
+            { key: 'totalUpserts', label: 'Upserts' },
+            { key: 'totalDeletes', label: 'Deletes' },
+          ]}
+        />
+      </div>
+    </UIPage>
+  );
+}

package/src/modules/analytics/routes/index.tsx

@@ -0,0 +1,133 @@
+/**
+ * @module @kb-labs/studio-app/modules/analytics/routes
+ * Analytics module routing configuration
+ */
+
+import type { RouteObject } from 'react-router-dom';
+import { AnalyticsOverviewPage } from '../pages/analytics-overview-page';
+import { AnalyticsEventsPage } from '../pages/analytics-events-page';
+import { AnalyticsLLMPage } from '../pages/analytics-llm-page';
+import { AnalyticsEmbeddingsPage } from '../pages/analytics-embeddings-page';
+import { AnalyticsVectorStorePage } from '../pages/analytics-vectorstore-page';
+import { AnalyticsCachePage } from '../pages/analytics-cache-page';
+import { AnalyticsStoragePage } from '../pages/analytics-storage-page';
+import { ErrorBoundary } from '../../../components/error-boundary';
+import { renderIcon } from '../../../routes/helpers';
+import type { NavigationItem } from '@/components/ui';
+
+// Route paths
+const PATHS = {
+  OVERVIEW: '/analytics/overview',
+  EVENTS: '/analytics/events',
+  LLM: '/analytics/llm',
+  EMBEDDINGS: '/analytics/embeddings',
+  VECTORSTORE: '/analytics/vectorstore',
+  CACHE: '/analytics/cache',
+  STORAGE: '/analytics/storage',
+} as const;
+
+// Route keys
+const KEYS = {
+  MODULE: 'analytics',
+  OVERVIEW: 'analytics-overview',
+  EVENTS: 'analytics-events',
+  LLM: 'analytics-llm',
+  EMBEDDINGS: 'analytics-embeddings',
+  VECTORSTORE: 'analytics-vectorstore',
+  CACHE: 'analytics-cache',
+  STORAGE: 'analytics-storage',
+} as const;
+
+/**
+ * Analytics routes
+ */
+export const analyticsRoutes: RouteObject[] = [
+  {
+    path: PATHS.OVERVIEW,
+    element: <AnalyticsOverviewPage />,
+    errorElement: <ErrorBoundary />,
+  },
+  {
+    path: PATHS.EVENTS,
+    element: <AnalyticsEventsPage />,
+    errorElement: <ErrorBoundary />,
+  },
+  {
+    path: PATHS.LLM,
+    element: <AnalyticsLLMPage />,
+    errorElement: <ErrorBoundary />,
+  },
+  {
+    path: PATHS.EMBEDDINGS,
+    element: <AnalyticsEmbeddingsPage />,
+    errorElement: <ErrorBoundary />,
+  },
+  {
+    path: PATHS.VECTORSTORE,
+    element: <AnalyticsVectorStorePage />,
+    errorElement: <ErrorBoundary />,
+  },
+  {
+    path: PATHS.CACHE,
+    element: <AnalyticsCachePage />,
+    errorElement: <ErrorBoundary />,
+  },
+  {
+    path: PATHS.STORAGE,
+    element: <AnalyticsStoragePage />,
+    errorElement: <ErrorBoundary />,
+  },
+];
+
+/**
+ * Analytics navigation item for sidebar
+ */
+export const analyticsNavigation: NavigationItem = {
+  key: KEYS.MODULE,
+  label: 'Analytics',
+  icon: renderIcon('BarChartOutlined'),
+  children: [
+    {
+      key: KEYS.OVERVIEW,
+      label: 'Overview',
+      path: PATHS.OVERVIEW,
+      icon: renderIcon('DashboardOutlined'),
+    },
+    {
+      key: KEYS.EVENTS,
+      label: 'Events',
+      path: PATHS.EVENTS,
+      icon: renderIcon('ThunderboltOutlined'),
+    },
+    {
+      key: KEYS.LLM,
+      label: 'LLM Usage',
+      path: PATHS.LLM,
+      icon: renderIcon('RobotOutlined'),
+    },
+    {
+      key: KEYS.EMBEDDINGS,
+      label: 'Embeddings',
+      path: PATHS.EMBEDDINGS,
+      icon: renderIcon('NodeIndexOutlined'),
+    },
+    {
+      key: KEYS.VECTORSTORE,
+      label: 'Vector Store',
+      path: PATHS.VECTORSTORE,
+      icon: renderIcon('DatabaseOutlined'),
+    },
+    {
+      key: KEYS.CACHE,
+      label: 'Cache',
+      path: PATHS.CACHE,
+      icon: renderIcon('ThunderboltOutlined'),
+    },
+    {
+      key: KEYS.STORAGE,
+      label: 'Storage',
+      path: PATHS.STORAGE,
+      icon: renderIcon('SaveOutlined'),
+    },
+  ],
+};

package/src/modules/analytics/utils/formatters.test.ts

@@ -0,0 +1,148 @@
+/**
+ * @module analytics/utils/formatters.test
+ * Tests for analytics formatters
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatCost } from './formatters';
+
+describe('formatCost', () => {
+  describe('real backend data - single LLM calls', () => {
+    it('should format very small costs (individual API calls)', () => {
+      // Real data from events-20260116.jsonl
+      expect(formatCost(0.000043349999999999997)).toBe('$4.33e-5'); // 145+36 tokens
+      expect(formatCost(0.00008730000000000001)).toBe('$8.73e-5'); // 234+87 tokens
+      expect(formatCost(0.0005536499999999999)).toBe('$0.000554'); // 2847+211 tokens
+      expect(formatCost(0.0001407)).toBe('$0.000141'); // 514+106 tokens
+    });
+
+    it('should format slightly larger costs', () => {
+      expect(formatCost(0.00028695)).toBe('$0.000287'); // Original bug example
+      expect(formatCost(0.000044399999999999995)).toBe('$4.44e-5'); // 160+34 tokens
+    });
+  });
+
+  describe('aggregated daily costs', () => {
+    it('should format daily totals', () => {
+      // Simulate 100 small API calls per day
+      const dailyTotal = 0.000043 * 100; // ≈ $0.0043
+      expect(formatCost(dailyTotal)).toBe('$0.004300');
+
+      // Simulate 1000 small API calls per day
+      const largeDailyTotal = 0.000043 * 1000; // ≈ $0.043
+      expect(formatCost(largeDailyTotal)).toBe('$0.0430');
+    });
+
+    it('should format typical production daily costs', () => {
+      expect(formatCost(0.001)).toBe('$0.001000'); // 6 decimals for $0.001
+      expect(formatCost(0.01)).toBe('$0.0100'); // 4 decimals for $0.01
+      expect(formatCost(0.1)).toBe('$0.1000'); // 4 decimals for $0.10
+      expect(formatCost(1.5)).toBe('$1.50'); // 2 decimals for $1.50
+      expect(formatCost(10.99)).toBe('$10.99'); // 2 decimals for $10.99
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle zero cost', () => {
+      expect(formatCost(0)).toBe('$0.00');
+    });
+
+    it('should handle very tiny costs (scientific notation)', () => {
+      expect(formatCost(0.00000012)).toBe('$1.20e-7');
+      expect(formatCost(0.000000001)).toBe('$1.00e-9');
+    });
+
+    it('should handle large costs', () => {
+      expect(formatCost(100.456)).toBe('$100.46');
+      expect(formatCost(1000.123)).toBe('$1000.12');
+    });
+  });
+
+  describe('precision thresholds', () => {
+    it('should use 2 decimals for >= $1', () => {
+      expect(formatCost(1)).toBe('$1.00');
+      expect(formatCost(1.234)).toBe('$1.23');
+      expect(formatCost(1.235)).toBe('$1.24'); // Rounds up
+    });
+
+    it('should use 4 decimals for >= $0.01', () => {
+      expect(formatCost(0.01)).toBe('$0.0100');
+      expect(formatCost(0.012345)).toBe('$0.0123');
+      expect(formatCost(0.012355)).toBe('$0.0124'); // Rounds up
+    });
+
+    it('should use 6 decimals for >= $0.0001', () => {
+      expect(formatCost(0.0001)).toBe('$0.000100');
+      expect(formatCost(0.00012345)).toBe('$0.000123');
+      expect(formatCost(0.00012355)).toBe('$0.000124'); // Rounds up
+    });
+
+    it('should use scientific notation for < $0.0001', () => {
+      expect(formatCost(0.00009999)).toBe('$1.00e-4');
+      expect(formatCost(0.00001)).toBe('$1.00e-5');
+    });
+  });
+
+  describe('what we expect to see in the chart tooltip', () => {
+    it('should show readable values for typical daily aggregates', () => {
+      // If we have 10 requests/day with avg $0.00028695 each
+      const cost = 10 * 0.00028695; // = $0.0028695
+      expect(formatCost(cost)).toBe('$0.002870'); // 6 decimals, readable
+
+      // If we have 100 requests/day
+      const cost100 = 100 * 0.00028695; // = $0.028695
+      expect(formatCost(cost100)).toBe('$0.0287'); // 4 decimals, readable
+
+      // If we have 1000 requests/day
+      const cost1000 = 1000 * 0.00028695; // = $0.28695
+      expect(formatCost(cost1000)).toBe('$0.2869'); // 4 decimals, readable (rounds down)
+    });
+
+    it('should NOT show $0.00 for small but non-zero values', () => {
+      // These should all be visible (not $0.00)
+      expect(formatCost(0.00028695)).not.toBe('$0.00');
+      expect(formatCost(0.000043)).not.toBe('$0.00');
+      expect(formatCost(0.001)).not.toBe('$0.00');
+    });
+  });
+
+  describe('real world scenario: what chart shows on Jan 16', () => {
+    it('should handle sum of all LLM calls on Jan 16', () => {
+      // Sample from real data:
+      const costs = [
+        0.000043349999999999997,
+        0.000043349999999999997,
+        0.00008730000000000001,
+        0.0005536499999999999,
+        0.0001407,
+      ];
+
+      const total = costs.reduce((sum, c) => sum + c, 0);
+      // Total ≈ 0.00086265
+
+      const formatted = formatCost(total);
+
+      // Should be visible with 6 decimals
+      expect(formatted).toBe('$0.000868'); // Actual rounded value
+
+      // Should NOT be $0.00
+      expect(formatted).not.toBe('$0.00');
+
+      // Should NOT be scientific notation (since > $0.0001)
+      expect(formatted).not.toContain('e');
+    });
+
+    it('should handle very low daily total (few requests)', () => {
+      // If only 2-3 requests on a day
+      const lowDailyTotal = 0.000043 + 0.000087; // $0.00013
+
+      const formatted = formatCost(lowDailyTotal);
+
+      // Should use 6 decimals (since >= $0.0001)
+      expect(formatted).toBe('$0.000130');
+
+      // Should NOT be $0.00
+      expect(formatted).not.toBe('$0.00');
+    });
+  });
+});

package/src/modules/analytics/utils/formatters.ts

@@ -0,0 +1,100 @@
+/**
+ * @module analytics/utils/formatters
+ * Common formatting utilities for analytics pages
+ */
+
+/**
+ * Format cost with adaptive precision based on magnitude.
+ *
+ * Uses different decimal places depending on the value:
+ * - >= $1.00: 2 decimal places ($12.34)
+ * - >= $0.01: 4 decimal places ($0.0123)
+ * - >= $0.0001: 6 decimal places ($0.000123)
+ * - < $0.0001: scientific notation ($1.23e-7)
+ *
+ * This ensures tiny costs (like $0.00028695) are visible in charts
+ * while keeping larger values readable.
+ *
+ * @example
+ * formatCost(12.3456) // "$12.35"
+ * formatCost(0.0123456) // "$0.0123"
+ * formatCost(0.00028695) // "$0.000287"
+ * formatCost(0.00000012) // "$1.20e-7"
+ */
+export function formatCost(cost: number | undefined | null): string {
+  if (cost == null || isNaN(cost)) {
+    return '$0.00';
+  }
+  // Handle zero explicitly
+  if (cost === 0) {
+    return '$0.00';
+  }
+
+  if (cost >= 1) {
+    return `$${cost.toFixed(2)}`;
+  }
+  if (cost >= 0.01) {
+    return `$${cost.toFixed(4)}`;
+  }
+  if (cost >= 0.0001) {
+    return `$${cost.toFixed(6)}`;
+  }
+  // For very small values (< $0.0001), use scientific notation
+  return `$${cost.toExponential(2)}`;
+}
+
+/**
+ * Format number with thousand separators.
+ *
+ * @example
+ * formatNumber(1234567) // "1,234,567"
+ */
+export function formatNumber(num: number): string {
+  return num.toLocaleString();
+}
+
+/**
+ * Format duration in milliseconds to human-readable string.
+ *
+ * @example
+ * formatDuration(500) // "500ms"
+ * formatDuration(2500) // "2.50s"
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) {
+    return `${ms.toFixed(0)}ms`;
+  }
+  return `${(ms / 1000).toFixed(2)}s`;
+}
+
+/**
+ * Format byte size to human-readable string.
+ *
+ * @example
+ * formatSize(512) // "512 B"
+ * formatSize(2048) // "2.00 KB"
+ * formatSize(1048576) // "1.00 MB"
+ */
+export function formatSize(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${(bytes / 1024).toFixed(2)} KB`;
+  }
+  if (bytes < 1024 * 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+  }
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+}
+
+/**
+ * Format percentage value.
+ *
+ * @example
+ * formatPercentage(0.856) // "85.6%"
+ * formatPercentage(0.1234) // "12.3%"
+ */
+export function formatPercentage(value: number): string {
+  return `${(value * 100).toFixed(1)}%`;
+}