sagedesk 1.0.0 → 2.0.0

package/dist/server/index.cjs

@@ -0,0 +1,348 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  createSageDeskHandler: () => createSageDeskHandler,
+  createSageDeskMiddleware: () => createSageDeskMiddleware
+});
+module.exports = __toCommonJS(server_exports);
+var import_fs = require("fs");
+
+// src/core/embedder.ts
+var XENOVA_IDS = {
+  "all-MiniLM-L6-v2": "Xenova/all-MiniLM-L6-v2",
+  "bge-small-en-v1-5": "Xenova/bge-small-en-v1.5",
+  "paraphrase-multilingual-MiniLM-L12-v2": "Xenova/paraphrase-multilingual-MiniLM-L12-v2",
+  "all-mpnet-base-v2": "Xenova/all-mpnet-base-v2"
+};
+var EmbedderRuntime = class _EmbedderRuntime {
+  constructor() {
+    this._ready = false;
+    this._failed = false;
+  }
+  static {
+    // Module-level singleton so the WASM model is loaded at most once per page,
+    // regardless of how many widget instances exist.
+    this._pipelineInstance = null;
+  }
+  static {
+    this._loadingPromise = null;
+  }
+  async load(model = "all-MiniLM-L6-v2") {
+    if (this._ready) return;
+    if (this._failed) throw new Error("EmbedderRuntime previously failed to load");
+    if (_EmbedderRuntime._loadingPromise) {
+      await _EmbedderRuntime._loadingPromise;
+      this._ready = true;
+      return;
+    }
+    const modelId = XENOVA_IDS[model];
+    _EmbedderRuntime._loadingPromise = (async () => {
+      try {
+        const { pipeline } = await import("@huggingface/transformers");
+        _EmbedderRuntime._pipelineInstance = await pipeline(
+          "feature-extraction",
+          modelId,
+          { dtype: "q8" }
+        );
+      } catch (err) {
+        _EmbedderRuntime._loadingPromise = null;
+        _EmbedderRuntime._pipelineInstance = null;
+        throw err;
+      }
+    })();
+    try {
+      await _EmbedderRuntime._loadingPromise;
+      this._ready = true;
+    } catch (err) {
+      this._failed = true;
+      throw err;
+    }
+  }
+  async embed(text) {
+    if (!_EmbedderRuntime._pipelineInstance) {
+      await this.load();
+    }
+    try {
+      const output = await _EmbedderRuntime._pipelineInstance(text, {
+        pooling: "mean",
+        normalize: true
+      });
+      return output.data;
+    } catch (err) {
+      throw new Error(`Embedding failed: ${String(err)}`);
+    }
+  }
+  get isReady() {
+    return this._ready;
+  }
+  get hasFailed() {
+    return this._failed;
+  }
+  /** @internal */
+  static _reset() {
+    _EmbedderRuntime._pipelineInstance = null;
+    _EmbedderRuntime._loadingPromise = null;
+  }
+};
+
+// src/core/search.ts
+function dotProduct(a, b) {
+  if (a.length !== b.length) {
+    throw new Error(`Vector dimension mismatch: query(${a.length}) vs index(${b.length})`);
+  }
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];
+  return dot;
+}
+function search(queryVector, index, topK = 3, minScore = 0.42) {
+  const results = [];
+  for (const chunk of index) {
+    const score = dotProduct(queryVector, chunk.vector384);
+    if (score < minScore) continue;
+    if (results.length < topK) {
+      results.push({ chunk, score });
+      results.sort((a, b) => b.score - a.score);
+    } else if (score > results[topK - 1].score) {
+      results[topK - 1] = { chunk, score };
+      results.sort((a, b) => b.score - a.score);
+    }
+  }
+  return results;
+}
+
+// src/core/renderer.ts
+function buildAnswer(results) {
+  if (results.length === 0) return "";
+  const seen = /* @__PURE__ */ new Set();
+  const parts = [];
+  for (const r of results) {
+    if (!seen.has(r.chunk.sourceId)) {
+      seen.add(r.chunk.sourceId);
+      parts.push(r.chunk.text);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+// src/server/index.ts
+var PROVIDER_URLS = {
+  openai: "https://api.openai.com/v1/chat/completions",
+  deepseek: "https://api.deepseek.com/chat/completions",
+  groq: "https://api.groq.com/openai/v1/chat/completions",
+  gemini: "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
+  anthropic: "https://api.anthropic.com/v1/messages"
+};
+var DEFAULT_SYSTEM_PROMPT = "You are a helpful support assistant. Answer the user's question based ONLY on the provided context. If the context does not contain a confident answer, respond with a friendly message saying you don't have that information right now. Do not make up information or draw from outside knowledge. Be concise, warm, and helpful.";
+var indexCache = /* @__PURE__ */ new Map();
+var embedderCache = /* @__PURE__ */ new Map();
+function loadIndexFile(indexPath) {
+  if (indexCache.has(indexPath)) return indexCache.get(indexPath);
+  const raw = (0, import_fs.readFileSync)(indexPath, "utf-8");
+  const data = JSON.parse(raw);
+  const chunks = Array.isArray(data) ? data : data.chunks;
+  for (const chunk of chunks) {
+    chunk.textLower = chunk.text.toLowerCase();
+    if (Array.isArray(chunk.vector384)) {
+      chunk.vector384 = new Float32Array(chunk.vector384);
+    }
+  }
+  indexCache.set(indexPath, chunks);
+  return chunks;
+}
+async function getEmbedder(model = "all-MiniLM-L6-v2") {
+  if (embedderCache.has(model)) return embedderCache.get(model);
+  const embedder = new EmbedderRuntime();
+  await embedder.load(model);
+  embedderCache.set(model, embedder);
+  return embedder;
+}
+function classifyError(error) {
+  const msg = String(error).toLowerCase();
+  if (msg.includes("401") || msg.includes("403") || msg.includes("unauthorized") || msg.includes("invalid api key")) {
+    return "auth-error";
+  }
+  if (msg.includes("429") || msg.includes("quota") || msg.includes("rate limit")) {
+    return "quota-exceeded";
+  }
+  if (msg.includes("timeout") || msg.includes("aborted")) {
+    return "timeout";
+  }
+  if (msg.includes("malformed") || msg.includes("json")) {
+    return "malformed-response";
+  }
+  return "api-error";
+}
+async function callLLM(provider, apiKey, model, systemPrompt, query, context, timeoutMs = 5e3) {
+  const url = PROVIDER_URLS[provider] ?? provider;
+  const controller = new AbortController();
+  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    if (provider === "anthropic") {
+      const res2 = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: 512,
+          system: systemPrompt,
+          messages: [{ role: "user", content: `Context:
+${context}
+
+Question: ${query}` }]
+        }),
+        signal: controller.signal
+      });
+      if (!res2.ok) {
+        const error = classifyError(`${res2.status}`);
+        return { answer: "", error };
+      }
+      const data2 = await res2.json();
+      const answer2 = data2.content?.[0]?.text?.trim() ?? "";
+      return { answer: answer2 };
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: "system", content: systemPrompt },
+          {
+            role: "user",
+            content: `Context:
+${context}
+
+Question: ${query}`
+          }
+        ],
+        temperature: 0.3,
+        max_tokens: 512
+      }),
+      signal: controller.signal
+    });
+    if (!res.ok) {
+      const error = classifyError(`${res.status}`);
+      return { answer: "", error };
+    }
+    const data = await res.json();
+    const answer = data.choices?.[0]?.message?.content?.trim() ?? "";
+    return { answer };
+  } catch (err) {
+    const error = classifyError(err);
+    return { answer: "", error };
+  } finally {
+    clearTimeout(timeoutHandle);
+  }
+}
+async function handleQuery(query, config) {
+  const {
+    indexPath,
+    provider,
+    apiKey,
+    model,
+    embeddingModel,
+    topK = 5,
+    minScore = 0.42,
+    systemPrompt = DEFAULT_SYSTEM_PROMPT,
+    llmTimeoutMs = 5e3
+  } = config;
+  const index = loadIndexFile(indexPath);
+  const embedder = await getEmbedder(embeddingModel);
+  const queryVector = await embedder.embed(query);
+  const results = search(queryVector, index, topK, minScore);
+  if (results.length === 0) {
+    return { answer: "", isFallback: true };
+  }
+  const context = buildAnswer(results);
+  const llmResult = await callLLM(
+    provider,
+    apiKey,
+    model,
+    systemPrompt,
+    query,
+    context,
+    llmTimeoutMs
+  );
+  if (!llmResult.answer) {
+    return {
+      answer: "",
+      isFallback: true,
+      fallbackReason: llmResult.error
+    };
+  }
+  return { answer: llmResult.answer, isFallback: false };
+}
+function createSageDeskHandler(config) {
+  return async function POST(request) {
+    try {
+      const body = await request.json();
+      const query = body.query?.trim();
+      if (!query) {
+        return Response.json({ error: "Missing query" }, { status: 400 });
+      }
+      const result = await handleQuery(query, config);
+      return Response.json(result);
+    } catch (err) {
+      console.error("[sagedesk/server] Handler error:", err);
+      return Response.json({ answer: "", isFallback: true }, { status: 500 });
+    }
+  };
+}
+function createSageDeskMiddleware(config) {
+  return async function sageDeskMiddleware(req, res, next) {
+    try {
+      const query = req.body?.query?.trim();
+      if (!query) {
+        res.status(400).json({ error: "Missing query" });
+        return;
+      }
+      const result = await handleQuery(query, config);
+      res.json(result);
+    } catch (err) {
+      console.error("[sagedesk/server] Middleware error:", err);
+      next(err);
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createSageDeskHandler,
+  createSageDeskMiddleware
+});
+//# sourceMappingURL=index.cjs.map

package/dist/server/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/server/index.ts","../../src/core/embedder.ts","../../src/core/search.ts","../../src/core/renderer.ts"],"sourcesContent":["import { readFileSync } from 'fs';\nimport { EmbedderRuntime } from '../core/embedder.js';\nimport { search } from '../core/search.js';\nimport { buildAnswer } from '../core/renderer.js';\nimport type { IndexChunk, IndexFile, SageDeskModel, FallbackReason } from '../core/types.js';\n\n// ─── Types ────────────────────────────────────────────────────────────────────\n\nexport interface SageDeskHandlerConfig {\n  /** Filesystem path to the pre-built vector index (e.g. \"./public/support-index.json\"). */\n  indexPath: string;\n  /** LLM provider: 'openai', 'deepseek', 'groq', 'gemini', 'anthropic', or any OpenAI-compatible base URL. */\n  provider: string;\n  /** API key for the LLM provider. Never sent to the browser. */\n  apiKey: string;\n  /** LLM model name (e.g. 'deepseek-chat', 'gpt-4o-mini', 'llama3-8b-8192'). */\n  model: string;\n  /** Embedding model - must match the model used at build time. Defaults to all-MiniLM-L6-v2. */\n  embeddingModel?: SageDeskModel;\n  /** Number of chunks to retrieve for context. Defaults to 5. */\n  topK?: number;\n  /** Minimum similarity score for a chunk to be included. Defaults to 0.42. */\n  minScore?: number;\n  /** Override the system prompt sent to the LLM. */\n  systemPrompt?: string;\n  /** Timeout for LLM API calls in milliseconds. Defaults to 5000 (5 seconds). */\n  llmTimeoutMs?: number;\n}\n\n// ─── Provider URL map ─────────────────────────────────────────────────────────\n\nconst PROVIDER_URLS: Record<string, string> = {\n  openai: 'https://api.openai.com/v1/chat/completions',\n  deepseek: 'https://api.deepseek.com/chat/completions',\n  groq: 'https://api.groq.com/openai/v1/chat/completions',\n  gemini: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',\n  anthropic: 'https://api.anthropic.com/v1/messages',\n};\n\n// ─── Default system prompt ────────────────────────────────────────────────────\n\nconst DEFAULT_SYSTEM_PROMPT =\n  'You are a helpful support assistant. Answer the user\\'s question based ONLY on the ' +\n  'provided context. If the context does not contain a confident answer, respond with a ' +\n  'friendly message saying you don\\'t have that information right now. Do not make up ' +\n  'information or draw from outside knowledge. Be concise, warm, and helpful.';\n\n// ─── Server-side caches (module-level singletons) ─────────────────────────────\n\nconst indexCache = new Map<string, IndexChunk[]>();\nconst embedderCache = new Map<string, EmbedderRuntime>();\n\nfunction loadIndexFile(indexPath: string): IndexChunk[] {\n  if (indexCache.has(indexPath)) return indexCache.get(indexPath)!;\n\n  const raw = readFileSync(indexPath, 'utf-8');\n  const data = JSON.parse(raw) as IndexFile | IndexChunk[];\n  const chunks: IndexChunk[] = Array.isArray(data) ? data : data.chunks;\n\n  for (const chunk of chunks) {\n    chunk.textLower = chunk.text.toLowerCase();\n    if (Array.isArray(chunk.vector384)) {\n      chunk.vector384 = new Float32Array(chunk.vector384);\n    }\n  }\n\n  indexCache.set(indexPath, chunks);\n  return chunks;\n}\n\nasync function getEmbedder(model: SageDeskModel = 'all-MiniLM-L6-v2'): Promise<EmbedderRuntime> {\n  if (embedderCache.has(model)) return embedderCache.get(model)!;\n\n  const embedder = new EmbedderRuntime();\n  await embedder.load(model);\n  embedderCache.set(model, embedder);\n  return embedder;\n}\n\n// ─── Helper: Classify error for client-side logging ───────────────────────────\n\nfunction classifyError(error: unknown): FallbackReason {\n  const msg = String(error).toLowerCase();\n\n  if (msg.includes('401') || msg.includes('403') || msg.includes('unauthorized') || msg.includes('invalid api key')) {\n    return 'auth-error';\n  }\n  if (msg.includes('429') || msg.includes('quota') || msg.includes('rate limit')) {\n    return 'quota-exceeded';\n  }\n  if (msg.includes('timeout') || msg.includes('aborted')) {\n    return 'timeout';\n  }\n  if (msg.includes('malformed') || msg.includes('json')) {\n    return 'malformed-response';\n  }\n\n  return 'api-error';\n}\n\n// ─── LLM call ─────────────────────────────────────────────────────────────────\n\nasync function callLLM(\n  provider: string,\n  apiKey: string,\n  model: string,\n  systemPrompt: string,\n  query: string,\n  context: string,\n  timeoutMs: number = 5000\n): Promise<{ answer: string; error?: FallbackReason }> {\n  const url = PROVIDER_URLS[provider] ?? provider;\n  const controller = new AbortController();\n  const timeoutHandle = setTimeout(() => controller.abort(), timeoutMs);\n\n  try {\n    if (provider === 'anthropic') {\n      const res = await fetch(url, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'x-api-key': apiKey,\n          'anthropic-version': '2023-06-01',\n        },\n        body: JSON.stringify({\n          model,\n          max_tokens: 512,\n          system: systemPrompt,\n          messages: [{ role: 'user', content: `Context:\\n${context}\\n\\nQuestion: ${query}` }],\n        }),\n        signal: controller.signal,\n      });\n\n      if (!res.ok) {\n        const error = classifyError(`${res.status}`);\n        return { answer: '', error };\n      }\n\n      const data = (await res.json()) as { content: Array<{ type: string; text: string }> };\n      const answer = data.content?.[0]?.text?.trim() ?? '';\n      return { answer };\n    }\n\n    const res = await fetch(url, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        Authorization: `Bearer ${apiKey}`,\n      },\n      body: JSON.stringify({\n        model,\n        messages: [\n          { role: 'system', content: systemPrompt },\n          {\n            role: 'user',\n            content: `Context:\\n${context}\\n\\nQuestion: ${query}`,\n          },\n        ],\n        temperature: 0.3,\n        max_tokens: 512,\n      }),\n      signal: controller.signal,\n    });\n\n    if (!res.ok) {\n      const error = classifyError(`${res.status}`);\n      return { answer: '', error };\n    }\n\n    const data = (await res.json()) as {\n      choices: Array<{ message: { content: string } }>;\n    };\n    const answer = data.choices?.[0]?.message?.content?.trim() ?? '';\n    return { answer };\n  } catch (err) {\n    const error = classifyError(err);\n    return { answer: '', error };\n  } finally {\n    clearTimeout(timeoutHandle);\n  }\n}\n\n// ─── Core handler logic ───────────────────────────────────────────────────────\n\nasync function handleQuery(\n  query: string,\n  config: SageDeskHandlerConfig\n): Promise<{ answer: string; isFallback: boolean; fallbackReason?: FallbackReason }> {\n  const {\n    indexPath,\n    provider,\n    apiKey,\n    model,\n    embeddingModel,\n    topK = 5,\n    minScore = 0.42,\n    systemPrompt = DEFAULT_SYSTEM_PROMPT,\n    llmTimeoutMs = 5000,\n  } = config;\n\n  const index = loadIndexFile(indexPath);\n  const embedder = await getEmbedder(embeddingModel);\n\n  const queryVector = await embedder.embed(query);\n  const results = search(queryVector, index, topK, minScore);\n\n  if (results.length === 0) {\n    return { answer: '', isFallback: true };\n  }\n\n  const context = buildAnswer(results);\n  const llmResult = await callLLM(\n    provider,\n    apiKey,\n    model,\n    systemPrompt,\n    query,\n    context,\n    llmTimeoutMs\n  );\n\n  if (!llmResult.answer) {\n    return {\n      answer: '',\n      isFallback: true,\n      fallbackReason: llmResult.error,\n    };\n  }\n\n  return { answer: llmResult.answer, isFallback: false };\n}\n\n// ─── Next.js App Router handler ───────────────────────────────────────────────\n\n/**\n * Returns a Next.js App Router POST handler.\n *\n * @example\n * // app/api/sagedesk/route.ts\n * import { createSageDeskHandler } from 'sagedesk/server'\n * export const POST = createSageDeskHandler({\n *   indexPath: './public/support-index.json',\n *   provider: 'deepseek',\n *   apiKey: process.env.SAGEDESK_LLM_API_KEY!,\n *   model: 'deepseek-chat',\n * })\n */\nexport function createSageDeskHandler(config: SageDeskHandlerConfig) {\n  return async function POST(request: Request): Promise<Response> {\n    try {\n      const body = (await request.json()) as { query?: string };\n      const query = body.query?.trim();\n\n      if (!query) {\n        return Response.json({ error: 'Missing query' }, { status: 400 });\n      }\n\n      const result = await handleQuery(query, config);\n      return Response.json(result);\n    } catch (err) {\n      console.error('[sagedesk/server] Handler error:', err);\n      return Response.json({ answer: '', isFallback: true }, { status: 500 });\n    }\n  };\n}\n\n// ─── Express / Connect middleware ─────────────────────────────────────────────\n\ntype ExpressRequest = {\n  body: { query?: string };\n};\ntype ExpressResponse = {\n  status: (code: number) => ExpressResponse;\n  json: (data: unknown) => void;\n};\ntype NextFunction = (err?: unknown) => void;\n\n/**\n * Returns an Express (or any Connect-compatible) middleware.\n *\n * @example\n * // server.ts / index.ts\n * import { createSageDeskMiddleware } from 'sagedesk/server'\n * app.use('/api/sagedesk', express.json(), createSageDeskMiddleware({\n *   indexPath: './public/support-index.json',\n *   provider: 'openai',\n *   apiKey: process.env.SAGEDESK_LLM_API_KEY!,\n *   model: 'gpt-4o-mini',\n * }))\n */\nexport function createSageDeskMiddleware(config: SageDeskHandlerConfig) {\n  return async function sageDeskMiddleware(\n    req: ExpressRequest,\n    res: ExpressResponse,\n    next: NextFunction\n  ): Promise<void> {\n    try {\n      const query = req.body?.query?.trim();\n\n      if (!query) {\n        res.status(400).json({ error: 'Missing query' });\n        return;\n      }\n\n      const result = await handleQuery(query, config);\n      res.json(result);\n    } catch (err) {\n      console.error('[sagedesk/server] Middleware error:', err);\n      next(err);\n    }\n  };\n}\n","import type { SageDeskModel } from './types';\n\ntype PipelineFn = (\n  text: string,\n  options: { pooling: string; normalize: boolean }\n) => Promise<{ data: Float32Array }>;\n\n// Maps each supported model alias to its full Xenova/HuggingFace model ID.\nconst XENOVA_IDS: Record<SageDeskModel, string> = {\n  'all-MiniLM-L6-v2': 'Xenova/all-MiniLM-L6-v2',\n  'bge-small-en-v1-5': 'Xenova/bge-small-en-v1.5',\n  'paraphrase-multilingual-MiniLM-L12-v2': 'Xenova/paraphrase-multilingual-MiniLM-L12-v2',\n  'all-mpnet-base-v2': 'Xenova/all-mpnet-base-v2',\n};\n\nexport class EmbedderRuntime {\n  private _ready = false;\n  private _failed = false;\n\n  // Module-level singleton so the WASM model is loaded at most once per page,\n  // regardless of how many widget instances exist.\n  private static _pipelineInstance: PipelineFn | null = null;\n  private static _loadingPromise: Promise<void> | null = null;\n\n  async load(model: SageDeskModel = 'all-MiniLM-L6-v2'): Promise<void> {\n    if (this._ready) return;\n    if (this._failed) throw new Error('EmbedderRuntime previously failed to load');\n\n    if (EmbedderRuntime._loadingPromise) {\n      await EmbedderRuntime._loadingPromise;\n      this._ready = true;\n      return;\n    }\n\n    const modelId = XENOVA_IDS[model];\n\n    EmbedderRuntime._loadingPromise = (async () => {\n      try {\n        const { pipeline } = await import('@huggingface/transformers');\n        EmbedderRuntime._pipelineInstance = (await pipeline(\n          'feature-extraction',\n          modelId,\n          { dtype: 'q8' }\n        )) as unknown as PipelineFn;\n      } catch (err) {\n        EmbedderRuntime._loadingPromise = null;\n        EmbedderRuntime._pipelineInstance = null;\n        throw err;\n      }\n    })();\n\n    try {\n      await EmbedderRuntime._loadingPromise;\n      this._ready = true;\n    } catch (err) {\n      this._failed = true;\n      throw err;\n    }\n  }\n\n  async embed(text: string): Promise<Float32Array> {\n    if (!EmbedderRuntime._pipelineInstance) {\n      await this.load();\n    }\n\n    try {\n      const output = await EmbedderRuntime._pipelineInstance!(text, {\n        pooling: 'mean',\n        normalize: true,\n      });\n      return output.data;\n    } catch (err) {\n      throw new Error(`Embedding failed: ${String(err)}`);\n    }\n  }\n\n  get isReady(): boolean {\n    return this._ready;\n  }\n\n  get hasFailed(): boolean {\n    return this._failed;\n  }\n\n  /** @internal */\n  static _reset(): void {\n    EmbedderRuntime._pipelineInstance = null;\n    EmbedderRuntime._loadingPromise = null;\n  }\n}\n","import type { IndexChunk, SearchResult } from './types';\n\n// Both the query vector (embedder.ts, normalize:true) and stored vectors\n// (builder-embedder.ts, normalize:true) are guaranteed unit-length, so\n// cosine similarity reduces to a plain dot product - no norms needed.\nfunction dotProduct(a: Float32Array, b: Float32Array): number {\n  if (a.length !== b.length) {\n    throw new Error(`Vector dimension mismatch: query(${a.length}) vs index(${b.length})`);\n  }\n  let dot = 0;\n  for (let i = 0; i < a.length; i++) dot += a[i] * b[i];\n  return dot;\n}\n\nexport function search(\n  queryVector: Float32Array,\n  index: IndexChunk[],\n  topK = 3,\n  minScore = 0.42\n): SearchResult[] {\n  // Use a simple selection sort approach for small topK, \n  // or a full sort if index is small. For very large indexes, \n  // a proper Heap would be better, but O(N * topK) is already better than O(N log N).\n  const results: SearchResult[] = [];\n\n  for (const chunk of index) {\n    const score = dotProduct(queryVector, chunk.vector384 as Float32Array);\n    if (score < minScore) continue;\n\n    if (results.length < topK) {\n      results.push({ chunk, score });\n      results.sort((a, b) => b.score - a.score);\n    } else if (score > results[topK - 1].score) {\n      results[topK - 1] = { chunk, score };\n      results.sort((a, b) => b.score - a.score);\n    }\n  }\n\n  return results;\n}\n\nexport function keywordSearch(\n  query: string,\n  index: IndexChunk[],\n  topK = 3\n): SearchResult[] {\n  const terms = query\n    .toLowerCase()\n    .split(/\\s+/)\n    .filter((w) => w.length > 2)\n    .map((w) => w.replace(/[^a-z0-9]/g, ''));\n\n  if (terms.length === 0) return [];\n\n  const results: SearchResult[] = [];\n\n  for (const chunk of index) {\n    const chunkLower = chunk.textLower || chunk.text.toLowerCase();\n    const matchCount = terms.filter((t) => chunkLower.includes(t)).length;\n    const score = matchCount / terms.length;\n\n    if (score <= 0) continue;\n\n    if (results.length < topK) {\n      results.push({ chunk, score });\n      results.sort((a, b) => b.score - a.score);\n    } else if (score > results[topK - 1].score) {\n      results[topK - 1] = { chunk, score };\n      results.sort((a, b) => b.score - a.score);\n    }\n  }\n\n  return results;\n}\n\nexport async function loadIndex(url: string): Promise<IndexChunk[]> {\n  const res = await fetch(url);\n  if (!res.ok) {\n    throw new Error(`Failed to fetch index (HTTP ${res.status}): ${url}`);\n  }\n  const data = await res.json();\n  // Support both the new { meta, chunks } format and the legacy bare-array format.\n  const chunks: IndexChunk[] = Array.isArray(data)\n    ? data\n    : (data as { chunks: IndexChunk[] }).chunks;\n\n  // Materialize lowercase versions and convert vectors to Float32Array once at load time.\n  for (const chunk of chunks) {\n    chunk.textLower = chunk.text.toLowerCase();\n    if (Array.isArray(chunk.vector384)) {\n      chunk.vector384 = new Float32Array(chunk.vector384);\n    }\n    if (Array.isArray(chunk.vector768)) {\n      chunk.vector768 = new Float32Array(chunk.vector768);\n    }\n  }\n\n  return chunks;\n}\n","import type { SearchResult } from './types';\n\nexport function buildAnswer(results: SearchResult[]): string {\n  if (results.length === 0) return '';\n  // Deduplicate by sourceId: query expansion produces multiple chunks per\n  // source entry (same answer, different query phrasings) - show each source once.\n  const seen = new Set<string>();\n  const parts: string[] = [];\n  for (const r of results) {\n    if (!seen.has(r.chunk.sourceId)) {\n      seen.add(r.chunk.sourceId);\n      parts.push(r.chunk.text);\n    }\n  }\n  return parts.join('\\n\\n');\n}\n\nexport function extractChips(\n  index: { text: string; question?: string; sourceId?: string }[],\n  override?: string[]\n): string[] {\n  if (override && override.length > 0) return override.slice(0, 5);\n\n  const chips: string[] = [];\n  const seenText = new Set<string>();\n  const seenSource = new Set<string>();\n\n  for (const chunk of index) {\n    if (chips.length >= 5) break;\n\n    // Deduplicate by sourceId if available to ensure variety of answers.\n    if (chunk.sourceId) {\n      if (seenSource.has(chunk.sourceId)) continue;\n      seenSource.add(chunk.sourceId);\n    }\n\n    const candidate = chunk.question ?? extractFirstSentence(chunk.text);\n    if (candidate && !seenText.has(candidate)) {\n      seenText.add(candidate);\n      chips.push(candidate);\n    }\n  }\n\n  return chips;\n}\n\nfunction extractFirstSentence(text: string): string {\n  const match = text.match(/^[^\\n.!?]{10,80}[.!?\\n]?/);\n  if (!match) return text.slice(0, 60);\n  return match[0].trim();\n}\n"],"mappings":"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","names":["res","data","answer"]}

package/dist/server/index.d.cts

@@ -0,0 +1,62 @@
+type SageDeskModel = 'all-MiniLM-L6-v2' | 'bge-small-en-v1-5' | 'paraphrase-multilingual-MiniLM-L12-v2' | 'all-mpnet-base-v2';
+
+interface SageDeskHandlerConfig {
+    /** Filesystem path to the pre-built vector index (e.g. "./public/support-index.json"). */
+    indexPath: string;
+    /** LLM provider: 'openai', 'deepseek', 'groq', 'gemini', 'anthropic', or any OpenAI-compatible base URL. */
+    provider: string;
+    /** API key for the LLM provider. Never sent to the browser. */
+    apiKey: string;
+    /** LLM model name (e.g. 'deepseek-chat', 'gpt-4o-mini', 'llama3-8b-8192'). */
+    model: string;
+    /** Embedding model - must match the model used at build time. Defaults to all-MiniLM-L6-v2. */
+    embeddingModel?: SageDeskModel;
+    /** Number of chunks to retrieve for context. Defaults to 5. */
+    topK?: number;
+    /** Minimum similarity score for a chunk to be included. Defaults to 0.42. */
+    minScore?: number;
+    /** Override the system prompt sent to the LLM. */
+    systemPrompt?: string;
+    /** Timeout for LLM API calls in milliseconds. Defaults to 5000 (5 seconds). */
+    llmTimeoutMs?: number;
+}
+/**
+ * Returns a Next.js App Router POST handler.
+ *
+ * @example
+ * // app/api/sagedesk/route.ts
+ * import { createSageDeskHandler } from 'sagedesk/server'
+ * export const POST = createSageDeskHandler({
+ *   indexPath: './public/support-index.json',
+ *   provider: 'deepseek',
+ *   apiKey: process.env.SAGEDESK_LLM_API_KEY!,
+ *   model: 'deepseek-chat',
+ * })
+ */
+declare function createSageDeskHandler(config: SageDeskHandlerConfig): (request: Request) => Promise<Response>;
+type ExpressRequest = {
+    body: {
+        query?: string;
+    };
+};
+type ExpressResponse = {
+    status: (code: number) => ExpressResponse;
+    json: (data: unknown) => void;
+};
+type NextFunction = (err?: unknown) => void;
+/**
+ * Returns an Express (or any Connect-compatible) middleware.
+ *
+ * @example
+ * // server.ts / index.ts
+ * import { createSageDeskMiddleware } from 'sagedesk/server'
+ * app.use('/api/sagedesk', express.json(), createSageDeskMiddleware({
+ *   indexPath: './public/support-index.json',
+ *   provider: 'openai',
+ *   apiKey: process.env.SAGEDESK_LLM_API_KEY!,
+ *   model: 'gpt-4o-mini',
+ * }))
+ */
+declare function createSageDeskMiddleware(config: SageDeskHandlerConfig): (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => Promise<void>;
+
+export { type SageDeskHandlerConfig, createSageDeskHandler, createSageDeskMiddleware };

package/dist/server/index.d.ts

@@ -0,0 +1,62 @@
+type SageDeskModel = 'all-MiniLM-L6-v2' | 'bge-small-en-v1-5' | 'paraphrase-multilingual-MiniLM-L12-v2' | 'all-mpnet-base-v2';
+
+interface SageDeskHandlerConfig {
+    /** Filesystem path to the pre-built vector index (e.g. "./public/support-index.json"). */
+    indexPath: string;
+    /** LLM provider: 'openai', 'deepseek', 'groq', 'gemini', 'anthropic', or any OpenAI-compatible base URL. */
+    provider: string;
+    /** API key for the LLM provider. Never sent to the browser. */
+    apiKey: string;
+    /** LLM model name (e.g. 'deepseek-chat', 'gpt-4o-mini', 'llama3-8b-8192'). */
+    model: string;
+    /** Embedding model - must match the model used at build time. Defaults to all-MiniLM-L6-v2. */
+    embeddingModel?: SageDeskModel;
+    /** Number of chunks to retrieve for context. Defaults to 5. */
+    topK?: number;
+    /** Minimum similarity score for a chunk to be included. Defaults to 0.42. */
+    minScore?: number;
+    /** Override the system prompt sent to the LLM. */
+    systemPrompt?: string;
+    /** Timeout for LLM API calls in milliseconds. Defaults to 5000 (5 seconds). */
+    llmTimeoutMs?: number;
+}
+/**
+ * Returns a Next.js App Router POST handler.
+ *
+ * @example
+ * // app/api/sagedesk/route.ts
+ * import { createSageDeskHandler } from 'sagedesk/server'
+ * export const POST = createSageDeskHandler({
+ *   indexPath: './public/support-index.json',
+ *   provider: 'deepseek',
+ *   apiKey: process.env.SAGEDESK_LLM_API_KEY!,
+ *   model: 'deepseek-chat',
+ * })
+ */
+declare function createSageDeskHandler(config: SageDeskHandlerConfig): (request: Request) => Promise<Response>;
+type ExpressRequest = {
+    body: {
+        query?: string;
+    };
+};
+type ExpressResponse = {
+    status: (code: number) => ExpressResponse;
+    json: (data: unknown) => void;
+};
+type NextFunction = (err?: unknown) => void;
+/**
+ * Returns an Express (or any Connect-compatible) middleware.
+ *
+ * @example
+ * // server.ts / index.ts
+ * import { createSageDeskMiddleware } from 'sagedesk/server'
+ * app.use('/api/sagedesk', express.json(), createSageDeskMiddleware({
+ *   indexPath: './public/support-index.json',
+ *   provider: 'openai',
+ *   apiKey: process.env.SAGEDESK_LLM_API_KEY!,
+ *   model: 'gpt-4o-mini',
+ * }))
+ */
+declare function createSageDeskMiddleware(config: SageDeskHandlerConfig): (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => Promise<void>;
+
+export { type SageDeskHandlerConfig, createSageDeskHandler, createSageDeskMiddleware };