@farming-labs/theme 0.1.71 → 0.1.72

package/dist/docs-api.d.mts

@@ -1,4 +1,4 @@
-import { ChangelogConfig, DocsAnalyticsConfig, DocsI18nConfig, DocsMcpConfig, DocsSearchConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
+import { ChangelogConfig, DocsAnalyticsConfig, DocsI18nConfig, DocsMcpConfig, DocsObservabilityConfig, DocsSearchConfig, FeedbackConfig, OrderingItem } from "@farming-labs/docs";
 
 //#region src/docs-api.d.ts
 interface AIProviderConfig {
@@ -43,6 +43,8 @@ interface DocsAPIOptions {
   search?: boolean | DocsSearchConfig;
   /** Analytics configuration */
   analytics?: boolean | DocsAnalyticsConfig;
+  /** Observability configuration for logs, traces, and metrics callbacks. */
+  observability?: boolean | DocsObservabilityConfig;
   /** Feedback configuration */
   feedback?: boolean | FeedbackConfig;
   /** MCP configuration used for the agent discovery spec. */
@@ -59,6 +61,7 @@ interface DocsMCPAPIOptions {
   mcp?: boolean | DocsMcpConfig;
   search?: boolean | DocsSearchConfig;
   analytics?: boolean | DocsAnalyticsConfig;
+  observability?: boolean | DocsObservabilityConfig;
 }
 /**
  * Create a unified docs API route handler.

package/dist/docs-api.mjs

@@ -3,7 +3,7 @@ import { getNextAppDir } from "./get-app-dir.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { emitDocsAnalyticsEvent, normalizeDocsRelated, performDocsSearch, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig } from "@farming-labs/docs";
+import { createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, normalizeDocsRelated, performDocsSearch, renderDocsRelatedMarkdownLines, resolveChangelogConfig, resolveDocsI18n, resolveDocsLocale, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig } from "@farming-labs/docs";
 import { createDocsMcpHttpHandler, createFilesystemDocsMcpSource, resolveDocsMcpConfig } from "@farming-labs/docs/server";
 
 //#region src/docs-api.ts
@@ -956,9 +956,74 @@ function resolveModelAndProvider(aiConfig, requestedModelId) {
 		apiKey
 	};
 }
-async function handleAskAI(request, indexes, aiConfig, analytics, analyticsContext = {}) {
+function safeUrlOrigin(value) {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return value;
+	}
+}
+async function handleAskAI(request, indexes, aiConfig, analytics, observability, analyticsContext = {}) {
 	const url = new URL(request.url);
 	const requestStartedAt = Date.now();
+	const trace = createDocsAgentTraceContext("ask-ai");
+	const runSpanId = createDocsAgentTraceId("span");
+	const traceBase = {
+		source: "server",
+		traceId: trace.traceId,
+		url: request.url,
+		path: url.pathname,
+		locale: analyticsContext.locale
+	};
+	async function emitTrace(event) {
+		await emitDocsAgentTraceEvent(observability, {
+			...traceBase,
+			...event
+		});
+	}
+	async function emitRunError(reason, outputPreview = {}) {
+		const endedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const elapsed = Math.max(0, Date.now() - requestStartedAt);
+		const common = {
+			name: "ask-ai",
+			startedAt: trace.startedAt,
+			endedAt,
+			durationMs: elapsed,
+			status: "error",
+			outputPreview: {
+				reason,
+				...outputPreview
+			},
+			metadata: { reason }
+		};
+		await emitTrace({
+			...common,
+			type: "error",
+			parentSpanId: runSpanId
+		});
+		await emitTrace({
+			...common,
+			type: "run.error",
+			spanId: runSpanId
+		});
+		await emitTrace({
+			...common,
+			type: "run.end",
+			spanId: runSpanId
+		});
+	}
+	await emitTrace({
+		type: "run.start",
+		name: "ask-ai",
+		spanId: runSpanId,
+		startedAt: trace.startedAt,
+		durationMs: 0,
+		status: "started",
+		inputPreview: {
+			method: request.method,
+			path: url.pathname
+		}
+	});
 	let body;
 	try {
 		body = await request.json();
@@ -974,6 +1039,7 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("invalid_json", { status: 400 });
 		return Response.json({ error: "Invalid JSON body. Expected { messages: [...] }" }, { status: 400 });
 	}
 	const messages = body.messages;
@@ -989,6 +1055,7 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("missing_messages", { status: 400 });
 		return Response.json({ error: "messages array is required and must not be empty." }, { status: 400 });
 	}
 	const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
@@ -1005,10 +1072,44 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("missing_user_message", {
+			status: 400,
+			messageCount: messages.length
+		});
 		return Response.json({ error: "At least one user message is required." }, { status: 400 });
 	}
 	const maxResults = aiConfig.maxResults ?? 5;
 	const query = lastUserMessage.content;
+	await emitTrace({
+		type: "user.input",
+		name: "ask-ai",
+		parentSpanId: runSpanId,
+		startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: 0,
+		status: "success",
+		inputPreview: {
+			messageCount: messages.length,
+			questionLength: query.length,
+			requestedModel: typeof body.model === "string" && body.model.trim().length > 0 ? body.model.trim() : void 0
+		}
+	});
+	const retrievalStartedAt = Date.now();
+	const retrievalStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+	const retrievalSpanId = createDocsAgentTraceId("span");
+	await emitTrace({
+		type: "retrieval.query",
+		name: "docs-index",
+		spanId: retrievalSpanId,
+		parentSpanId: runSpanId,
+		startedAt: retrievalStartedAtIso,
+		status: "started",
+		inputPreview: {
+			queryLength: query.length,
+			maxResults,
+			indexSize: indexes.length
+		}
+	});
 	const scored = indexes.map((doc) => {
 		const q = query.toLowerCase();
 		const titleMatch = doc.title.toLowerCase().includes(q) ? 10 : 0;
@@ -1020,12 +1121,52 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 			score: titleMatch + contentMatch
 		};
 	}).filter((d) => d.score > 0).sort((a, b) => b.score - a.score).slice(0, maxResults);
+	await emitTrace({
+		type: "retrieval.result",
+		name: "docs-index",
+		parentSpanId: retrievalSpanId,
+		startedAt: retrievalStartedAtIso,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: Math.max(0, Date.now() - retrievalStartedAt),
+		status: "success",
+		outputPreview: {
+			resultCount: scored.length,
+			urls: scored.slice(0, 5).map((doc) => doc.url)
+		},
+		metadata: {
+			maxResults,
+			indexSize: indexes.length
+		}
+	});
+	const promptStartedAt = Date.now();
+	const promptStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+	const promptSpanId = createDocsAgentTraceId("span");
 	const context = scored.map((doc) => `## ${doc.title}\nURL: ${doc.url}\n${doc.description ? `Description: ${doc.description}\n` : ""}\n${doc.content}`).join("\n\n---\n\n");
 	const systemPrompt = aiConfig.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
-	const llmMessages = [{
+	const systemMessage = {
 		role: "system",
 		content: context ? `${systemPrompt}\n\n---\n\nDocumentation context:\n\n${context}` : systemPrompt
-	}, ...messages.filter((m) => m.role !== "system")];
+	};
+	const llmMessages = [systemMessage, ...messages.filter((m) => m.role !== "system")];
+	await emitTrace({
+		type: "prompt.build",
+		name: "ask-ai.prompt",
+		spanId: promptSpanId,
+		parentSpanId: runSpanId,
+		startedAt: promptStartedAtIso,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: Math.max(0, Date.now() - promptStartedAt),
+		status: "success",
+		inputPreview: {
+			messageCount: messages.length,
+			retrievedCount: scored.length
+		},
+		outputPreview: {
+			llmMessageCount: llmMessages.length,
+			contextChars: context.length,
+			systemMessageChars: systemMessage.content.length
+		}
+	});
 	const resolved = resolveModelAndProvider(aiConfig, typeof body.model === "string" && body.model.trim().length > 0 ? body.model.trim() : void 0);
 	if (!resolved.apiKey) {
 		await emitDocsAnalyticsEvent(analytics, {
@@ -1044,6 +1185,13 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("missing_api_key", {
+			status: 500,
+			messageCount: messages.length,
+			questionLength: query.length,
+			retrievedCount: scored.length,
+			model: resolved.model
+		});
 		return Response.json({ error: `AI is enabled but no API key was found. Either set apiKey in your docs.config ai section, configure a provider, or add OPENAI_API_KEY to your .env.local file.` }, { status: 500 });
 	}
 	await emitDocsAnalyticsEvent(analytics, {
@@ -1060,20 +1208,100 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 			model: resolved.model
 		}
 	});
-	const llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
-		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			Authorization: `Bearer ${resolved.apiKey}`
-		},
-		body: JSON.stringify({
-			model: resolved.model,
+	const modelStartedAt = Date.now();
+	const modelStartedAtIso = (/* @__PURE__ */ new Date()).toISOString();
+	const modelSpanId = createDocsAgentTraceId("span");
+	const providerOrigin = safeUrlOrigin(resolved.baseUrl);
+	await emitTrace({
+		type: "model.call",
+		name: resolved.model,
+		spanId: modelSpanId,
+		parentSpanId: runSpanId,
+		startedAt: modelStartedAtIso,
+		status: "started",
+		inputPreview: {
+			messageCount: llmMessages.length,
 			stream: true,
-			messages: llmMessages
-		})
+			providerOrigin
+		},
+		metadata: { model: resolved.model }
 	});
+	let llmResponse;
+	try {
+		llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${resolved.apiKey}`
+			},
+			body: JSON.stringify({
+				model: resolved.model,
+				stream: true,
+				messages: llmMessages
+			})
+		});
+	} catch (error) {
+		const elapsed = Math.max(0, Date.now() - modelStartedAt);
+		const message = error instanceof Error ? error.message : "Unknown error";
+		await emitTrace({
+			type: "model.error",
+			name: resolved.model,
+			parentSpanId: modelSpanId,
+			startedAt: modelStartedAtIso,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: elapsed,
+			status: "error",
+			outputPreview: { message },
+			metadata: {
+				model: resolved.model,
+				providerOrigin
+			}
+		});
+		await emitDocsAnalyticsEvent(analytics, {
+			type: "api_ai_error",
+			source: "server",
+			url: request.url,
+			path: url.pathname,
+			locale: analyticsContext.locale,
+			input: { question: query },
+			properties: {
+				reason: "llm_fetch_error",
+				messageCount: messages.length,
+				questionLength: query.length,
+				retrievedCount: scored.length,
+				model: resolved.model,
+				durationMs: Math.max(0, Date.now() - requestStartedAt)
+			}
+		});
+		await emitRunError("llm_fetch_error", {
+			status: 502,
+			messageCount: messages.length,
+			questionLength: query.length,
+			retrievedCount: scored.length,
+			model: resolved.model
+		});
+		return Response.json({ error: "LLM API request failed." }, { status: 502 });
+	}
 	if (!llmResponse.ok) {
 		const errText = await llmResponse.text().catch(() => "Unknown error");
+		const elapsed = Math.max(0, Date.now() - modelStartedAt);
+		await emitTrace({
+			type: "model.error",
+			name: resolved.model,
+			parentSpanId: modelSpanId,
+			startedAt: modelStartedAtIso,
+			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			durationMs: elapsed,
+			status: "error",
+			outputPreview: {
+				status: llmResponse.status,
+				errorChars: errText.length
+			},
+			metadata: {
+				model: resolved.model,
+				providerOrigin
+			}
+		});
 		await emitDocsAnalyticsEvent(analytics, {
 			type: "api_ai_error",
 			source: "server",
@@ -1091,6 +1319,14 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 				durationMs: Math.max(0, Date.now() - requestStartedAt)
 			}
 		});
+		await emitRunError("llm_error", {
+			status: 502,
+			modelStatus: llmResponse.status,
+			messageCount: messages.length,
+			questionLength: query.length,
+			retrievedCount: scored.length,
+			model: resolved.model
+		});
 		return Response.json({ error: `LLM API error (${llmResponse.status}): ${errText}` }, { status: 502 });
 	}
 	await emitDocsAnalyticsEvent(analytics, {
@@ -1108,6 +1344,66 @@ async function handleAskAI(request, indexes, aiConfig, analytics, analyticsConte
 			durationMs: Math.max(0, Date.now() - requestStartedAt)
 		}
 	});
+	const responseEndedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const modelDurationMs = Math.max(0, Date.now() - modelStartedAt);
+	await emitTrace({
+		type: "model.response",
+		name: resolved.model,
+		parentSpanId: modelSpanId,
+		startedAt: modelStartedAtIso,
+		endedAt: responseEndedAt,
+		durationMs: modelDurationMs,
+		status: "success",
+		outputPreview: {
+			status: llmResponse.status,
+			stream: true,
+			contentType: llmResponse.headers.get("content-type") ?? void 0
+		},
+		metadata: {
+			model: resolved.model,
+			providerOrigin
+		}
+	});
+	await emitTrace({
+		type: "model.stream",
+		name: resolved.model,
+		parentSpanId: modelSpanId,
+		startedAt: modelStartedAtIso,
+		endedAt: responseEndedAt,
+		durationMs: modelDurationMs,
+		status: "success",
+		outputPreview: { stream: true },
+		metadata: { model: resolved.model }
+	});
+	const runDurationMs = Math.max(0, Date.now() - requestStartedAt);
+	await emitTrace({
+		type: "agent.final",
+		name: "ask-ai",
+		parentSpanId: runSpanId,
+		startedAt: trace.startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: runDurationMs,
+		status: "success",
+		outputPreview: {
+			stream: true,
+			retrievedCount: scored.length
+		},
+		metadata: { model: resolved.model }
+	});
+	await emitTrace({
+		type: "run.end",
+		name: "ask-ai",
+		spanId: runSpanId,
+		startedAt: trace.startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		durationMs: runDurationMs,
+		status: "success",
+		outputPreview: {
+			stream: true,
+			retrievedCount: scored.length
+		},
+		metadata: { model: resolved.model }
+	});
 	return new Response(llmResponse.body, { headers: {
 		"Content-Type": "text/event-stream",
 		"Cache-Control": "no-cache",
@@ -1188,6 +1484,7 @@ function createDocsAPI(options) {
 	const root = options?.rootDir ?? process.cwd();
 	const entry = options?.entry ?? readEntry(root);
 	const analytics = options?.analytics;
+	const observability = options?.observability;
 	const appDir = getNextAppDir(root);
 	const contentDir = options?.contentDir ?? path.join(appDir, entry);
 	const changelogConfig = resolveChangelogConfig(options?.changelog);
@@ -1586,7 +1883,7 @@ function createDocsAPI(options) {
 				return Response.json({ error: "AI is not enabled. Set `ai: { enabled: true }` in your docs.config to enable it." }, { status: 404 });
 			}
 			const ctx = resolveContextFromRequest(request);
-			return handleAskAI(request, getIndexes(ctx), aiConfig, analytics, { locale: ctx.locale });
+			return handleAskAI(request, getIndexes(ctx), aiConfig, analytics, observability, { locale: ctx.locale });
 		}
 	};
 }
@@ -1616,6 +1913,7 @@ function createDocsMCPAPI(options = {}) {
 		mcp: options.mcp ?? readMcpConfig(rootDir),
 		search: options.search,
 		analytics: options.analytics,
+		observability: options.observability,
 		defaultName: navTitle
 	});
 	return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/theme",
-  "version": "0.1.71",
+  "version": "0.1.72",
   "description": "Theme package for @farming-labs/docs — layout, provider, MDX components, and styles",
   "keywords": [
     "docs",
@@ -139,7 +139,7 @@
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4",
-    "@farming-labs/docs": "0.1.71"
+    "@farming-labs/docs": "0.1.72"
   },
   "peerDependencies": {
     "@farming-labs/docs": ">=0.0.1",