update analytics for api usage (forgot to stage untracked)

Author: 0xGingi

AGENTS.md

@@ -0,0 +1,99 @@
+# Agent Development Guidelines
+
+## API Documentation Requirement
+
+**IMPORTANT**: Whenever making changes to API endpoints, you MUST update the `api-docs.md` file to reflect those changes.
+
+## When to Update api-docs.md
+
+Update the documentation when:
+
+1. **Creating a new endpoint** - Add full documentation including:
+   - HTTP method and path
+   - Authentication requirement (Session, API Key, or Public)
+   - Request body schema (if applicable)
+   - Query parameters (if applicable)
+   - Response schema
+   - CURL example
+
+2. **Modifying an existing endpoint** - Update:
+   - Request/response schema changes
+   - Authentication changes
+   - New query parameters or body fields
+
+3. **Deleting an endpoint** - Remove the endpoint from documentation
+
+4. **Changing authentication** - Update the `**Authentication**:` line
+
+## Authentication Types
+
+Use one of these authentication labels:
+
+- `**Authentication**: Session or API Key` - Most common for authenticated endpoints
+- `**Authentication**: Session or API Key (owner only)` - When ownership is required
+- `**Authentication**: Session or API Key (owner or editor)` - Role-based access
+- `**Authentication**: None` - Public endpoints
+- `**Authentication**: Session` - Session-only endpoints (TTS/STT use this pattern)
+
+## Authentication Implementation
+
+For new authenticated endpoints, use the shared auth utility:
+
+```typescript
+import { getAuthenticatedUserId } from '$lib/backend/auth-utils';
+
+export async function GET({ request }: RequestEvent) {
+    const userId = await getAuthenticatedUserId(request);
+    // ... endpoint logic
+}
+```
+
+For optional authentication (public with optional user context):
+
+```typescript
+import { tryGetAuthenticatedUserId } from '$lib/backend/auth-utils';
+
+export async function GET({ request }: RequestEvent) {
+    const userId = await tryGetAuthenticatedUserId(request);
+    // userId may be undefined if not authenticated
+}
+```
+
+## Documentation Format
+
+Follow this template when adding a new endpoint:
+
+```markdown
+#### METHOD `/api/endpoint-path`
+Brief description of what the endpoint does.
+
+**Authentication**: Session or API Key
+
+**Request Body**:
+\`\`\`json
+{
+  "field": "type (description)"
+}
+\`\`\`
+
+**Response**:
+\`\`\`json
+{
+  "field": "type"
+}
+\`\`\`
+
+**CURL Example**:
+\`\`\`bash
+curl -X METHOD "http://localhost:3432/api/endpoint-path" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer your_api_key" \
+  -d '{"field": "value"}'
+\`\`\`
+```
+
+## Reference Files
+
+- API documentation: `api-docs.md`
+- Auth utility: `src/lib/backend/auth-utils.ts`
+- API endpoints: `src/routes/api/`

src/lib/analytics/model-analytics.ts

@@ -0,0 +1,106 @@
+import type { ModelPerformanceStats } from '$lib/db/schema';
+import {
+	calculateAllModelPerformanceStats,
+	getModelPerformanceStatsByUser,
+} from '$lib/db/queries/model-performance';
+
+export type ModelAnalyticsInsights = {
+	totalMessages: number;
+	totalCost: number;
+	avgRating: number | null;
+	mostUsedModel: ModelPerformanceStats | null;
+	bestRatedModel: ModelPerformanceStats | null;
+	mostCostEffective: ModelPerformanceStats | null;
+	fastestModel: ModelPerformanceStats | null;
+};
+
+export async function getModelAnalytics(
+	userId: string,
+	options?: { recalculate?: boolean }
+): Promise<{ stats: ModelPerformanceStats[]; insights: ModelAnalyticsInsights }> {
+	const recalculate = options?.recalculate ?? true;
+
+	const stats = recalculate
+		? await calculateAllModelPerformanceStats(userId)
+		: await getModelPerformanceStatsByUser(userId);
+
+	const insights = buildModelAnalyticsInsights(stats);
+	return { stats, insights };
+}
+
+export function buildModelAnalyticsInsights(
+	stats: ModelPerformanceStats[]
+): ModelAnalyticsInsights {
+	const totalMessages = stats.reduce((sum, s) => sum + s.totalMessages, 0);
+	const totalCost = stats.reduce((sum, s) => {
+		const cost = s.totalCost;
+		if (cost === null || cost === undefined || Number.isNaN(cost)) {
+			return sum;
+		}
+		return sum + cost;
+	}, 0);
+
+	const ratedStats = stats.filter((s) => s.avgRating !== null && s.avgRating !== undefined);
+	const avgRating =
+		ratedStats.length > 0
+			? ratedStats.reduce((sum, s) => sum + (s.avgRating ?? 0), 0) / ratedStats.length
+			: null;
+
+	const mostUsedModel =
+		stats.length > 0
+			? stats.reduce(
+					(prev, current) => (current.totalMessages > prev.totalMessages ? current : prev),
+					stats[0]!
+				)
+			: null;
+
+	const qualifiedModels = stats.filter((s) => s.totalMessages >= 5 && s.avgRating !== null);
+	const bestRatedModel =
+		qualifiedModels.length > 0
+			? qualifiedModels.reduce((prev, current) =>
+					(current.avgRating ?? 0) > (prev.avgRating ?? 0) ? current : prev
+				)
+			: null;
+
+	const modelsWithCost = stats.filter(
+		(s) => s.totalMessages >= 5 && s.totalCost > 0 && !Number.isNaN(s.totalCost)
+	);
+	const mostCostEffective =
+		modelsWithCost.length > 0
+			? modelsWithCost.reduce((prev, current) => {
+					const prevCostPerMsg = prev.totalCost / prev.totalMessages;
+					const currentCostPerMsg = current.totalCost / current.totalMessages;
+					return currentCostPerMsg < prevCostPerMsg ? current : prev;
+				})
+			: null;
+
+	const modelsWithSpeed = stats.filter(
+		(s) =>
+			s.totalMessages >= 5 &&
+			s.avgTokens !== null &&
+			s.avgTokens !== undefined &&
+			s.avgResponseTime !== null &&
+			s.avgResponseTime !== undefined &&
+			s.avgResponseTime > 0
+	);
+
+	const fastestModel =
+		modelsWithSpeed.length > 0
+			? modelsWithSpeed.reduce((prev, current) => {
+					const prevSpeed = (prev.avgTokens ?? 0) / ((prev.avgResponseTime ?? 0) / 1000 || 1);
+					const currentSpeed =
+						(current.avgTokens ?? 0) / ((current.avgResponseTime ?? 0) / 1000 || 1);
+					return currentSpeed > prevSpeed ? current : prev;
+				})
+			: null;
+
+	return {
+		totalMessages,
+		totalCost,
+		avgRating,
+		mostUsedModel,
+		bestRatedModel,
+		mostCostEffective,
+		fastestModel,
+	};
+}

src/routes/api/analytics/+server.ts

@@ -0,0 +1,25 @@
+import { json, error } from '@sveltejs/kit';
+import type { RequestHandler } from './$types';
+import { getAuthenticatedUserId } from '$lib/backend/auth-utils';
+import { getModelAnalytics } from '$lib/analytics/model-analytics';
+
+export const GET: RequestHandler = async ({ request, url }) => {
+	try {
+		const userId = await getAuthenticatedUserId(request);
+		const recalculate = url.searchParams.get('recalculate') !== 'false';
+
+		console.log(
+			`[analytics] Fetching analytics for user ${userId} (recalculate: ${recalculate})`
+		);
+
+		const { stats, insights } = await getModelAnalytics(userId, { recalculate });
+
+		return json({ success: true, stats, insights });
+	} catch (err) {
+		console.error('[analytics] Error fetching analytics:', err);
+		if (err && typeof err === 'object' && 'status' in err) {
+			throw err;
+		}
+		throw error(500, 'Failed to fetch analytics');
+	}
+};