@farming-labs/svelte 0.1.71 → 0.1.73

package/dist/server.js

@@ -30,7 +30,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import matter from "gray-matter";
-import { applySidebarFolderIndexBehavior, buildDocsAgentDiscoverySpec, emitDocsAnalyticsEvent, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsSkillRequest, normalizeDocsRelated, performDocsSearch, renderDocsMarkdownDocument, renderDocsSkillDocument, stripGeneratedAgentProvenance, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSkillFormat, } from "@farming-labs/docs";
+import { applySidebarFolderIndexBehavior, buildDocsAskAIContext, buildDocsAgentDiscoverySpec, createDocsAgentTraceContext, createDocsAgentTraceId, emitDocsAgentTraceEvent, emitDocsAnalyticsEvent, formatDocsAskAIPackageHints, findDocsMarkdownPage, isDocsAgentDiscoveryRequest, isDocsSkillRequest, normalizeDocsRelated, performDocsSearch, renderDocsMarkdownDocument, renderDocsSkillDocument, stripGeneratedAgentProvenance, resolveDocsAgentMdxContent, resolvePageSidebarFolderIndexBehavior, resolveSearchRequestConfig, resolveDocsI18n, resolveDocsLlmsTxtFormat, resolveDocsLocale, resolveDocsMarkdownRequest, resolveDocsPath, resolvePageReadingTime, resolveReadingTimeOptions, resolveDocsSkillFormat, } from "@farming-labs/docs";
 import { createDocsMcpHttpHandler, resolveDocsMcpConfig, serializeDocsIconRegistry, serializeOpenDocsProviders, } from "@farming-labs/docs/server";
 import { loadDocsNavTree, loadDocsContent, flattenNavTree } from "./content.js";
 import { renderMarkdown } from "./markdown.js";
@@ -59,6 +59,14 @@ function resolveAIModelAndProvider(aiConfig, requestedModelId) {
         (typeof process !== "undefined" ? process.env?.OPENAI_API_KEY : undefined);
     return { model: modelId, baseUrl, apiKey };
 }
+function safeUrlOrigin(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return value;
+    }
+}
 function stripMarkdownText(content) {
     return content
         .replace(/^(import|export)\s.*$/gm, "")
@@ -342,6 +350,7 @@ function findPageInMap(contentMap, dirPrefix, slug) {
 export function createDocsServer(config = {}) {
     const entry = config.entry ?? "docs";
     const analytics = config.analytics;
+    const observability = config.observability;
     const contentDirBase = config.contentDir ?? entry;
     const rootDir = path.resolve(config.rootDir ?? process.cwd());
     const i18n = resolveDocsI18n(config.i18n);
@@ -539,20 +548,6 @@ export function createDocsServer(config = {}) {
         searchIndexByEntry.set(key, index);
         return index;
     }
-    function searchByQuery(query, ctx) {
-        const index = getSearchIndex(ctx);
-        return index
-            .map((page) => {
-            const titleMatch = page.title.toLowerCase().includes(query) ? 10 : 0;
-            const words = query.split(/\s+/);
-            const contentMatch = words.reduce((score, word) => {
-                return score + (page.content.toLowerCase().includes(word) ? 1 : 0);
-            }, 0);
-            return { ...page, score: titleMatch + contentMatch };
-        })
-            .filter((r) => r.score > 0)
-            .sort((a, b) => b.score - a.score);
-    }
     // ─── llms.txt content builder ────────────────────────────────
     const llmsSiteTitle = typeof config.nav === "object" &&
         typeof config.nav?.title === "string"
@@ -739,12 +734,16 @@ export function createDocsServer(config = {}) {
     function buildDefaultSystemPrompt() {
         const lines = [
             `You are a helpful documentation assistant${projectName ? ` for ${projectName}` : ""}.`,
-            "Answer questions based on the provided documentation context.",
+            "Answer only from the provided documentation context.",
+            "Prefer exact code/config snippets from the context when the question asks how to implement something.",
+            "Cite the relevant documentation URL when you use a source.",
+            "Use only URLs exactly as they appear in the context; do not invent placeholder domains.",
+            'Never use placeholder package names or imports such as "your-auth-library", "your-package", "your-sdk", "replace-me", or "example-library". If the exact package or import is not in the context, do not include an import snippet.',
             "Be concise and accurate. If the answer is not in the context, say so honestly.",
             "Use markdown formatting for code examples and links.",
         ];
         if (packageName) {
-            lines.push(`When showing import examples, always use "${packageName}" as the package name.`);
+            lines.push(`When showing import examples, use "${packageName}" as the package name and prefer exact imports copied from the documentation context.`);
         }
         if (docsUrl) {
             lines.push(`When linking to documentation pages, use "${docsUrl}" as the base URL (e.g. ${docsUrl}/docs/get-started).`);
@@ -755,6 +754,51 @@ export function createDocsServer(config = {}) {
     async function POST(event) {
         const requestUrl = new URL(event.request.url);
         const requestStartedAt = Date.now();
+        const trace = createDocsAgentTraceContext("ask-ai");
+        const runSpanId = createDocsAgentTraceId("span");
+        const traceBase = {
+            source: "server",
+            traceId: trace.traceId,
+            url: event.request.url,
+            path: requestUrl.pathname,
+        };
+        async function emitTrace(traceEvent) {
+            await emitDocsAgentTraceEvent(observability, {
+                ...traceBase,
+                ...traceEvent,
+            });
+        }
+        async function emitRunError(reason, outputPreview = {}) {
+            const endedAt = 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: event.request.method,
+                path: requestUrl.pathname,
+            },
+        });
         if (!aiConfig.enabled) {
             await emitDocsAnalyticsEvent(analytics, {
                 type: "api_ai_error",
@@ -763,6 +807,7 @@ export function createDocsServer(config = {}) {
                 path: requestUrl.pathname,
                 properties: { reason: "disabled" },
             });
+            await emitRunError("disabled", { status: 404 });
             return new Response(JSON.stringify({
                 error: "AI is not enabled. Set `ai: { enabled: true }` in your docs config to enable it.",
             }), { status: 404, headers: { "Content-Type": "application/json" } });
@@ -781,6 +826,7 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("missing_api_key", { status: 500 });
             return new Response(JSON.stringify({
                 error: "AI is enabled but no API key was found. Set `apiKey` in your docs config `ai` section or add OPENAI_API_KEY to your environment.",
             }), { status: 500, headers: { "Content-Type": "application/json" } });
@@ -802,6 +848,7 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("invalid_json", { status: 400, locale: ctx.locale });
             return new Response(JSON.stringify({ error: "Invalid JSON body. Expected { messages: [...] }" }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
         const messages = body.messages;
@@ -817,6 +864,7 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("missing_messages", { status: 400, locale: ctx.locale });
             return new Response(JSON.stringify({ error: "messages array is required and must not be empty." }), { status: 400, headers: { "Content-Type": "application/json" } });
         }
         const lastUserMessage = [...messages].reverse().find((m) => m.role === "user");
@@ -833,26 +881,113 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("missing_user_message", {
+                status: 400,
+                locale: ctx.locale,
+                messageCount: messages.length,
+            });
             return new Response(JSON.stringify({ error: "At least one user message is required." }), {
                 status: 400,
                 headers: { "Content-Type": "application/json" },
             });
         }
         const maxResults = aiConfig.maxResults ?? 5;
-        const scored = searchByQuery(lastUserMessage.content.toLowerCase(), ctx).slice(0, maxResults);
-        const contextParts = scored.map((doc) => `## ${doc.title}\nURL: ${doc.url}\n${doc.description ? `Description: ${doc.description}\n` : ""}\n${doc.content}`);
-        const context = contextParts.join("\n\n---\n\n");
+        await emitTrace({
+            type: "user.input",
+            name: "ask-ai",
+            parentSpanId: runSpanId,
+            startedAt: new Date().toISOString(),
+            endedAt: new Date().toISOString(),
+            durationMs: 0,
+            status: "success",
+            locale: ctx.locale,
+            inputPreview: {
+                messageCount: messages.length,
+                questionLength: lastUserMessage.content.length,
+                requestedModel: typeof body.model === "string" && body.model.trim().length > 0
+                    ? body.model.trim()
+                    : undefined,
+            },
+        });
+        const retrievalStartedAt = Date.now();
+        const retrievalStartedAtIso = new Date().toISOString();
+        const retrievalSpanId = createDocsAgentTraceId("span");
+        await emitTrace({
+            type: "retrieval.query",
+            name: "docs-index",
+            spanId: retrievalSpanId,
+            parentSpanId: runSpanId,
+            startedAt: retrievalStartedAtIso,
+            status: "started",
+            locale: ctx.locale,
+            inputPreview: {
+                queryLength: lastUserMessage.content.length,
+                maxResults,
+            },
+        });
+        const retrieval = await buildDocsAskAIContext({
+            pages: getSearchIndex(ctx),
+            query: lastUserMessage.content,
+            search: resolveSearchRequestConfig(config.search, event.request.url),
+            locale: ctx.locale,
+            pathname: requestUrl.searchParams.get("pathname") ?? undefined,
+            siteTitle: llmsTitle,
+            baseUrl: requestUrl.origin,
+            limit: maxResults,
+        });
+        const scored = retrieval.results;
+        await emitTrace({
+            type: "retrieval.result",
+            name: "docs-index",
+            parentSpanId: retrievalSpanId,
+            startedAt: retrievalStartedAtIso,
+            endedAt: new Date().toISOString(),
+            durationMs: Math.max(0, Date.now() - retrievalStartedAt),
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                resultCount: scored.length,
+                urls: scored.slice(0, 5).map((doc) => doc.url),
+            },
+            metadata: { maxResults },
+        });
+        const promptStartedAt = Date.now();
+        const promptStartedAtIso = new Date().toISOString();
+        const promptSpanId = createDocsAgentTraceId("span");
+        const context = retrieval.context;
         const systemPrompt = aiConfig.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+        const packageHintsPrompt = formatDocsAskAIPackageHints(retrieval.packageHints, packageName);
+        const fullSystemPrompt = [systemPrompt, packageHintsPrompt].filter(Boolean).join("\n\n");
         const systemMessage = {
             role: "system",
             content: context
-                ? `${systemPrompt}\n\n---\n\nDocumentation context:\n\n${context}`
-                : systemPrompt,
+                ? `${fullSystemPrompt}\n\n---\n\nDocumentation context:\n\n${context}`
+                : fullSystemPrompt,
         };
         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: new Date().toISOString(),
+            durationMs: Math.max(0, Date.now() - promptStartedAt),
+            status: "success",
+            locale: ctx.locale,
+            inputPreview: {
+                messageCount: messages.length,
+                retrievedCount: scored.length,
+            },
+            outputPreview: {
+                llmMessageCount: llmMessages.length,
+                contextChars: context.length,
+                systemMessageChars: systemMessage.content.length,
+            },
+        });
         const requestedModel = typeof body.model === "string" && body.model.trim().length > 0
             ? body.model.trim()
             : undefined;
@@ -872,16 +1007,96 @@ export function createDocsServer(config = {}) {
                 model: resolved.model,
             },
         });
-        const llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json",
-                Authorization: `Bearer ${finalKey}`,
+        const modelStartedAt = Date.now();
+        const modelStartedAtIso = 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",
+            locale: ctx.locale,
+            inputPreview: {
+                messageCount: llmMessages.length,
+                stream: true,
+                providerOrigin,
             },
-            body: JSON.stringify({ model: resolved.model, stream: true, messages: llmMessages }),
+            metadata: { model: resolved.model },
         });
+        let llmResponse;
+        try {
+            llmResponse = await fetch(`${resolved.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${finalKey}`,
+                },
+                body: JSON.stringify({ model: resolved.model, stream: true, messages: llmMessages }),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            await emitTrace({
+                type: "model.error",
+                name: resolved.model,
+                parentSpanId: modelSpanId,
+                startedAt: modelStartedAtIso,
+                endedAt: new Date().toISOString(),
+                durationMs: Math.max(0, Date.now() - modelStartedAt),
+                status: "error",
+                locale: ctx.locale,
+                outputPreview: { message },
+                metadata: { model: resolved.model, providerOrigin },
+            });
+            await emitDocsAnalyticsEvent(analytics, {
+                type: "api_ai_error",
+                source: "server",
+                url: event.request.url,
+                path: requestUrl.pathname,
+                locale: ctx.locale,
+                input: { question: lastUserMessage.content },
+                properties: {
+                    reason: "llm_fetch_error",
+                    messageCount: messages.length,
+                    questionLength: lastUserMessage.content.length,
+                    retrievedCount: scored.length,
+                    model: resolved.model,
+                    durationMs: Math.max(0, Date.now() - requestStartedAt),
+                },
+            });
+            await emitRunError("llm_fetch_error", {
+                status: 502,
+                locale: ctx.locale,
+                messageCount: messages.length,
+                questionLength: lastUserMessage.content.length,
+                retrievedCount: scored.length,
+                model: resolved.model,
+            });
+            return new Response(JSON.stringify({ error: "LLM API request failed." }), {
+                status: 502,
+                headers: { "Content-Type": "application/json" },
+            });
+        }
         if (!llmResponse.ok) {
             const errText = await llmResponse.text().catch(() => "Unknown error");
+            await emitTrace({
+                type: "model.error",
+                name: resolved.model,
+                parentSpanId: modelSpanId,
+                startedAt: modelStartedAtIso,
+                endedAt: new Date().toISOString(),
+                durationMs: Math.max(0, Date.now() - modelStartedAt),
+                status: "error",
+                locale: ctx.locale,
+                outputPreview: {
+                    status: llmResponse.status,
+                    errorChars: errText.length,
+                },
+                metadata: { model: resolved.model, providerOrigin },
+            });
             await emitDocsAnalyticsEvent(analytics, {
                 type: "api_ai_error",
                 source: "server",
@@ -899,6 +1114,15 @@ export function createDocsServer(config = {}) {
                     durationMs: Math.max(0, Date.now() - requestStartedAt),
                 },
             });
+            await emitRunError("llm_error", {
+                status: 502,
+                modelStatus: llmResponse.status,
+                locale: ctx.locale,
+                messageCount: messages.length,
+                questionLength: lastUserMessage.content.length,
+                retrievedCount: scored.length,
+                model: resolved.model,
+            });
             return new Response(JSON.stringify({ error: `LLM API error (${llmResponse.status}): ${errText}` }), { status: 502, headers: { "Content-Type": "application/json" } });
         }
         await emitDocsAnalyticsEvent(analytics, {
@@ -916,6 +1140,67 @@ export function createDocsServer(config = {}) {
                 durationMs: Math.max(0, Date.now() - requestStartedAt),
             },
         });
+        const responseEndedAt = 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",
+            locale: ctx.locale,
+            outputPreview: {
+                status: llmResponse.status,
+                stream: true,
+                contentType: llmResponse.headers.get("content-type") ?? undefined,
+            },
+            metadata: { model: resolved.model, providerOrigin },
+        });
+        await emitTrace({
+            type: "model.stream",
+            name: resolved.model,
+            parentSpanId: modelSpanId,
+            startedAt: modelStartedAtIso,
+            endedAt: responseEndedAt,
+            durationMs: modelDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            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: new Date().toISOString(),
+            durationMs: runDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                stream: true,
+                retrievedCount: scored.length,
+            },
+            metadata: { model: resolved.model },
+        });
+        await emitTrace({
+            type: "run.end",
+            name: "ask-ai",
+            spanId: runSpanId,
+            startedAt: trace.startedAt,
+            endedAt: new Date().toISOString(),
+            durationMs: runDurationMs,
+            status: "success",
+            locale: ctx.locale,
+            outputPreview: {
+                stream: true,
+                retrievedCount: scored.length,
+            },
+            metadata: { model: resolved.model },
+        });
         return new Response(llmResponse.body, {
             headers: {
                 "Content-Type": "text/event-stream",
@@ -947,6 +1232,7 @@ export function createDocsServer(config = {}) {
         },
         mcp: config.mcp,
         analytics,
+        observability,
         defaultName: mcpSiteTitle,
     });
     return { load, GET, POST, MCP };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farming-labs/svelte",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "description": "SvelteKit adapter for @farming-labs/docs — content loading and navigation utilities",
   "keywords": [
     "docs",
@@ -56,7 +56,7 @@
   "devDependencies": {
     "@types/node": "^22.10.0",
     "typescript": "^5.9.3",
-    "@farming-labs/docs": "0.1.71"
+    "@farming-labs/docs": "0.1.73"
   },
   "peerDependencies": {
     "@farming-labs/docs": "*"