# .npmrc
@pixygon:registry=https://ppm.pixygon.io/

npm install @pixygon/chatbot-server@0.7.1

@pixygon/chatbot-server

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

npm install @pixygon/chatbot-server

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	All AI calls — chat and embeddings — route through the Pixygon AI gateway (POST /v1/ai/api). PixygonServer handles upstream provider selection, billing, and the 20 % platform markup.
PIXYGON_API_URL	no	Override gateway base; default https://api.pixygon.com/v1
PIXYGON_CHAT_INPUT_USD_PER_1K	no	Local cost estimate used by the chatbot's cost-cap pre-flight + per-conversation analytics. Not the same as the platform's billing rates.
PIXYGON_CHAT_OUTPUT_USD_PER_1K	no	Same — for chat output
OPENAI_EMBED_USD_PER_1K	no	Same — for embeddings

There is no direct-provider bypass — every call flows through Pixygon so per-key margin tracking stays accurate. A single PIXYGON_API_KEY is all you need.

---

Usage

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";

export const chatbot = createChatbot({
  mongoose,
  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!,
  },

  // 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 ?? 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: (tenantId, fn) => withTenantScope(tenantId, fn),

    systemPromptBuilder: (tenantName, contextBlocks) => {
      const sources = contextBlocks.length === 0
        ? "(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 shape the host uses.
app.use("/v1/tenants/:tenantId", verifyToken, tenantAccess, chatbot.routes.private);
app.use("/v1/public/chat", chatbot.routes.public);

A host that uses companyId instead of tenantId swaps both tenantParamName and tenantField to "companyId". The package adapts.

---

API surface

Private routes (mounted under /v1/<tenants>/:<id>):

GET    /knowledge
POST   /knowledge                       { title, sourceType, sourceText? | url? }
GET    /knowledge/:documentId
PUT    /knowledge/:documentId           { title?, sourceText? }
DELETE /knowledge/:documentId

POST   /chat                            { sessionId, message }
GET    /chat/:sessionId
GET    /conversations?limit=50
POST   /chat/rate                       { sessionId, turnIndex, rating }  // 1 | -1

GET    /chat-analytics/overview
GET    /chat-analytics/top-questions?limit=20
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=<q>&limit=50
GET    /chat-analytics/semantic-clusters?limit=15

Public routes (mounted under /v1/public/chat):

POST   /:tenantSlug                     { sessionId, message }
GET    /:tenantSlug/:sessionId
POST   /:tenantSlug/rate                { sessionId, turnIndex, rating }

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:

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(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.

// 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

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";

---

Troubleshooting

Errors thrown by the gateway include a code and (for HTTP failures) a status field, surfaced to the host's error handler:

code	When	Fix
PIXYGON_AI_UNCONFIGURED	PIXYGON_API_KEY not set	Provision a key on admin.pixygon.io and put it in the host's env
PIXYGON_AI_CHAT_FAILED	Gateway returned non-2xx for chat	Check key balance + model availability
PIXYGON_EMBED_FAILED	Gateway returned non-2xx for embeddings	Same
PIXYGON_EMBED_EMPTY	Gateway returned 2xx but no vector	Unlikely — file an issue if it happens
CHAT_BUDGET_EXCEEDED (status 503)	Tenant.chatCostCapUsdMonthly reached for the calendar month	Raise the cap or wait until next month

When the host echoes err.code in its error response, consumers can diagnose without scraping logs.

Migration

v0.2.x → v0.3.0 (breaking)

Direct OpenAI routing was removed. All AI calls now flow through the Pixygon AI gateway unconditionally, so per-API-key margin tracking on admin.pixygon.io stays accurate.

What to change:

• Drop openaiApiKey and openaiApiUrl from your createChatbot({ ai }) config — they no longer exist on the AiConfig type.
• Delete OPENAI_API_KEY / OPENAI_API_URL from your host's env (Coolify, .env, secrets store, etc.).
• If you used OPENAI_EMBED_USD_PER_1K for the cost-cap estimate, rename to PIXYGON_EMBED_USD_PER_1K — same shape, just a clearer name now that embeddings go through Pixygon.

Before:

ai: {
  pixygonApiKey: process.env.PIXYGON_API_KEY!,
  openaiApiKey:  process.env.OPENAI_API_KEY!,    // remove
}

After:

ai: { pixygonApiKey: process.env.PIXYGON_API_KEY! }

That's the full migration — the API surface (chatbot.rag, chatbot.analytics, chatbot.routes.*, model exports) is unchanged.

Companion package

@pixygon/chatbot-react ships matching MUI + RTK Query pages (KnowledgePage / ChatPage / ChatAnalyticsPage / EmbedChatPage / ChatbotSettings / ChatLauncher). See its README for the React/Vite wire-up.

License

MIT.