@burtson-labs/bandit-engine 2.0.9 → 2.0.11

package/README.md

@@ -6,18 +6,32 @@
   </picture>
 </a>
 
-[![npm version](https://img.shields.io/npm/v/%40burtson-labs%2Fbandit-engine)](https://www.npmjs.com/package/@burtson-labs/bandit-engine)
+# Bandit Engine ⚡
+
+An AI chat toolkit built for speed, design, and control. Power branded AI assistants with battle-tested React components and a secure gateway contract.
+
+[![npm private](https://img.shields.io/badge/npm-private-lightgrey?logo=npm)](https://www.npmjs.com/package/@burtson-labs/bandit-engine)
+[![Docs](https://img.shields.io/badge/docs-banditailabs.com%2Fnpm--package-0C7BD4)](https://banditailabs.com/npm-package)
+[![Live Demo](https://img.shields.io/badge/live%20demo-banditailabs.com%2Fchat-7F56D9)](https://banditailabs.com/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-red)](./LICENSE)
 
-> **Welcome to the Bandit Engine – an AI chat interface toolkit from Burtson Labs.**
-> Designed for devs who move fast, think sharp, and want full control over their AI chat UX. Plug it in, power it up, and bend AI to your brand's will.
+## Features
+- 🔌 Plug-and-play React chat, modal, and management surfaces
+- 🧠 Memory, vector knowledge, and provider switching behind a secure gateway
+- 🎨 Full MUI theming, dark mode, and branding controls out of the box
+- 🌐 Multimodal support (voice, images, documents) with Ollama, OpenAI, Azure, Anthropic
+- 🛠️ CLI scaffolding, sample gateway, and docs to launch in minutes
 
-📚 Looking for docs? Start with the [documentation index](./docs/README.md) or jump straight to the [gateway contract](./docs/02_gateway_api.md).
+## Quick Links
+- 📚 Full docs: [banditailabs.com/npm-package](https://banditailabs.com/npm-package) (mirrors `/docs` in this repo)
+- 🎯 Live demo with OAuth sign-in: [banditailabs.com](https://banditailabs.com/)
+- 🧪 Playground (no auth required): [banditailabs.com/playground](https://banditailabs.com/playground)
+- 🔁 Sample gateway: [`examples/gateway-node`](./examples/gateway-node/README.md)
 
-🧪 Want to kick the tires? Clone the [Node.js gateway example](./examples/gateway-node/README.md) for a ready-to-run backend.
+## Quick Start
 
-## ⚡ CLI Quick Start
+### CLI Scaffold
 
 Want a working playground instantly? Scaffold a Bandit app and gateway in one command:
 
@@ -59,6 +73,16 @@ Check out the [CLI quick start guide](./docs/05_cli_quickstart.md) for the full
 
 The CLI prints next steps (install, copy `.env`, run dev server) once scaffolding completes, so you can copy-paste and ship immediately.
 
+### Playground (Password-Free Preview)
+
+Want to feel the UX without wiring a gateway or signing in? Visit the hosted playground:
+
+- **URL:** [`https://banditailabs.com/playground`](https://banditailabs.com/playground)
+- **What you get:** Mock streaming answers, conversation starters, and theming preview powered by the built-in `PlaygroundProvider`.
+- **What’s simulated:** Responses come from canned scripts – no external API keys, tokens, or backend required.
+
+The playground is ideal for product demos, initial stakeholder reviews, or QA before you connect real providers. When you’re ready to go live, swap the provider back to your gateway for production traffic.
+
 ## 🛠️ Getting Started – Plug & Play AI
 
 
@@ -676,11 +700,13 @@ const chatPackageSettings = {
 - 🔄 **Provider Switching**: Change backends without frontend updates
 - 🛡️ **Authentication**: Unified auth across all AI services
 
-**Gateway Requirements:**
+**Gateway Requirements:**  
 Your gateway API can be built with any technology (Node.js, Python, .NET, Java, etc.) as long as it implements:
-- `GET /api/health` - Health check endpoint
-- `POST /api/chat/completions` - Chat completions with provider in request body
-- `POST /api/generate` - Text generation with provider in request body
+- `GET /api/health` — Health check endpoint that lists available providers.
+- `GET /api/models` and `GET /api/models/{provider}` — Model discovery for the management UI.
+- `POST /api/chat/completions` and `POST /api/generate` — Default OpenAI-style routes when no provider override is present.
+- `POST /api/{provider}/chat/completions` and `POST /api/{provider}/generate` — Provider-specific routing for `openai`, `azure-openai`, and `anthropic`.
+- `POST /api/ollama/chat` and `POST /api/ollama/generate` — Native Ollama routes (no `/chat/completions` suffix).
 
 ### Legacy Direct Providers
 
@@ -742,22 +768,32 @@ The Bandit Engine provides comprehensive image support across all AI providers t
 Your gateway API should accept images in the standardized format sent by the Bandit Engine and forward them appropriately to each provider. No transformation needed - the frontend handles provider-specific formatting.
 
 ```javascript
-// Example: Gateway forwards images as-is to each provider
-app.post('/api/chat/completions', async (req, res) => {
-  const { provider, messages, ...options } = req.body;
-  
-  // Messages already contain properly formatted images
-  // Forward directly to the target provider API
-  switch (provider) {
-    case 'ollama':
-      // messages[].images format (base64 arrays)
-      return await ollamaClient.chat({ messages, ...options });
-    case 'openai':  
-      // messages[].content[].image_url format (structured)
-      return await openaiClient.chat.completions.create({ messages, ...options });
-    default:
-      throw new Error(`Unsupported provider: ${provider}`);
-  }
+// Example: Gateway forwards images as-is using provider-specific routes
+app.post('/api/openai/chat/completions', async (req, res) => {
+  const { messages, ...options } = req.body;
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`
+    },
+    body: JSON.stringify({ messages, ...options })
+  });
+
+  res.status(response.status);
+  response.body?.pipe(res);
+});
+
+app.post('/api/ollama/chat', async (req, res) => {
+  const { messages, ...options } = req.body;
+  const response = await fetch(`${process.env.OLLAMA_URL}/api/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ messages, ...options })
+  });
+
+  res.status(response.status);
+  response.body?.pipe(res);
 });
 ```
 
@@ -1025,7 +1061,7 @@ Your gateway API should validate subscription tiers and return appropriate featu
 
 ```javascript
 // Example: Gateway API subscription validation
-app.post('/api/chat/completions', authenticateJWT, async (req, res) => {
+app.post('/api/openai/chat/completions', authenticateJWT, async (req, res) => {
   const { subscriptionType, isSubscribed } = req.user;
   
   // Validate tier access for requested features
@@ -1036,8 +1072,17 @@ app.post('/api/chat/completions', authenticateJWT, async (req, res) => {
   }
   
   // Proceed with AI request
-  const response = await processAIRequest(req.body);
-  res.json(response);
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env.OPENAI_API_KEY}`
+    },
+    body: JSON.stringify(req.body)
+  });
+
+  res.status(response.status);
+  response.body?.pipe(res);
 });
 ```
 

package/dist/{aiProviderStore-YWJHSWFA.mjs → aiProviderStore-3YS2BZU3.mjs}

@@ -1,9 +1,9 @@
 import {
   useAIProviderStore
-} from "./chunk-AVC6IZJQ.mjs";
+} from "./chunk-IHJPVIGB.mjs";
 import "./chunk-KCI46M23.mjs";
 import "./chunk-BJTO5JO5.mjs";
 export {
   useAIProviderStore
 };
-//# sourceMappingURL=aiProviderStore-YWJHSWFA.mjs.map
+//# sourceMappingURL=aiProviderStore-3YS2BZU3.mjs.map

package/dist/chat-ZPJNWIXI.mjs

@@ -0,0 +1,15 @@
+import {
+  chat_default
+} from "./chunk-5UVULH77.mjs";
+import "./chunk-ONQMRE2G.mjs";
+import "./chunk-RTQDQ6TC.mjs";
+import "./chunk-XEG45Q6V.mjs";
+import "./chunk-UMPVXYVC.mjs";
+import "./chunk-XUBYA5I7.mjs";
+import "./chunk-IHJPVIGB.mjs";
+import "./chunk-KCI46M23.mjs";
+import "./chunk-BJTO5JO5.mjs";
+export {
+  chat_default as default
+};
+//# sourceMappingURL=chat-ZPJNWIXI.mjs.map

package/dist/chat-provider.js

@@ -3184,6 +3184,185 @@ var init_gateway_provider = __esm({
   }
 });
 
+// src/services/ai-provider/providers/playground.provider.ts
+var import_rxjs8, PLAYGROUND_MODELS, PLAYGROUND_CONVERSATION_STARTERS, PLAYGROUND_SCRIPTS, FALLBACK_RESPONSE, STREAM_DELAY_MS, PlaygroundProvider;
+var init_playground_provider = __esm({
+  "src/services/ai-provider/providers/playground.provider.ts"() {
+    "use strict";
+    import_rxjs8 = require("rxjs");
+    init_common_types();
+    PLAYGROUND_MODELS = [
+      {
+        name: "bandit-playground",
+        details: {
+          format: "chat",
+          family: "bandit",
+          families: ["bandit", "demo"],
+          parameter_size: "demo",
+          quantization_level: "synthetic"
+        },
+        digest: "playground-demo-001",
+        modified_at: (/* @__PURE__ */ new Date()).toISOString()
+      },
+      {
+        name: "bandit-starter",
+        details: {
+          format: "chat",
+          family: "bandit",
+          families: ["bandit", "demo"],
+          parameter_size: "demo",
+          quantization_level: "synthetic"
+        },
+        digest: "playground-demo-002",
+        modified_at: (/* @__PURE__ */ new Date()).toISOString()
+      }
+    ];
+    PLAYGROUND_CONVERSATION_STARTERS = [
+      "What can I build with Bandit Engine if my backend is not ready yet?",
+      "How does the gateway contract keep API keys out of the browser?",
+      "Can I theme the chat UI to match my product brand?",
+      "How do I switch between Ollama and OpenAI without redeploying the frontend?",
+      "Show me how the management console handles personas and models."
+    ];
+    PLAYGROUND_SCRIPTS = [
+      {
+        match: (input) => /model|switch|personas|management/i.test(input),
+        response: [
+          "Absolutely \u2014 the management console ships with live model switching, persona editing, and feature toggles.",
+          "",
+          "- Use the **Models** tab to expose whichever gateway-backed models you want customers to see.",
+          "- Personas hydrate the chat with branded system prompts, voice preferences, and avatars.",
+          "- Everything persists through the gateway, so you can roll out changes without shipping a new build."
+        ].join("\n")
+      },
+      {
+        match: (input) => /gateway|api|contract|backend/i.test(input),
+        response: [
+          "The gateway contract keeps secrets on the server while giving the UI a unified AI API.",
+          "",
+          "Key highlights:",
+          "1. `/api/chat/completions` is the default OpenAI-format endpoint when no provider override is set.",
+          "2. `/api/{provider}/chat/completions` handles OpenAI, Azure OpenAI, and Anthropic while `/api/ollama/chat` streams Ollama responses.",
+          "3. The contract is language-agnostic \u2014 Express, FastAPI, .NET, Go\u2026 anything works as long as it speaks HTTP."
+        ].join("\n")
+      },
+      {
+        match: (input) => /style|theme|brand|ui/i.test(input),
+        response: [
+          "Every surface in Bandit Engine is themeable.",
+          "",
+          "- Drop a JSON config into your `public/` folder (or host it on a CDN) to control themes, logos, and accent colors.",
+          "- The React components expose hooks for custom headers, menus, and call-to-action buttons.",
+          "- Need a modal? `ChatModal` reuses the same store, so the handoff between embedded chat and floating assistant stays seamless."
+        ].join("\n")
+      },
+      {
+        match: (input) => /voice|tts|audio/i.test(input),
+        response: [
+          "Voice is opt-in, but the plumbing is ready.",
+          "",
+          "- Configure `/api/tts` and `/api/stt` on the gateway to unlock the speak/listen controls.",
+          "- The UI lazily loads voices and respects feature flags, so you can leave it disabled in the playground.",
+          "- Everything streams \u2014 the assistant starts speaking before the full response lands."
+        ].join("\n")
+      },
+      {
+        match: (input) => /deploy|production|secure/i.test(input),
+        response: [
+          "Production hardening is front and center.",
+          "",
+          "- Gateway tokens ride in the `Authorization` header; rotate them server-side without touching the bundle.",
+          "- Feature flags gate premium surfaces, letting you trial the UI before wiring billing.",
+          "- Vector search, knowledge, and memories are isolated behind `/api/embedding/*` so you can plug in your own storage policies."
+        ].join("\n")
+      }
+    ];
+    FALLBACK_RESPONSE = [
+      "Bandit Engine is running in playground mode. I'm simulating how streaming works so you can explore the UX without connecting a live model.",
+      "",
+      "Try asking about the gateway contract, theming, voice features, or model management to see tailored walkthroughs."
+    ].join("\n");
+    STREAM_DELAY_MS = 350;
+    PlaygroundProvider = class {
+      config;
+      constructor(config) {
+        this.config = { type: "playground" /* PLAYGROUND */, ...config };
+      }
+      chat(request) {
+        const lastUserMessage = [...request.messages].reverse().find((m) => m.role === "user")?.content ?? "";
+        const script = PLAYGROUND_SCRIPTS.find(
+          (scenario) => scenario.match(lastUserMessage)
+        );
+        const responseText = script?.response ?? FALLBACK_RESPONSE;
+        const chunks = this.splitIntoChunks(responseText);
+        return new import_rxjs8.Observable((observer) => {
+          let index = 0;
+          const emitChunk = () => {
+            if (index >= chunks.length) {
+              observer.complete();
+              return;
+            }
+            const chunk = chunks[index];
+            observer.next({
+              message: {
+                content: chunk,
+                role: "assistant"
+              },
+              done: index === chunks.length - 1
+            });
+            index += 1;
+            setTimeout(emitChunk, STREAM_DELAY_MS);
+          };
+          emitChunk();
+          return () => {
+            index = chunks.length;
+          };
+        });
+      }
+      generate(_request) {
+        const starters = PLAYGROUND_CONVERSATION_STARTERS.join("\n");
+        return new import_rxjs8.Observable((observer) => {
+          observer.next({
+            response: starters,
+            done: true
+          });
+          observer.complete();
+        });
+      }
+      listModels() {
+        return new import_rxjs8.Observable((observer) => {
+          observer.next(PLAYGROUND_MODELS);
+          observer.complete();
+        });
+      }
+      async validateServiceAvailability(args) {
+        const simulatedUrl = this.config.baseUrl ?? "playground://local";
+        if (args.timeoutMs > 0) {
+          await new Promise((resolve) => setTimeout(resolve, Math.min(args.timeoutMs, 250)));
+        }
+        return {
+          url: simulatedUrl,
+          isAvailable: true
+        };
+      }
+      getProviderType() {
+        return "playground" /* PLAYGROUND */;
+      }
+      getConfig() {
+        return this.config;
+      }
+      splitIntoChunks(response) {
+        const paragraphs = response.split("\n\n").map((p) => p.trim()).filter(Boolean);
+        if (paragraphs.length <= 1) {
+          const sentences = response.split(/(?<=[.!?])\s+/).filter(Boolean);
+          return sentences.length > 0 ? sentences : [response];
+        }
+        return paragraphs;
+      }
+    };
+  }
+});
+
 // src/services/ai-provider/ai-provider.factory.ts
 var AIProviderFactory;
 var init_ai_provider_factory = __esm({
@@ -3195,6 +3374,7 @@ var init_ai_provider_factory = __esm({
     init_azure_openai_provider();
     init_anthropic_provider();
     init_gateway_provider();
+    init_playground_provider();
     AIProviderFactory = class {
       static createProvider(config) {
         switch (config.type) {
@@ -3208,6 +3388,8 @@ var init_ai_provider_factory = __esm({
             return new AnthropicProvider(config);
           case "gateway" /* GATEWAY */:
             return new GatewayProvider(config);
+          case "playground" /* PLAYGROUND */:
+            return new PlaygroundProvider(config);
           default:
             throw new Error(`Unsupported AI provider type: ${config.type}`);
         }
@@ -3218,7 +3400,8 @@ var init_ai_provider_factory = __esm({
           "openai" /* OPENAI */,
           "azure-openai" /* AZURE_OPENAI */,
           "anthropic" /* ANTHROPIC */,
-          "gateway" /* GATEWAY */
+          "gateway" /* GATEWAY */,
+          "playground" /* PLAYGROUND */
         ];
       }
       static validateConfig(config) {
@@ -3234,6 +3417,8 @@ var init_ai_provider_factory = __esm({
             return !!config.apiKey;
           case "gateway" /* GATEWAY */:
             return !!(config.gatewayUrl && config.provider);
+          case "playground" /* PLAYGROUND */:
+            return true;
           default:
             return false;
         }
@@ -5659,7 +5844,7 @@ var import_mammoth = __toESM(require("mammoth"));
 var pdfjsLib = __toESM(require("pdfjs-dist/legacy/build/pdf"));
 
 // src/services/prompts/conversationStarters.ts
-var import_rxjs8 = require("rxjs");
+var import_rxjs9 = require("rxjs");
 init_aiProviderStore();
 init_packageSettingsStore();
 
@@ -5817,19 +6002,19 @@ var NotificationService = class {
 var notificationService = new NotificationService();
 
 // src/services/prompts/moodDetection.ts
-var import_rxjs9 = require("rxjs");
+var import_rxjs10 = require("rxjs");
 init_aiProviderStore();
 init_packageSettingsStore();
 init_debugLogger();
 
 // src/services/prompts/detectUserInterestAndExcitement.ts
-var import_rxjs10 = require("rxjs");
+var import_rxjs11 = require("rxjs");
 init_aiProviderStore();
 init_packageSettingsStore();
 init_debugLogger();
 
 // src/services/prompts/documentSummarization.ts
-var import_rxjs11 = require("rxjs");
+var import_rxjs12 = require("rxjs");
 init_aiProviderStore();
 init_packageSettingsStore();
 init_debugLogger();
@@ -5857,8 +6042,8 @@ ${content.slice(0, 4e3)}
       stream: false,
       options: { temperature: 0.3, num_predict: 100 }
     });
-    const summary$ = data$.pipe((0, import_rxjs11.map)((d) => d.response.trim()));
-    const summary = await (0, import_rxjs11.lastValueFrom)(summary$);
+    const summary$ = data$.pipe((0, import_rxjs12.map)((d) => d.response.trim()));
+    const summary = await (0, import_rxjs12.lastValueFrom)(summary$);
     debugLogger.ragDebug("summarizeDocument result", { name, summary });
     return summary || `Document summary for ${name}`;
   } catch (error) {
@@ -5868,7 +6053,7 @@ ${content.slice(0, 4e3)}
 };
 
 // src/services/prompts/documentRelevance.ts
-var import_rxjs12 = require("rxjs");
+var import_rxjs13 = require("rxjs");
 init_aiProviderStore();
 init_packageSettingsStore();
 init_debugLogger();
@@ -9331,10 +9516,16 @@ var ChatProvider = (props) => {
       useProjectStore.getState().hydrate();
       useAIQueryStore.getState().hydrate();
       useMemoryStore.getState().hydrate();
-      await usePreferencesStore.getState().loadPreferences();
-      await useKnowledgeStore.getState().loadDocs();
-      await useMCPToolsStore.getState().loadTools();
-      await useConversationSyncStore.getState().initialize();
+      const isPlaygroundRoute = typeof window !== "undefined" && window.location.pathname.includes("/playground");
+      const isPlaygroundMode = isPlaygroundRoute || props.packageSettings.playgroundMode === true;
+      if (isPlaygroundMode) {
+        debugLogger.info("ChatProvider: Playground mode detected \u2014 skipping remote preference and sync initialization");
+      } else {
+        await usePreferencesStore.getState().loadPreferences();
+        await useKnowledgeStore.getState().loadDocs();
+        await useMCPToolsStore.getState().loadTools();
+        await useConversationSyncStore.getState().initialize();
+      }
       debugLogger.info("ChatProvider about to call initModels - checking for existing branding first");
       const storeConfigs6 = [{ name: "config", keyPath: "id" }];
       let existingBranding = null;
@@ -9396,10 +9587,14 @@ var ChatProvider = (props) => {
           debugLogger.error("\u274C Failed to fetch or apply branding config:", { error: err });
         });
       }
-      loadDocuments();
-      embeddingService.backfillMissingEmbeddings().catch((err) => {
-        debugLogger.error("\u274C Failed to backfill memory embeddings:", { error: err });
-      });
+      if (!isPlaygroundMode) {
+        loadDocuments();
+        embeddingService.backfillMissingEmbeddings().catch((err) => {
+          debugLogger.error("\u274C Failed to backfill memory embeddings:", { error: err });
+        });
+      } else {
+        debugLogger.info("ChatProvider: Playground mode skipping knowledge backfill");
+      }
     };
     initializeAsync();
   }, [props.packageSettings, loadDocuments]);