@pixygon/chatbot-server 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @pixygon/chatbot-server
+
+RAG chatbot + analytics for Node + Mongoose + Express hosts.
+
+## Install
+
+```bash
+npm install @pixygon/chatbot-server
+# Peer deps the host already has:
+# - express ≥5
+# - mongoose ≥8
+```
+
+## Usage
+
+```ts
+import { createChatbot } from "@pixygon/chatbot-server";
+import mongoose from "mongoose";
+import { Tenant } from "./models/Tenant.js";
+import { withTenantScope } from "./middleware/requestContext.js";
+import { tenantScopedPlugin } from "./models/_plugins/tenantScoped.js";
+
+const chatbot = createChatbot({
+  mongoose,
+  tenantParamName: "tenantId",            // also accepts "companyId"
+  tenantRefName: "Tenant",
+  ai: {
+    pixygonApiKey: process.env.PIXYGON_API_KEY!,
+    openaiApiKey: process.env.OPENAI_API_KEY!,
+  },
+  plugins: [(schema, label) => schema.plugin(tenantScopedPlugin, { 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(),
+    getCostCap: async (id) =>
+      (await Tenant.findById(id).select("chatCostCapUsdMonthly").lean())?.chatCostCapUsdMonthly ?? null,
+    withTenantScope,
+    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}`;
+    },
+  },
+});
+
+// Mount under whatever path the host wants.
+app.use("/v1/tenants/:tenantId", verifyToken, tenantAccess, chatbot.routes.private);
+app.use("/v1/public/chat", chatbot.routes.public);
+```
+
+## What you get
+
+- **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`):
+
+```
+GET    /knowledge
+POST   /knowledge
+GET    /knowledge/:documentId
+PUT    /knowledge/:documentId
+DELETE /knowledge/:documentId
+
+POST   /chat
+GET    /chat/:sessionId
+GET    /conversations?limit=50
+POST   /chat/rate
+
+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=&limit=50
+GET    /chat-analytics/semantic-clusters?limit=15
+```
+
+Public routes (mounted under `/v1/public/chat`):
+
+```
+POST   /:tenantSlug
+GET    /:tenantSlug/:sessionId
+POST   /:tenantSlug/rate
+```
+
+All public routes IP rate-limited (20/min/IP by default; override via
+`createPublicRouter(chatbot, { rateLimitConfig: { windowMs, max } })`).
+
+## 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.

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+import { Request, Response, NextFunction, Router } from 'express';
+import { Model, Schema, Mongoose } from 'mongoose';
+
+/**
+ * AI gateway client.
+ *
+ * - chat() → Pixygon AI gateway (POST /ai/api with FormData type=text).
+ *   PixygonServer's apiGenerate returns { text, url, role, model, version }.
+ * - embed() → OpenAI /embeddings directly. PixygonServer doesn't route
+ *   embeddings; they're commoditized + cheap so we hit OpenAI directly.
+ */
+interface AiConfig {
+    pixygonApiUrl?: string;
+    pixygonApiKey: string;
+    openaiApiUrl?: string;
+    openaiApiKey: string;
+    chatInputUsdPer1K?: number;
+    chatOutputUsdPer1K?: number;
+    embedUsdPer1K?: number;
+}
+interface ChatMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+interface ChatResult {
+    content: string;
+    model: string;
+    tokensInput: number;
+    tokensOutput: number;
+    costUsd: number;
+}
+interface EmbedResult {
+    embedding: number[];
+    tokens: number;
+    costUsd: number;
+    dimensions: number;
+}
+interface AiClient {
+    chat(args: {
+        messages: ChatMessage[];
+        system?: string;
+        model?: string;
+        version?: string;
+    }): Promise<ChatResult>;
+    embed(text: string, opts?: {
+        model?: string;
+    }): Promise<EmbedResult>;
+}
+declare function cosineSimilarity(a: number[], b: number[]): number;
+
+interface ModelFactoryOptions {
+    /** Field name on chatbot models that points at the tenant. */
+    tenantField: string;
+    /** Mongoose model name for the tenant document (used as Schema.ref). */
+    tenantRefName: string;
+    /**
+     * Optional plugins applied to each schema before model() — usually the
+     * host's `tenantScopedPlugin` and `auditLogPlugin`. The factory passes the
+     * compiled label so the plugin can scope logs.
+     */
+    plugins?: Array<(schema: Schema, label: string) => void>;
+}
+interface ChatbotModels {
+    KnowledgeDocument: Model<any>;
+    KnowledgeChunk: Model<any>;
+    ChatConversation: Model<any>;
+}
+
+/**
+ * Hooks the host implements to plug the package into its environment.
+ * Every per-app concern (tenant lookups, ALS, branding) flows through here.
+ */
+interface ChatbotHooks {
+    /** Resolve the tenant's display name for system-prompt injection. */
+    getTenantName: (tenantId: any) => Promise<string | null | undefined>;
+    /** Anonymous public chat looks tenants up by slug. */
+    getTenantBySlug: (slug: string) => Promise<{
+        _id: any;
+        name: string;
+        slug: string;
+    } | null>;
+    /** Optional monthly cost cap. Return null/undefined for no cap. */
+    getCostCap?: (tenantId: any) => Promise<number | null | undefined>;
+    /** AsyncLocalStorage tenant scope for handlers that run outside HTTP context. */
+    withTenantScope?: <T>(tenantId: any, fn: () => Promise<T> | T) => Promise<T> | T;
+    /**
+     * Build the LLM system prompt. Receives the tenant name + the formatted
+     * source-citation blocks. Host owns the wording.
+     */
+    systemPromptBuilder: (tenantName: string, contextBlocks: string[]) => string;
+}
+interface ChatbotConfig {
+    mongoose: Mongoose;
+    /** URL param name carrying the tenant id. e.g. "tenantId" or "companyId". */
+    tenantParamName: string;
+    /** Field name on chatbot docs that references the tenant. Usually same as param. */
+    tenantField?: string;
+    /** Mongoose ref string for the tenant model. */
+    tenantRefName: string;
+    /** AI gateway credentials + rate knobs. */
+    ai: AiConfig;
+    hooks: ChatbotHooks;
+    /**
+     * Mongoose plugins to attach to every schema before model registration.
+     * Pass the host's tenant-scoped plugin + audit-log plugin here.
+     */
+    plugins?: Array<(schema: any, label: string) => void>;
+}
+interface Chatbot {
+    models: ChatbotModels;
+    ai: AiClient;
+    config: Required<Pick<ChatbotConfig, "tenantParamName" | "tenantField" | "tenantRefName">> & ChatbotConfig;
+}
+
+interface Citation {
+    chunkId: any;
+    documentId: any;
+    documentTitle: string;
+    snippet: string;
+    similarity: number;
+}
+interface RespondArgs {
+    tenantId: any;
+    sessionId: string;
+    userId?: any;
+    message: string;
+}
+interface RespondResult {
+    conversationId: any;
+    assistantContent: string;
+    citations: Citation[];
+    costUsd: number;
+}
+/**
+ * Factory for the RAG entry points. Bound to a Chatbot — captures models,
+ * ai client, hooks. The returned object is what the host hands to controllers.
+ */
+declare function createRag(chatbot: Chatbot): {
+    respond: ({ tenantId, sessionId, userId, message }: RespondArgs) => Promise<RespondResult>;
+    processDocument: (documentId: any) => Promise<void>;
+    currentMonthCost: (tenantId: any, now?: Date) => Promise<number>;
+};
+
+interface AnalyticsService {
+    overview(tenantId: any): Promise<any>;
+    topQuestions(tenantId: any, limit?: number): Promise<any[]>;
+    keywordFrequency(tenantId: any, limit?: number): Promise<any[]>;
+    costTimeseries(tenantId: any, days?: number): Promise<any[]>;
+    knowledgeGaps(tenantId: any, limit?: number): Promise<any[]>;
+    documentUsage(tenantId: any): Promise<any[]>;
+    conversationsForQuestion(tenantId: any, normalized: string, limit?: number): Promise<any[]>;
+    semanticClusters(tenantId: any, limit?: number): Promise<any[]>;
+}
+declare function createAnalytics(chatbot: Chatbot): AnalyticsService;
+
+interface Chunk {
+    text: string;
+    position: number;
+}
+declare function chunkText(input: string): Chunk[];
+
+declare function rateLimit({ windowMs, max, scope, }: {
+    windowMs: number;
+    max: number;
+    scope: string;
+}): (req: Request, res: Response, next: NextFunction) => void;
+
+/**
+ * Wire up the chatbot for a host. Returns models, services, and Express
+ * router factories. Idempotent — calling twice returns the same models.
+ *
+ *   const chatbot = createChatbot({ mongoose, tenantParamName: "tenantId", ... });
+ *
+ *   app.use("/v1/tenants/:tenantId", verifyToken, tenantAccess, chatbot.routes.private);
+ *   app.use("/v1/public/chat", chatbot.routes.public);
+ */
+declare function createChatbot(cfg: ChatbotConfig): Chatbot & {
+    rag: ReturnType<typeof createRag>;
+    analytics: ReturnType<typeof createAnalytics>;
+    routes: {
+        private: Router;
+        public: Router;
+    };
+};
+
+export { type AiClient, type AiConfig, type AnalyticsService, type ChatMessage, type ChatResult, type Chatbot, type ChatbotConfig, type ChatbotHooks, type ChatbotModels, type Citation, type EmbedResult, type ModelFactoryOptions, type RespondArgs, type RespondResult, chunkText, cosineSimilarity, createChatbot, rateLimit };