@burtson-labs/bandit-engine 2.0.8 → 2.0.9

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,4 +1,10 @@
-<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)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
@@ -37,6 +43,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
@@ -53,6 +61,9 @@ The CLI prints next steps (install, copy `.env`, run dev server) once scaffoldin
 
 ## 🛠️ 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 +103,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 +114,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 +156,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 +224,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 +233,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 +550,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 +620,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
 
@@ -647,8 +708,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:
@@ -1043,7 +1102,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 +1136,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 +1185,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 +1261,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 +1288,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/chat-OLCX6TBK.mjs

@@ -0,0 +1,15 @@
+import {
+  chat_default
+} from "./chunk-6YRLBITU.mjs";
+import "./chunk-ONQMRE2G.mjs";
+import "./chunk-5E7S7DK3.mjs";
+import "./chunk-PXXVEH5M.mjs";
+import "./chunk-6IHJZCUH.mjs";
+import "./chunk-QHLKGSMB.mjs";
+import "./chunk-AVC6IZJQ.mjs";
+import "./chunk-KCI46M23.mjs";
+import "./chunk-BJTO5JO5.mjs";
+export {
+  chat_default as default
+};
+//# sourceMappingURL=chat-OLCX6TBK.mjs.map