@pixygon/chatbot-server 0.1.0 → 0.2.0

package/README.md

@@ -1,82 +1,151 @@
 # @pixygon/chatbot-server
 
-RAG chatbot + analytics for Node + Mongoose + Express hosts.
+Drop-in RAG chatbot + knowledge base + analytics for **Node 22 + Express 5 + Mongoose 8**.
+Multi-tenant by construction. Public anonymous surface included.
+
+```
++--------------------+      +-------------------------+
+|  Host Express app  |----->| chatbot.routes.private  |
+|  (your auth here)  |      | chatbot.routes.public   |
++--------------------+      +-------------------------+
+        |                              |
+        v                              v
+   Host's mongoose          chatbot.{rag, analytics}
+   (models register here)    services
+        |
+        v
+   KnowledgeDocument · KnowledgeChunk · ChatConversation
+```
+
+---
+
+## What it does
+
+- **Knowledge base.** Operators paste docs (text/url/file). The service chunks
+  to ~2 kB paragraphs, embeds via OpenAI `text-embedding-3-small` (1536-dim),
+  stores chunks per tenant.
+- **Chat (RAG).** User asks a question → cosine-sim top-K=5 chunks → renders a
+  system prompt → forwards to the Pixygon AI gateway (configurable model) →
+  returns text + cited sources.
+- **Analytics.** 8 endpoints: overview KPIs, top questions, keyword frequency,
+  cost timeseries, knowledge gaps, document usage, conversation drill-down,
+  semantic clusters. All tenant-scoped.
+- **Public surface.** Anonymous `/public/chat/:tenantSlug` for embedding on
+  marketing/help-center sites. IP rate-limited.
+- **Cost cap.** Per-tenant monthly USD ceiling. New messages refused with a
+  503 `CHAT_BUDGET_EXCEEDED` once exceeded.
+
+---
 
 ## Install
 
 ```bash
 npm install @pixygon/chatbot-server
-# Peer deps the host already has:
-# - express ≥5
-# - mongoose ≥8
 ```
 
+Peer expectations (host already has these):
+
+- `express` ≥ 5
+- `mongoose` ≥ 8
+- Node ≥ 22
+
+Env vars consumed by `createChatbot`:
+
+| Var | Required | What it's for |
+|---|---|---|
+| `PIXYGON_API_KEY` | yes | Chat completions via the Pixygon AI gateway |
+| `OPENAI_API_KEY` | yes | Embeddings (`text-embedding-3-small`) |
+| `PIXYGON_API_URL` | no | Override gateway base; default `https://api.pixygon.com/v1` |
+| `PIXYGON_CHAT_INPUT_USD_PER_1K` | no | Cost-cap input pricing |
+| `PIXYGON_CHAT_OUTPUT_USD_PER_1K` | no | Cost-cap output pricing |
+| `OPENAI_EMBED_USD_PER_1K` | no | Cost-cap embeddings pricing |
+
+---
+
 ## Usage
 
 ```ts
-import { createChatbot } from "@pixygon/chatbot-server";
 import mongoose from "mongoose";
+import { createChatbot } from "@pixygon/chatbot-server";
 import { Tenant } from "./models/Tenant.js";
 import { withTenantScope } from "./middleware/requestContext.js";
 import { tenantScopedPlugin } from "./models/_plugins/tenantScoped.js";
+import { auditLogPlugin } from "./models/_plugins/auditLog.js";
 
-const chatbot = createChatbot({
+export const chatbot = createChatbot({
   mongoose,
-  tenantParamName: "tenantId",            // also accepts "companyId"
-  tenantRefName: "Tenant",
+  tenantParamName: "tenantId",      // path param: /tenants/:tenantId/...
+  tenantField: "tenantId",          // the field name on documents
+  tenantRefName: "Tenant",          // mongoose ref name for population
+
   ai: {
     pixygonApiKey: process.env.PIXYGON_API_KEY!,
     openaiApiKey: process.env.OPENAI_API_KEY!,
   },
-  plugins: [(schema, label) => schema.plugin(tenantScopedPlugin, { label })],
+
+  // Optional host plugins applied to every chatbot model.
+  // Use this for tenant-scoped query enforcement, audit log, etc.
+  plugins: [
+    (schema, label) =>
+      schema.plugin(tenantScopedPlugin, { tenantField: "tenantId", label }),
+    (schema, label) =>
+      schema.plugin(auditLogPlugin, { entityType: label }),
+  ],
+
   hooks: {
     getTenantName: async (id) =>
-      (await Tenant.findById(id).select("name").lean())?.name,
-    getTenantBySlug: async (slug) =>
-      Tenant.findOne({ slug, status: "active" }).select("_id name slug").lean(),
+      (await Tenant.findById(id).select("name").lean())?.name ?? null,
+
+    getTenantBySlug: async (slug) => {
+      const t = await Tenant.findOne({ slug, status: "active" })
+        .select("_id name slug").lean();
+      return t ? { _id: t._id, name: t.name, slug: t.slug } : null;
+    },
+
     getCostCap: async (id) =>
-      (await Tenant.findById(id).select("chatCostCapUsdMonthly").lean())?.chatCostCapUsdMonthly ?? null,
-    withTenantScope,
+      (await Tenant.findById(id).select("chatCostCapUsdMonthly").lean())
+        ?.chatCostCapUsdMonthly ?? null,
+
+    withTenantScope: (tenantId, fn) => withTenantScope(tenantId, fn),
+
     systemPromptBuilder: (tenantName, contextBlocks) => {
       const sources = contextBlocks.length === 0
-        ? "(no relevant sources)"
-        : contextBlocks.map((b, i) => `[Source ${i + 1}]\n${b}`).join("\n\n");
-      return `You are the ${tenantName} assistant. Use ONLY the sources below.\n\n${sources}`;
+        ? "(no relevant sources matched)"
+        : contextBlocks.map((c, i) => `[Source ${i + 1}]\n${c}`).join("\n\n");
+      return `You are the ${tenantName} assistant. Use ONLY the sources below as factual basis. If unsure, say so.
+
+=== Sources ===
+${sources}
+=== End ===`;
     },
   },
 });
 
-// Mount under whatever path the host wants.
+// Mount under whatever shape the host uses.
 app.use("/v1/tenants/:tenantId", verifyToken, tenantAccess, chatbot.routes.private);
 app.use("/v1/public/chat", chatbot.routes.public);
 ```
 
-## What you get
+A host that uses `companyId` instead of `tenantId` swaps both `tenantParamName`
+and `tenantField` to `"companyId"`. The package adapts.
 
-- **Models** registered on the host's connection: `KnowledgeDocument`,
-  `KnowledgeChunk`, `ChatConversation`.
-- **Services**: `chatbot.rag.respond({tenantId, sessionId, message})`,
-  `chatbot.rag.processDocument(docId)`, `chatbot.rag.currentMonthCost(tenantId)`,
-  `chatbot.analytics.*` (8 methods).
-- **Routers**: `chatbot.routes.private` (auth required, mounted under a
-  tenant-scoped path) and `chatbot.routes.public` (anonymous, IP rate-limited,
-  slug-based lookup).
+---
 
 ## API surface
 
-Private routes (mounted under `/v1/tenants/:tenantId`):
+**Private routes** (mounted under `/v1/<tenants>/:<id>`):
 
 ```
 GET    /knowledge
-POST   /knowledge
+POST   /knowledge                       { title, sourceType, sourceText? | url? }
 GET    /knowledge/:documentId
-PUT    /knowledge/:documentId
+PUT    /knowledge/:documentId           { title?, sourceText? }
 DELETE /knowledge/:documentId
 
-POST   /chat
+POST   /chat                            { sessionId, message }
 GET    /chat/:sessionId
 GET    /conversations?limit=50
-POST   /chat/rate
+POST   /chat/rate                       { sessionId, turnIndex, rating }  // 1 | -1
 
 GET    /chat-analytics/overview
 GET    /chat-analytics/top-questions?limit=20
@@ -84,24 +153,99 @@ GET    /chat-analytics/keywords?limit=30
 GET    /chat-analytics/cost-timeseries?days=30
 GET    /chat-analytics/knowledge-gaps?limit=15
 GET    /chat-analytics/document-usage
-GET    /chat-analytics/conversations?normalized=&limit=50
+GET    /chat-analytics/conversations?normalized=<q>&limit=50
 GET    /chat-analytics/semantic-clusters?limit=15
 ```
 
-Public routes (mounted under `/v1/public/chat`):
+**Public routes** (mounted under `/v1/public/chat`):
 
 ```
-POST   /:tenantSlug
+POST   /:tenantSlug                     { sessionId, message }
 GET    /:tenantSlug/:sessionId
-POST   /:tenantSlug/rate
+POST   /:tenantSlug/rate                { sessionId, turnIndex, rating }
 ```
 
-All public routes IP rate-limited (20/min/IP by default; override via
-`createPublicRouter(chatbot, { rateLimitConfig: { windowMs, max } })`).
+Default IP rate limit: 20 req/min/IP. Override via
+`createPublicRouter(chatbot, { rateLimitConfig: { windowMs, max } })` if you
+need to wire a custom limiter — or use the exported `rateLimit` helper.
+
+---
+
+## Hooks reference
+
+| Hook | Required | Purpose |
+|---|---|---|
+| `getTenantName(id)` | yes | System prompt — "You are the X assistant" |
+| `getTenantBySlug(slug)` | yes (for public surface) | Resolves slug to tenant for anonymous chat |
+| `getCostCap(id)` | yes | Returns monthly USD cap; `null` = no cap |
+| `withTenantScope(id, fn)` | yes | AsyncLocalStorage wrapper for tenant context |
+| `systemPromptBuilder(name, blocks)` | yes | Builds the LLM system prompt with citations |
+
+`plugins` is an array of `(schema, label) => void` — applied to every chatbot
+model schema. Use this to attach your host's tenant-scope enforcement, audit
+log, soft-delete, or whatever else every model needs.
+
+---
+
+## Direct service calls
+
+The router is convenient but you can call the services directly if needed:
+
+```ts
+const { text, citations, usage } = await chatbot.rag.respond({
+  tenantId, sessionId, message: "How do I export SAF-T?",
+});
+
+await chatbot.rag.processDocument(documentId);     // background embedding
+const spend = await chatbot.rag.currentMonthCost(tenantId);
+
+const kpis = await chatbot.analytics.overview(tenantId);
+const gaps = await chatbot.analytics.knowledgeGaps(tenantId, 10);
+const clusters = await chatbot.analytics.semanticClusters(tenantId, 15);
+```
+
+---
 
 ## Cost-cap enforcement
 
-When `hooks.getCostCap` returns a number > 0, `rag.respond()` pre-flights
-the current-month cost. Over the cap throws a 503 with code
-`CHAT_BUDGET_EXCEEDED`. Host's error handler should map application errors
-with a numeric `.status` to the response.
+When `hooks.getCostCap(tenantId)` returns a number > 0, `rag.respond()`
+pre-flights the current month's spend. Over the cap → throws
+`{ status: 503, code: "CHAT_BUDGET_EXCEEDED" }`. The host's error handler
+should map application errors with a numeric `.status` to the response.
+
+```ts
+// somewhere in your error middleware
+app.use((err, req, res, next) => {
+  if (err.status) return res.status(err.status).json({ error: err.code || err.message });
+  next(err);
+});
+```
+
+---
+
+## Exports
+
+```ts
+import {
+  createChatbot,             // main factory
+  chunkText,                 // 2 kB paragraph chunker
+  cosineSimilarity,          // dot-product over unit vectors
+  rateLimit,                 // express middleware factory
+  type ChatbotConfig,
+  type ChatbotHooks,
+  type Chatbot,
+  type ChatMessage,
+  type Citation,
+  type RespondArgs,
+  type RespondResult,
+  type AnalyticsService,
+} from "@pixygon/chatbot-server";
+```
+
+---
+
+## Companion package
+
+`@pixygon/chatbot-react` ships matching MUI + RTK Query pages
+(KnowledgePage / ChatPage / ChatAnalyticsPage / EmbedChatPage /
+ChatbotSettings). See its README for the React/Vite wire-up.

package/dist/index.js

@@ -134,12 +134,41 @@ function createAiClient(cfg) {
       return { content, model: `${model}/${version}`, tokensInput, tokensOutput, costUsd };
     },
     async embed(text, opts = {}) {
+      const model = opts.model || "text-embedding-3-small";
       if (!cfg.openaiApiKey) {
-        const err = new Error("OPENAI_API_KEY not set");
-        err.code = "OPENAI_UNCONFIGURED";
-        throw err;
+        if (!cfg.pixygonApiKey) {
+          const err = new Error("PIXYGON_API_KEY (or OPENAI_API_KEY) required for embeddings");
+          err.code = "EMBED_UNCONFIGURED";
+          throw err;
+        }
+        const formData = new FormData();
+        formData.append("type", "embedding");
+        formData.append("model", "openai");
+        formData.append("version", model);
+        formData.append("prompt", text);
+        const res2 = await fetch(PIXYGON_AI_URL, {
+          method: "POST",
+          headers: { "x-api-key": cfg.pixygonApiKey },
+          body: formData
+        });
+        if (!res2.ok) {
+          const body = await res2.text().catch(() => "");
+          const err = new Error(`Pixygon embed failed: ${res2.status} \u2014 ${body.slice(0, 300)}`);
+          err.code = "PIXYGON_EMBED_FAILED";
+          err.status = res2.status;
+          throw err;
+        }
+        const payload2 = await res2.json();
+        const vector = payload2?.embedding;
+        if (!Array.isArray(vector) || vector.length === 0) {
+          const err = new Error("Pixygon embed response had no vector");
+          err.code = "PIXYGON_EMBED_EMPTY";
+          throw err;
+        }
+        const tokens2 = Number(payload2?.tokens ?? approxTokens(text));
+        const costUsd2 = tokens2 / 1e3 * EMBED_RATE;
+        return { embedding: vector, tokens: tokens2, costUsd: costUsd2, dimensions: vector.length };
       }
-      const model = opts.model || "text-embedding-3-small";
       const res = await fetch(`${OPENAI_API_URL}/embeddings`, {
         method: "POST",
         headers: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixygon/chatbot-server",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "RAG chatbot + analytics for Node + Mongoose + Express hosts.",
   "type": "module",
   "main": "./dist/index.js",