@kb-labs/studio-app 0.7.0 → 2.9.0

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

@@ -1,279 +0,0 @@
-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

@@ -1,133 +0,0 @@
-/**
- * @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

@@ -1,148 +0,0 @@
-/**
- * @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

@@ -1,100 +0,0 @@
-/**
- * @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)}%`;
-}