@burtson-labs/bandit-engine 2.0.8 → 2.0.10

package/LICENSE

@@ -20,14 +20,14 @@ https://burtson.ai/license
 Parameters
 
 Licensor:             Burtson Labs LLC
-Licensed Work:        Bandit Engine AI Chat Application
+Licensed Work:        Bandit Engine UI SDK
                       The Licensed Work is © 2025 Burtson Labs
 Additional Use Grant: You may make use of the Licensed Work, provided that you do not use
                       the Licensed Work for a Commercial Use. A "Commercial Use" means use of
                       the Licensed Work in production, or any other use that is primarily
                       intended for or directed toward commercial advantage or monetary
                       compensation.
-Change Date:          January 1, 2027
+Change Date:          April 1, 2027
 Change License:       Apache License, Version 2.0
 
 For information about alternative licensing arrangements for the Licensed Work,

package/README.md

@@ -1,17 +1,37 @@
-<a href="https://burtson.ai"><img src="https://cdn.burtson.ai/logos/burtson-labs-logo-alt.png" alt="Burtson Labs Logo" width="120" style="width: 120px !important; max-width: 120px !important; height: auto; display: inline-block;" /></a>
+<a href="https://burtson.ai">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cdn.burtson.ai/logos/burtson-labs-logo-alt.png" />
+    <source media="(prefers-color-scheme: light)" srcset="https://cdn.burtson.ai/logos/burtson-labs-logo.png" />
+    <img src="https://cdn.burtson.ai/logos/burtson-labs-logo.png" alt="Burtson Labs Logo" width="120" style="width: 120px !important; max-width: 120px !important; height: auto; display: inline-block;" />
+  </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:
 
@@ -37,6 +57,8 @@ Customize the output with options such as:
 
 > 🗝️ The generated project includes an `.npmrc` that targets `https://npm.pkg.github.com/` and expects a `GITHUB_NPM_TOKEN` environment variable. Run `npm login --registry=https://npm.pkg.github.com --scope=@burtson-labs` (or export `GITHUB_NPM_TOKEN`) before installing dependencies.
 
+> ⚠️ The scaffolded gateway focuses on OpenAI/Ollama chat and model discovery. All advanced routes (file storage uploads, vector embedding, voice, MCP, etc.) are generated as `501` placeholders so you can wire them to your own infrastructure. Implement the contracts below before turning on those features in production.
+
 Check out the [CLI quick start guide](./docs/05_cli_quickstart.md) for the full walkthrough, option matrix, and project anatomy.
 
 ### CLI Options
@@ -51,8 +73,21 @@ 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
 
+
+Bandit ships with responsive layouts baked in — the chat surface, management console, and modal all collapse gracefully on phones and tablets. Install it inside a Vite project and you can ship a polished PWA: the package works offline when cached, supports mobile nav patterns, and plays nicely with add-to-home-screen flows.
+
 1. **Add a config.json** to your public folder (or host it on a CDN) and point `brandingConfigUrl` at it:
 
 _Host it locally in `/public` or serve it from a CDN and reference it via `brandingConfigUrl`._
@@ -92,7 +127,7 @@ const chatPackageSettings = {
     provider: "openai" // Backend: openai, azure-openai, anthropic, ollama
   },
   
-  // Legacy Ollama Configuration (Still Supported)
+  // Direct Ollama configuration (development only)
   // ollamaUrl: import.meta.env.VITE_OLLAMA_URL!,
   
   // Model Configuration
@@ -103,7 +138,7 @@ const chatPackageSettings = {
   
   // Branding and optional overrides
   brandingConfigUrl: "/config.json",
-  // s3ApiUrl: import.meta.env.VITE_S3_API_URL,
+  // fileStorageApiUrl: import.meta.env.VITE_FILE_STORAGE_API_URL,
   // homeUrl: "https://yourapp.com",
   // feedbackEmail: "feedback@yourapp.com",
 };
@@ -145,13 +180,34 @@ aiProvider: {
 }
 ```
 
-**Gateway Requirements:** Your backend needs to implement these endpoints:
-- `GET /api/health` - Health check
-- `POST /api/chat/completions` - Chat completions  
-- `POST /api/generate` - Text generation
-- `POST /api/tts` - Text-to-Speech (optional, for voice features)
-- `GET /api/tts/available-models` - TTS model listing (optional)
-- `POST /api/stt` - Speech-to-Text (optional, for voice input)
+**Gateway Requirements:** Implement the endpoints that match the features you turn on:
+
+- **Core status & discovery**
+  - `GET /api/health` — system health and provider availability
+  - `GET /api/models` and `GET /api/models/{provider}` — model inventory
+  - `GET /api/memory` — hydrate personal memory when the feature is enabled
+- **Chat & text generation**
+  - `POST /api/chat/completions` — default provider routing
+  - `POST /api/{provider}/chat/completions` — provider-specific routing (e.g. `openai`, `azure-openai`, `anthropic`)
+  - `POST /api/ollama/chat` — native Ollama chat format
+  - `POST /api/generate` — non-chat generation (conversation starters, summaries, etc.)
+  - `POST /api/{provider}/generate` — same contract, but scoped per provider (required for conversation starters to respect OpenAI vs. Ollama routing)
+- **Knowledge & vector search** (required for memories, knowledge management, and MCP document tools)
+  - `POST /api/embedding/embed-memory`
+  - `POST /api/embedding/batch-embed-memories`
+  - `POST /api/embedding/embed-document`
+  - `POST /api/embedding/search` and `POST /api/embedding/search-memories`
+  - `GET /api/embedding/my-memories` (with `skip`/`limit`)
+  - `DELETE /api/embedding/memory/{memoryId}` and `PUT /api/embedding/memory/{memoryId}/pin`
+  - `GET /api/embedding/available-files` and `GET /api/embedding/files`
+  - See [File Storage API Contract](#file-storage-api-contract) for the companion `/file/*` routes used to upload and download source documents.
+- **Voice & transcription**
+  - `POST /api/tts` — synthesize speech
+  - `GET /api/tts/available-models` — advertise available voices
+  - `POST /api/stt/transcribe` — speech-to-text ingestion
+- **Feedback & subscriptions** (optional but recommended)
+  - `POST /api/feedback` — submit in-app feedback
+  - `GET /subscription/{userId}` and `PUT /subscription/{userId}` — synchronize subscription tiers used by the feature-flag system
 
 > **⚠️ Important:** The Bandit Engine automatically routes to provider-specific endpoints:
 > - **Ollama** → `/api/ollama/chat` (native Ollama format)
@@ -192,7 +248,7 @@ The Bandit Engine supports Text-to-Speech (TTS) and Speech-to-Text (STT) through
 - **Output**: Audio file (MP3, WAV, etc.) or streaming audio
 - **Compatible with**: OpenAI TTS, Azure Speech, Google Cloud TTS, AWS Polly, local TTS servers, or custom implementations
 
-**STT Endpoint (`POST /api/stt`)**  
+**STT Endpoint (`POST /api/stt/transcribe`)**  
 - **Input**: Audio file upload (multipart/form-data)
 - **Output**: `{ text: string }` or `{ transcription: string }`
 - **Compatible with**: OpenAI Whisper, Azure Speech, Google Speech, AWS Transcribe, local Whisper servers, or custom implementations
@@ -201,6 +257,8 @@ The Bandit Engine supports Text-to-Speech (TTS) and Speech-to-Text (STT) through
 - **Output**: `{ models: string[], defaultModel: string, fallbackModel: string }`
 - Used for automatic service availability detection and voice model selection
 
+> Quickstart note: the generated Express gateway ships these TTS/STT routes as `501` placeholders so you can connect your own provider. Voice features remain disabled until you implement them server-side.
+
 See the [Gateway API Contract](./docs/02_gateway_api.md) for complete implementation examples in multiple languages.
 
 Use the Management interface to switch providers anytime or migrate from direct to gateway setup.
@@ -516,32 +574,44 @@ Here are some screenshots of Bandit Chat in action:
 
 **Chat Demo – Your AI-powered UI**  
 <p align="center">
-  <img src="./public/images/chat-demo.jpg" alt="Bandit chat session showing multi-turn conversation with inline actions" width="600" />
+  <a href="https://cdn.burtson.ai/images/chat-demo.jpg" target="_blank" rel="noopener">
+    <img src="https://cdn.burtson.ai/images/chat-demo.jpg" alt="Bandit chat session showing multi-turn conversation with multi-device layout" width="600" style="width: 100%; max-width: 600px; height: auto;" />
+  </a>
 </p>
 
 **Conversation Drawer & Project Context**  
 <p align="center">
-  <img src="./public/images/chat-demo-2.jpg" alt="Chat drawer open with projects list and answered question" width="600" />
+  <a href="https://cdn.burtson.ai/images/chat-demo-2.jpg" target="_blank" rel="noopener">
+    <img src="https://cdn.burtson.ai/images/chat-demo-2.jpg" alt="Chat drawer open with projects list and answered question" width="600" style="width: 100%; max-width: 600px; height: auto;" />
+  </a>
 </p>
 
 **Chat Modal – Quick Assist Anywhere**  
 <p align="center">
-  <img src="./public/images/chat-modal.jpg" alt="Chat modal with control center options and message composer" width="600" />
+  <a href="https://cdn.burtson.ai/images/chat-modal.jpg" target="_blank" rel="noopener">
+    <img src="https://cdn.burtson.ai/images/chat-modal.jpg" alt="Chat modal with control center options and message composer" width="600" style="width: 100%; max-width: 600px; height: auto;" />
+  </a>
 </p>
 
 **Management – Branding Controls**  
 <p align="center">
-  <img src="./public/images/mgmt-branding.jpg" alt="Management interface branding tab showing logo and color options" width="600" />
+  <a href="https://cdn.burtson.ai/images/mgmt-branding.jpg" target="_blank" rel="noopener">
+    <img src="https://cdn.burtson.ai/images/mgmt-branding.jpg" alt="Management interface branding tab showing logo and color options" width="600" style="width: 100%; max-width: 600px; height: auto;" />
+  </a>
 </p>
 
 **Management – Personas**  
 <p align="center">
-  <img src="./public/images/mgmt-personalities.jpg" alt="Management interface personas tab with configurable AI personalities" width="600" />
+  <a href="https://cdn.burtson.ai/images/mgmt-personalities.jpg" target="_blank" rel="noopener">
+    <img src="https://cdn.burtson.ai/images/mgmt-personalities.jpg" alt="Management interface personas tab with configurable AI personalities" width="600" style="width: 100%; max-width: 600px; height: auto;" />
+  </a>
 </p>
 
 **Management – Preferences**  
 <p align="center">
-  <img src="./public/images/mgmt-preferences.jpg" alt="Management interface preferences tab with feature toggles" width="600" />
+  <a href="https://cdn.burtson.ai/images/mgmt-preferences.jpg" target="_blank" rel="noopener">
+    <img src="https://cdn.burtson.ai/images/mgmt-preferences.jpg" alt="Management interface preferences tab with feature toggles" width="600" style="width: 100%; max-width: 600px; height: auto;" />
+  </a>
 </p>
 
 
@@ -574,11 +644,26 @@ This enables remote control of Bandit appearance, available models, and more —
 - `gatewayApiUrl`: Gateway API base URL for AI, TTS, STT, and MCP
 - `aiProvider`: Provider configuration object (recommended for new installs)
 - `ollamaUrl`: Legacy Ollama base URL (deprecated, prefer `aiProvider`)
-- `s3ApiUrl`: Optional file storage API base URL (defaults to `gatewayApiUrl`)
+- `fileStorageApiUrl`: Optional file storage API base URL (defaults to `gatewayApiUrl`)
 - `brandingConfigUrl`: Hosted branding JSON used to hydrate UI theming
 - `homeUrl`: Optional URL for the home button in management UI
 - `feedbackEmail`: Optional email address for feedback submissions
 - `featureFlags`: Optional feature flag configuration (see examples below)
+- `types`: Official TypeScript entry point is available at `@burtson-labs/bandit-engine/types`. Importing from that path gives you rich IntelliSense for `ChatProviderProps`, `PackageSettings`, `ChatModalProps`, gateway contracts, and more.
+
+### File Storage API Contract
+
+Enabling `fileStorageApiUrl` activates document uploads for vector memories, but the CLI quickstart intentionally leaves the backend stubbed. When you point the frontend at a file storage service, Bandit expects these authenticated endpoints:
+
+- `POST /file/upload` — `multipart/form-data` body with `file` and optional `shareWithTeam`; returns `{ fileId, message? }`
+- `GET /file/files?skip=0&limit=50` — lists previously uploaded files and metadata (`id`, `filename`, `size`, `contentType`, `updatedAt`)
+- `GET /file/download/{fileId}` — streams the file associated with the supplied identifier
+
+All requests include a Bearer token issued by your gateway. Implementers can back these routes with S3, MinIO, or any storage provider — the frontend only requires the contract above.
+
+These file operations are invoked in tandem with the `/api/embedding/*` endpoints described earlier to keep the vector index in sync.
+
+> Quickstart note: the bundled Express gateway does not implement these upload/download routes; they currently return `501` until you connect real storage.
 
 ## 🤖 AI Provider System
 
@@ -615,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
 
@@ -647,8 +734,6 @@ aiProvider: {
 3. **Test Connection**: Use the Management interface to validate
 4. **Update API Keys**: Move keys from frontend to backend config
 
-See `GATEWAY_MIGRATION_GUIDE.md` for detailed migration steps.
-
 ### Image/Multimodal Support
 
 The Bandit Engine provides comprehensive image support across all AI providers through the gateway architecture:
@@ -683,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);
 });
 ```
 
@@ -966,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
@@ -977,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);
 });
 ```
 
@@ -1043,7 +1147,7 @@ const chatPackageSettings = {
 // ❌ Deprecated (still works but not recommended)
 const oldSettings = {
   ttsUrl: "/api/tts",
-  sttUrl: "/api/stt",
+  sttUrl: "/api/stt/transcribe",
   ollamaUrl: "http://localhost:11434",
 };
 
@@ -1077,7 +1181,7 @@ The Bandit Engine uses a **unified gateway approach** for all backend services.
   - Output: Audio file or streaming audio
   - **Technology-agnostic**: Works with OpenAI TTS, Azure Speech, Google TTS, AWS Polly, Whisper.cpp, or custom implementations
 
-- `POST /api/stt` - Speech-to-Text transcription
+- `POST /api/stt/transcribe` - Speech-to-Text transcription
   - Input: Audio file upload (multipart/form-data)
   - Output: `{ text: string }` or `{ transcription: string }`
   - **Technology-agnostic**: Works with OpenAI Whisper, Azure Speech, Google Speech, AWS Transcribe, local Whisper, or custom implementations
@@ -1126,7 +1230,7 @@ If you're currently using separate `ttsUrl` and `sttUrl` settings, migrate to th
 ```tsx
 const settings = {
   ttsUrl: "https://your-tts-service.com/api/tts",
-  sttUrl: "https://your-stt-service.com/api/stt", 
+  sttUrl: "https://your-stt-service.com/api/stt/transcribe", 
   ollamaUrl: "https://your-ollama.com",
 };
 ```
@@ -1202,11 +1306,13 @@ This codebase includes multiple protection layers:
 
 ### 👨‍💻 For Contributors & Developers
 
-Before contributing or making changes to this codebase:
+Before contributing or publishing a new Pull Request, run the available validation scripts:
 
 ```bash
-# Essential pre-push workflow - run before every commit
-npm run pre-push
+npm run lint               # Static analysis for the src tree
+npm run test               # Vitest suite
+npm run build              # Generate the dist bundle with tsup
+npm run validate-protection # Ensure license headers and fingerprints are intact
 ```
 
 **Developer Resources:**
@@ -1227,7 +1333,6 @@ All source files must include proper license headers and watermarks. The protect
 ```bash
 npm run protect             # Apply protection to new files
 npm run validate-protection # Check for license violations  
-npm run pre-push           # Complete pre-push validation
 ```
 
 ---

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