@burtson-labs/bandit-engine 2.0.8

package/dist/memoryUtils-33TZKHSQ.mjs

@@ -0,0 +1,223 @@
+import "./chunk-BJTO5JO5.mjs";
+
+// src/utils/memoryUtils.ts
+var isRecord = (value) => typeof value === "object" && value !== null;
+var isStringArray = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+var resolveTimestampLabel = (timestamp) => {
+  if (timestamp instanceof Date && !Number.isNaN(timestamp.getTime())) {
+    return timestamp.toLocaleDateString();
+  }
+  if (typeof timestamp === "number" && Number.isFinite(timestamp)) {
+    const date = new Date(timestamp);
+    if (!Number.isNaN(date.getTime())) {
+      return date.toLocaleDateString();
+    }
+  }
+  if (typeof timestamp === "string" && timestamp.trim()) {
+    const date = new Date(timestamp);
+    if (!Number.isNaN(date.getTime())) {
+      return date.toLocaleDateString();
+    }
+  }
+  return (/* @__PURE__ */ new Date()).toLocaleDateString();
+};
+var MemoryUtils = class {
+  /**
+   * Validate memory content before bulk operations
+   */
+  static validateMemories(memories) {
+    const valid = [];
+    const invalid = [];
+    memories.forEach((memory, index) => {
+      if (!memory.content || memory.content.trim().length === 0) {
+        invalid.push({
+          content: memory.content || "",
+          error: "Empty content",
+          index
+        });
+        return;
+      }
+      if (memory.content.length > 5e4) {
+        invalid.push({
+          content: memory.content.substring(0, 100) + "...",
+          error: "Content too long (max 50KB)",
+          index
+        });
+        return;
+      }
+      if (memory.tags && (!Array.isArray(memory.tags) || memory.tags.some((tag) => typeof tag !== "string"))) {
+        invalid.push({
+          content: memory.content.substring(0, 100) + "...",
+          error: "Invalid tags format (must be string array)",
+          index
+        });
+        return;
+      }
+      valid.push(memory);
+    });
+    return { valid, invalid };
+  }
+  /**
+   * Format IndexedDB memories for vector import
+   */
+  static formatForVectorImport(indexedDBMemories) {
+    return indexedDBMemories.reduce((acc, entry) => {
+      if (!isRecord(entry)) {
+        return acc;
+      }
+      const candidate = entry;
+      if (typeof candidate.content !== "string") {
+        return acc;
+      }
+      const title = typeof candidate.title === "string" && candidate.title.trim().length > 0 ? candidate.title : `Memory from ${resolveTimestampLabel(candidate.timestamp)}`;
+      const tags = isStringArray(candidate.tags) ? candidate.tags : [];
+      acc.push({
+        content: candidate.content,
+        title,
+        tags
+      });
+      return acc;
+    }, []);
+  }
+  /**
+   * Chunk large batch operations for better performance
+   */
+  static chunkMemories(memories, chunkSize = 100) {
+    const chunks = [];
+    for (let i = 0; i < memories.length; i += chunkSize) {
+      chunks.push(memories.slice(i, i + chunkSize));
+    }
+    return chunks;
+  }
+  /**
+   * Estimate batch operation time and resource usage
+   */
+  static estimateBatchOperation(memoryCount, averageContentLength) {
+    const warnings = [];
+    const embeddingsPerMinute = 100;
+    const tokensPerCharacter = 0.25;
+    const estimatedTimeMinutes = Math.ceil(memoryCount / embeddingsPerMinute);
+    const estimatedTokens = Math.ceil(memoryCount * averageContentLength * tokensPerCharacter);
+    let recommendedChunkSize = 50;
+    if (memoryCount > 1e3) {
+      recommendedChunkSize = 25;
+      warnings.push("Large batch operation - consider running during off-peak hours");
+    }
+    if (averageContentLength > 2e3) {
+      recommendedChunkSize = Math.max(10, recommendedChunkSize / 2);
+      warnings.push("Large content size - reduced chunk size recommended");
+    }
+    if (estimatedTimeMinutes > 30) {
+      warnings.push("Long operation expected - ensure stable internet connection");
+    }
+    return {
+      estimatedTimeMinutes,
+      estimatedTokens,
+      recommendedChunkSize,
+      warnings
+    };
+  }
+  /**
+   * Create summary report for batch operations
+   */
+  static createBatchSummary(result, operationType, startTime) {
+    const endTime = /* @__PURE__ */ new Date();
+    const durationMs = endTime.getTime() - startTime.getTime();
+    const durationMinutes = Math.floor(durationMs / 6e4);
+    const durationSeconds = Math.floor(durationMs % 6e4 / 1e3);
+    const totalMemories = result.summary?.totalProcessed ?? result.totalMemories ?? 0;
+    const successful = result.summary?.successCount ?? result.successCount ?? 0;
+    const failed = result.summary?.failureCount ?? result.failureCount ?? 0;
+    const successRate = totalMemories > 0 ? (successful / totalMemories * 100).toFixed(1) : "0";
+    const avgTimePerMemory = totalMemories > 0 ? (durationMs / totalMemories).toFixed(0) : "0";
+    const summary = `${operationType.toUpperCase()} completed: ${successful}/${totalMemories} memories processed successfully (${successRate}% success rate) in ${durationMinutes}m ${durationSeconds}s`;
+    const details = {
+      operation: operationType,
+      duration: `${durationMinutes}m ${durationSeconds}s`,
+      totalMemories,
+      successful,
+      failed,
+      successRate: `${successRate}%`,
+      averageTimePerMemory: `${avgTimePerMemory}ms`
+    };
+    return { summary, details };
+  }
+  /**
+   * Generate progress messages for UI updates
+   */
+  static generateProgressMessage(current, total, operation = "Processing") {
+    const percentage = Math.floor(current / total * 100);
+    const remaining = total - current;
+    if (current === 0) {
+      return `Starting ${operation.toLowerCase()}...`;
+    } else if (current === total) {
+      return `${operation} completed!`;
+    } else if (current < total / 4) {
+      return `${operation} memories... (${current}/${total})`;
+    } else if (current < total / 2) {
+      return `${percentage}% complete... (${remaining} remaining)`;
+    } else if (current < total * 0.9) {
+      return `Almost done... ${percentage}% complete`;
+    } else {
+      return `Finishing up... ${remaining} memories left`;
+    }
+  }
+  /**
+   * Compare memory content for deduplication
+   */
+  static calculateSimilarity(content1, content2) {
+    const words1 = content1.toLowerCase().split(/\s+/);
+    const words2 = content2.toLowerCase().split(/\s+/);
+    const set1 = new Set(words1);
+    const set2 = new Set(words2);
+    const intersection = new Set([...set1].filter((word) => set2.has(word)));
+    const union = /* @__PURE__ */ new Set([...set1, ...set2]);
+    return union.size > 0 ? intersection.size / union.size : 0;
+  }
+  /**
+   * Find potential duplicates in memory list
+   */
+  static findPotentialDuplicates(memories, similarityThreshold = 0.8) {
+    const duplicates = [];
+    for (let i = 0; i < memories.length; i++) {
+      const currentMemory = memories[i];
+      const potentialDuplicates = [];
+      for (let j = i + 1; j < memories.length; j++) {
+        const compareMemory = memories[j];
+        const similarity = this.calculateSimilarity(currentMemory.content, compareMemory.content);
+        if (similarity >= similarityThreshold) {
+          potentialDuplicates.push({
+            memory: compareMemory,
+            similarity,
+            index: j
+          });
+        }
+      }
+      if (potentialDuplicates.length > 0) {
+        duplicates.push({
+          memory: currentMemory,
+          duplicates: potentialDuplicates
+        });
+      }
+    }
+    return duplicates;
+  }
+};
+var validateMemories = MemoryUtils.validateMemories;
+var formatForVectorImport = MemoryUtils.formatForVectorImport;
+var chunkMemories = MemoryUtils.chunkMemories;
+var estimateBatchOperation = MemoryUtils.estimateBatchOperation;
+var createBatchSummary = MemoryUtils.createBatchSummary;
+var generateProgressMessage = MemoryUtils.generateProgressMessage;
+var findPotentialDuplicates = MemoryUtils.findPotentialDuplicates;
+export {
+  MemoryUtils,
+  chunkMemories,
+  createBatchSummary,
+  estimateBatchOperation,
+  findPotentialDuplicates,
+  formatForVectorImport,
+  generateProgressMessage,
+  validateMemories
+};
+//# sourceMappingURL=memoryUtils-33TZKHSQ.mjs.map

package/dist/memoryUtils-33TZKHSQ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/memoryUtils.ts"],"sourcesContent":["/*\n  © 2025 Burtson Labs — Licensed under Business Source License 1.1\n  https://burtson.ai/license\n\n  This file is protected intellectual property.\n  Do NOT use in commercial software, prompts, AI training data, or derivative works without a valid commercial license.\n\n  🚫 AI NOTICE: This file contains visible and invisible watermarks.\n  ⚖️  VIOLATION NOTICE: Removing, modifying, or obscuring these watermarks is a license violation.\n  🔒 LICENSE TERMINATION: Upon license termination, ALL forks, copies, and derivatives must be permanently deleted.\n  📋 AUDIT TRAIL: File usage is logged and monitored for compliance verification.\n*/\n\n// Bandit Engine Watermark: BL-WM-9A9C-45AD6B\nconst __banditFingerprint_utils_memoryUtilsts = 'BL-FP-E6A353-3010';\nconst __auditTrail_utils_memoryUtilsts = 'BL-AU-MGOIKVWA-JZOJ';\n// File: memoryUtils.ts | Path: src/utils/memoryUtils.ts | Hash: 9a9c3010\n\nexport interface BulkMemoryResult {\n  success: boolean;\n  message: string;\n  totalProcessed: number;\n  successCount: number;\n  failureCount: number;\n  errors: string[];\n}\n\nexport interface MemoryImportOptions {\n  mode: 'append' | 'replace' | 'smartDedupe';\n  clearExisting?: boolean;\n  includeMetadata?: boolean;\n  batchSize?: number;\n}\n\ntype MemoryRecordCandidate = {\n  content?: unknown;\n  title?: unknown;\n  tags?: unknown;\n  timestamp?: unknown;\n};\n\ntype BatchOperationResult = {\n  summary?: {\n    totalProcessed?: number;\n    successCount?: number;\n    failureCount?: number;\n  };\n  totalMemories?: number;\n  successCount?: number;\n  failureCount?: number;\n};\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === 'object' && value !== null;\n\nconst isStringArray = (value: unknown): value is string[] =>\n  Array.isArray(value) && value.every((item) => typeof item === 'string');\n\nconst resolveTimestampLabel = (timestamp: unknown): string => {\n  if (timestamp instanceof Date && !Number.isNaN(timestamp.getTime())) {\n    return timestamp.toLocaleDateString();\n  }\n\n  if (typeof timestamp === 'number' && Number.isFinite(timestamp)) {\n    const date = new Date(timestamp);\n    if (!Number.isNaN(date.getTime())) {\n      return date.toLocaleDateString();\n    }\n  }\n\n  if (typeof timestamp === 'string' && timestamp.trim()) {\n    const date = new Date(timestamp);\n    if (!Number.isNaN(date.getTime())) {\n      return date.toLocaleDateString();\n    }\n  }\n\n  return new Date().toLocaleDateString();\n};\n\n/**\n * Memory Utilities for Bulk Operations\n * \n * Provides helper functions for batch memory operations,\n * data formatting, and migration utilities.\n */\nexport class MemoryUtils {\n  /**\n   * Validate memory content before bulk operations\n   */\n  static validateMemories(memories: Array<{ content: string; title?: string; tags?: string[] }>): {\n    valid: Array<{ content: string; title?: string; tags?: string[] }>;\n    invalid: Array<{ content: string; error: string; index: number }>;\n  } {\n    const valid: Array<{ content: string; title?: string; tags?: string[] }> = [];\n    const invalid: Array<{ content: string; error: string; index: number }> = [];\n\n    memories.forEach((memory, index) => {\n      // Check content length\n      if (!memory.content || memory.content.trim().length === 0) {\n        invalid.push({\n          content: memory.content || '',\n          error: 'Empty content',\n          index\n        });\n        return;\n      }\n\n      // Check maximum content length (e.g., 50KB)\n      if (memory.content.length > 50000) {\n        invalid.push({\n          content: memory.content.substring(0, 100) + '...',\n          error: 'Content too long (max 50KB)',\n          index\n        });\n        return;\n      }\n\n      // Check tags format\n      if (memory.tags && (!Array.isArray(memory.tags) || memory.tags.some(tag => typeof tag !== 'string'))) {\n        invalid.push({\n          content: memory.content.substring(0, 100) + '...',\n          error: 'Invalid tags format (must be string array)',\n          index\n        });\n        return;\n      }\n\n      valid.push(memory);\n    });\n\n    return { valid, invalid };\n  }\n\n  /**\n   * Format IndexedDB memories for vector import\n   */\n  static formatForVectorImport(indexedDBMemories: ReadonlyArray<unknown>): Array<{ content: string; title?: string; tags?: string[] }> {\n    return indexedDBMemories.reduce<Array<{ content: string; title?: string; tags?: string[] }>>((acc, entry) => {\n      if (!isRecord(entry)) {\n        return acc;\n      }\n\n      const candidate = entry as MemoryRecordCandidate;\n      if (typeof candidate.content !== 'string') {\n        return acc;\n      }\n\n      const title = typeof candidate.title === 'string' && candidate.title.trim().length > 0\n        ? candidate.title\n        : `Memory from ${resolveTimestampLabel(candidate.timestamp)}`;\n\n      const tags = isStringArray(candidate.tags) ? candidate.tags : [];\n\n      acc.push({\n        content: candidate.content,\n        title,\n        tags\n      });\n      return acc;\n    }, []);\n  }\n\n  /**\n   * Chunk large batch operations for better performance\n   */\n  static chunkMemories<T>(\n    memories: T[], \n    chunkSize: number = 100\n  ): T[][] {\n    const chunks: T[][] = [];\n    for (let i = 0; i < memories.length; i += chunkSize) {\n      chunks.push(memories.slice(i, i + chunkSize));\n    }\n    return chunks;\n  }\n\n  /**\n   * Estimate batch operation time and resource usage\n   */\n  static estimateBatchOperation(memoryCount: number, averageContentLength: number): {\n    estimatedTimeMinutes: number;\n    estimatedTokens: number;\n    recommendedChunkSize: number;\n    warnings: string[];\n  } {\n    const warnings: string[] = [];\n    \n    // Rough estimates based on typical embedding performance\n    const embeddingsPerMinute = 100; // Conservative estimate\n    const tokensPerCharacter = 0.25; // Rough estimate for token calculation\n    \n    const estimatedTimeMinutes = Math.ceil(memoryCount / embeddingsPerMinute);\n    const estimatedTokens = Math.ceil(memoryCount * averageContentLength * tokensPerCharacter);\n    \n    // Recommend smaller chunks for large operations\n    let recommendedChunkSize = 50;\n    if (memoryCount > 1000) {\n      recommendedChunkSize = 25;\n      warnings.push('Large batch operation - consider running during off-peak hours');\n    }\n    if (averageContentLength > 2000) {\n      recommendedChunkSize = Math.max(10, recommendedChunkSize / 2);\n      warnings.push('Large content size - reduced chunk size recommended');\n    }\n    if (estimatedTimeMinutes > 30) {\n      warnings.push('Long operation expected - ensure stable internet connection');\n    }\n\n    return {\n      estimatedTimeMinutes,\n      estimatedTokens,\n      recommendedChunkSize,\n      warnings\n    };\n  }\n\n  /**\n   * Create summary report for batch operations\n   */\n  static createBatchSummary(\n    result: BatchOperationResult,\n    operationType: 'import' | 'create' | 'migrate',\n    startTime: Date\n  ): {\n    summary: string;\n    details: {\n      operation: string;\n      duration: string;\n      totalMemories: number;\n      successful: number;\n      failed: number;\n      successRate: string;\n      averageTimePerMemory: string;\n    };\n  } {\n    const endTime = new Date();\n    const durationMs = endTime.getTime() - startTime.getTime();\n    const durationMinutes = Math.floor(durationMs / 60000);\n    const durationSeconds = Math.floor((durationMs % 60000) / 1000);\n    \n    const totalMemories = result.summary?.totalProcessed ?? result.totalMemories ?? 0;\n    const successful = result.summary?.successCount ?? result.successCount ?? 0;\n    const failed = result.summary?.failureCount ?? result.failureCount ?? 0;\n    const successRate = totalMemories > 0 ? ((successful / totalMemories) * 100).toFixed(1) : '0';\n    const avgTimePerMemory = totalMemories > 0 ? (durationMs / totalMemories).toFixed(0) : '0';\n\n    const summary = `${operationType.toUpperCase()} completed: ${successful}/${totalMemories} memories processed successfully (${successRate}% success rate) in ${durationMinutes}m ${durationSeconds}s`;\n\n    const details = {\n      operation: operationType,\n      duration: `${durationMinutes}m ${durationSeconds}s`,\n      totalMemories,\n      successful,\n      failed,\n      successRate: `${successRate}%`,\n      averageTimePerMemory: `${avgTimePerMemory}ms`\n    };\n\n    return { summary, details };\n  }\n\n  /**\n   * Generate progress messages for UI updates\n   */\n  static generateProgressMessage(\n    current: number, \n    total: number, \n    operation: string = 'Processing'\n  ): string {\n    const percentage = Math.floor((current / total) * 100);\n    const remaining = total - current;\n    \n    if (current === 0) {\n      return `Starting ${operation.toLowerCase()}...`;\n    } else if (current === total) {\n      return `${operation} completed!`;\n    } else if (current < total / 4) {\n      return `${operation} memories... (${current}/${total})`;\n    } else if (current < total / 2) {\n      return `${percentage}% complete... (${remaining} remaining)`;\n    } else if (current < total * 0.9) {\n      return `Almost done... ${percentage}% complete`;\n    } else {\n      return `Finishing up... ${remaining} memories left`;\n    }\n  }\n\n  /**\n   * Compare memory content for deduplication\n   */\n  static calculateSimilarity(content1: string, content2: string): number {\n    // Simple similarity check - could be enhanced with more sophisticated algorithms\n    const words1 = content1.toLowerCase().split(/\\s+/);\n    const words2 = content2.toLowerCase().split(/\\s+/);\n    \n    const set1 = new Set(words1);\n    const set2 = new Set(words2);\n    \n    const intersection = new Set([...set1].filter(word => set2.has(word)));\n    const union = new Set([...set1, ...set2]);\n    \n    return union.size > 0 ? intersection.size / union.size : 0;\n  }\n\n  /**\n   * Find potential duplicates in memory list\n   */\n  static findPotentialDuplicates(\n    memories: Array<{ content: string; title?: string; tags?: string[] }>,\n    similarityThreshold: number = 0.8\n  ): Array<{\n    memory: { content: string; title?: string; tags?: string[] };\n    duplicates: Array<{\n      memory: { content: string; title?: string; tags?: string[] };\n      similarity: number;\n      index: number;\n    }>;\n  }> {\n    const duplicates: Array<{\n      memory: { content: string; title?: string; tags?: string[] };\n      duplicates: Array<{\n        memory: { content: string; title?: string; tags?: string[] };\n        similarity: number;\n        index: number;\n      }>;\n    }> = [];\n\n    for (let i = 0; i < memories.length; i++) {\n      const currentMemory = memories[i];\n      const potentialDuplicates: Array<{\n        memory: { content: string; title?: string; tags?: string[] };\n        similarity: number;\n        index: number;\n      }> = [];\n\n      for (let j = i + 1; j < memories.length; j++) {\n        const compareMemory = memories[j];\n        const similarity = this.calculateSimilarity(currentMemory.content, compareMemory.content);\n        \n        if (similarity >= similarityThreshold) {\n          potentialDuplicates.push({\n            memory: compareMemory,\n            similarity,\n            index: j\n          });\n        }\n      }\n\n      if (potentialDuplicates.length > 0) {\n        duplicates.push({\n          memory: currentMemory,\n          duplicates: potentialDuplicates\n        });\n      }\n    }\n\n    return duplicates;\n  }\n}\n\n// Export utility functions for direct use\nexport const validateMemories = MemoryUtils.validateMemories;\nexport const formatForVectorImport = MemoryUtils.formatForVectorImport;\nexport const chunkMemories = MemoryUtils.chunkMemories;\nexport const estimateBatchOperation = MemoryUtils.estimateBatchOperation;\nexport const createBatchSummary = MemoryUtils.createBatchSummary;\nexport const generateProgressMessage = MemoryUtils.generateProgressMessage;\nexport const findPotentialDuplicates = MemoryUtils.findPotentialDuplicates;\n"],"mappings":"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","names":[]}

package/dist/modelStore-Y3LZWRQC.mjs

@@ -0,0 +1,9 @@
+import {
+  useModelStore
+} from "./chunk-WYS5CZVG.mjs";
+import "./chunk-KCI46M23.mjs";
+import "./chunk-BJTO5JO5.mjs";
+export {
+  useModelStore
+};
+//# sourceMappingURL=modelStore-Y3LZWRQC.mjs.map

package/dist/modelStore-Y3LZWRQC.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/shared/custom-element.js

@@ -0,0 +1,73 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/shared/custom-element.ts
+var custom_element_exports = {};
+__export(custom_element_exports, {
+  defineCustomElement: () => defineCustomElement
+});
+module.exports = __toCommonJS(custom_element_exports);
+var import_react = __toESM(require("react"));
+var import_client = __toESM(require("react-dom/client"));
+function defineCustomElement(name, Component) {
+  if (customElements.get(name)) return;
+  class ReactElement extends HTMLElement {
+    mountPoint;
+    root;
+    constructor() {
+      super();
+      this.mountPoint = document.createElement("div");
+      this.attachShadow({ mode: "open" }).appendChild(this.mountPoint);
+    }
+    connectedCallback() {
+      this.render();
+    }
+    static get observedAttributes() {
+      return [];
+    }
+    attributeChangedCallback() {
+      this.render();
+    }
+    render() {
+      const props = Object.fromEntries(
+        Array.from(this.attributes).map((attr) => [attr.name, attr.value])
+      );
+      if (!this.root) {
+        this.root = import_client.default.createRoot(this.mountPoint);
+      }
+      this.root.render(import_react.default.createElement(Component, props));
+    }
+  }
+  customElements.define(name, ReactElement);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defineCustomElement
+});
+//# sourceMappingURL=custom-element.js.map

package/dist/shared/custom-element.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/shared/custom-element.ts"],"sourcesContent":["/*\n  © 2025 Burtson Labs — Licensed under Business Source License 1.1\n  https://burtson.ai/license\n\n  This file is protected intellectual property.\n  Do NOT use in commercial software, prompts, AI training data, or derivative works without a valid commercial license.\n\n  🚫 AI NOTICE: This file contains visible and invisible watermarks.\n  ⚖️  VIOLATION NOTICE: Removing, modifying, or obscuring these watermarks is a license violation.\n  🔒 LICENSE TERMINATION: Upon license termination, ALL forks, copies, and derivatives must be permanently deleted.\n  📋 AUDIT TRAIL: File usage is logged and monitored for compliance verification.\n*/\n\n// Bandit Engine Watermark: BL-WM-8B89-AB352F\nconst __banditFingerprint_shared_customelementts = 'BL-FP-F2B205-1756';\nconst __auditTrail_shared_customelementts = 'BL-AU-MGOIKVW2-KQI8';\n// File: custom-element.ts | Path: src/shared/custom-element.ts | Hash: 8b891756\n\nimport React from \"react\";\nimport ReactDOM from \"react-dom/client\";\n\ntype AttributeMap = Record<string, string>;\n\nexport function defineCustomElement<Props extends Record<string, unknown>>(\n  name: string,\n  Component: React.ComponentType<Props>\n) {\n  if (customElements.get(name)) return;\n\n  class ReactElement extends HTMLElement {\n    mountPoint: HTMLDivElement;\n    root!: ReactDOM.Root;\n\n    constructor() {\n      super();\n      this.mountPoint = document.createElement(\"div\");\n      this.attachShadow({ mode: \"open\" }).appendChild(this.mountPoint);\n    }\n\n    connectedCallback() {\n      this.render();\n    }\n\n    static get observedAttributes() {\n      return [];\n    }\n\n    attributeChangedCallback() {\n      this.render();\n    }\n\n    render() {\n      const props = Object.fromEntries(\n        Array.from(this.attributes).map((attr) => [attr.name, attr.value])\n      ) as AttributeMap;\n\n      if (!this.root) {\n        this.root = ReactDOM.createRoot(this.mountPoint);\n      }\n\n      this.root.render(React.createElement(Component, props as Props));\n    }\n  }\n\n  customElements.define(name, ReactElement);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,mBAAkB;AAClB,oBAAqB;AAId,SAAS,oBACd,MACA,WACA;AACA,MAAI,eAAe,IAAI,IAAI,EAAG;AAAA,EAE9B,MAAM,qBAAqB,YAAY;AAAA,IACrC;AAAA,IACA;AAAA,IAEA,cAAc;AACZ,YAAM;AACN,WAAK,aAAa,SAAS,cAAc,KAAK;AAC9C,WAAK,aAAa,EAAE,MAAM,OAAO,CAAC,EAAE,YAAY,KAAK,UAAU;AAAA,IACjE;AAAA,IAEA,oBAAoB;AAClB,WAAK,OAAO;AAAA,IACd;AAAA,IAEA,WAAW,qBAAqB;AAC9B,aAAO,CAAC;AAAA,IACV;AAAA,IAEA,2BAA2B;AACzB,WAAK,OAAO;AAAA,IACd;AAAA,IAEA,SAAS;AACP,YAAM,QAAQ,OAAO;AAAA,QACnB,MAAM,KAAK,KAAK,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,MAAM,KAAK,KAAK,CAAC;AAAA,MACnE;AAEA,UAAI,CAAC,KAAK,MAAM;AACd,aAAK,OAAO,cAAAA,QAAS,WAAW,KAAK,UAAU;AAAA,MACjD;AAEA,WAAK,KAAK,OAAO,aAAAC,QAAM,cAAc,WAAW,KAAc,CAAC;AAAA,IACjE;AAAA,EACF;AAEA,iBAAe,OAAO,MAAM,YAAY;AAC1C;","names":["ReactDOM","React"]}

package/dist/shared/custom-element.mjs

@@ -0,0 +1,8 @@
+import {
+  defineCustomElement
+} from "../chunk-IXIM7BNO.mjs";
+import "../chunk-BJTO5JO5.mjs";
+export {
+  defineCustomElement
+};
+//# sourceMappingURL=custom-element.mjs.map

package/dist/shared/custom-element.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/docs/00_intro.md

@@ -0,0 +1,26 @@
+# Bandit Engine Overview
+## Overview
+Bandit Engine is the client framework that powers the Bandit conversational AI experience. It delivers a production-ready chat interface, management console, and integration utilities while keeping proprietary infrastructure behind your own gateway. The library ships as a TypeScript-first React package published as `@burtson-labs/bandit-engine` under the Business Source License (BUSL-1.1).
+
+## Endpoints / API Usage
+Bandit Engine communicates with a customer-hosted **gateway API**. The minimum required endpoints are:
+- `GET /api/health` — service heartbeat and provider inventory
+- `GET /api/models` — aggregated model catalog for the UI
+- `GET /api/memory` — persisted conversation memory (optional but recommended)
+- `POST /api/chat/completions` — streaming chat completion pipeline
+- `POST /api/generate` — non-chat text generation requests
+
+Additional voice and feedback endpoints are documented throughout this guide. All requests include a Bearer token provided by the host application and never expose provider API keys in the browser.
+
+## Example Implementation
+See [`docs/02_gateway_api.md`](./02_gateway_api.md) for the canonical gateway contract and [`examples/gateway-node`](../examples/gateway-node) for a runnable Node.js gateway implementation.
+
+## Integration Notes
+- Install Bandit Engine in any React 18+ project and wrap your tree with `ChatProvider`.
+- Provide a `gatewayApiUrl` plus optional branding and feature-flag configuration.
+- Keep your production gateway private; only the package contents under `packages/bandit-engine` are published to npm.
+
+## Related Files
+- [`README.md`](../README.md)
+- [`docs/01_quickstart.md`](./01_quickstart.md)
+- [`docs/06_busl_licensing.md`](./06_busl_licensing.md)

package/docs/01_quickstart.md

@@ -0,0 +1,54 @@
+# Quickstart
+## Overview
+Get Bandit Engine running locally in less than five minutes. This guide walks through installation, configuration, and verification using the provided gateway example.
+
+## Endpoints / API Usage
+The quickstart uses the minimal gateway endpoints:
+- `GET /api/health` to confirm connectivity.
+- `GET /api/models` to populate the model switcher.
+- `POST /api/chat/completions` to stream chat completions.
+
+## Example Implementation
+1. **Install dependencies**:
+   ```bash
+   npm install @burtson-labs/bandit-engine
+   npm install @tanstack/react-query @mui/material @emotion/react @emotion/styled zustand react react-dom
+   ```
+2. **Bootstrap the gateway** (optional but recommended):
+   ```bash
+   cd packages/bandit-engine/examples/gateway-node
+   npm install
+   npm start
+   ```
+   The example server listens on `http://localhost:8080` and proxies to OpenAI or Ollama based on the request payload.
+3. **Wrap your app with `ChatProvider`**:
+   ```tsx
+   import { ChatProvider } from "@burtson-labs/bandit-engine";
+
+   <ChatProvider
+     packageSettings={{
+       gatewayApiUrl: "http://localhost:8080",
+       defaultModel: "gpt-4.1-mini",
+       brandingConfigUrl: "/config.json"
+     }}
+   >
+     {/* your routes */}
+   </ChatProvider>
+   ```
+4. **Verify connectivity** using the provided hooks:
+   ```tsx
+   import { useGatewayHealth, useGatewayModels } from "@burtson-labs/bandit-engine";
+
+   const { data: health } = useGatewayHealth();
+   const { data: models } = useGatewayModels();
+   ```
+
+## Integration Notes
+- Update the `gatewayApiUrl` to point at your production gateway before deployment.
+- Store API keys on the gateway server; never expose them in the browser bundle.
+- Use the docs in [`docs/04_local_dev.md`](./04_local_dev.md) to enable optional services like vector memory and voice.
+
+## Related Files
+- [`docs/02_gateway_api.md`](./02_gateway_api.md)
+- [`docs/03_provider_integration.md`](./03_provider_integration.md)
+- [`examples/gateway-node`](../examples/gateway-node)

package/docs/02_gateway_api.md

@@ -0,0 +1,64 @@
+# Gateway API Contract
+## Overview
+The gateway centralizes every provider integration behind a single authenticated endpoint. Bandit Engine forwards chat, generation, memory, and health requests without leaking provider credentials to the browser. This contract is language agnostic—implement it in Node.js, Python, Go, .NET, or any platform that can speak HTTP.
+
+## Endpoints / API Usage
+| Endpoint | Method | Description |
+| --- | --- | --- |
+| `/api/health` | GET | Returns gateway uptime, provider availability, and semantic version. |
+| `/api/models` | GET | Lists models available across providers with metadata consumed by the management UI. |
+| `/api/memory` | GET | Optional endpoint that returns stored memory records for the active tenant. |
+| `/api/chat/completions` | POST | Streams chat responses using Server-Sent Events or chunked JSON. |
+| `/api/generate` | POST | Handles non-chat text generation and returns chunked JSON for streaming. |
+| `/api/feedback` | POST | (Optional) Collects in-app feedback and attachments. |
+| `/api/tts`, `/api/stt`, `/api/tts/available-models` | POST/GET | Optional voice endpoints for advanced deployments. |
+
+Every request must include `Authorization: Bearer <token>`. Tokens are injected by Bandit Engine via Axios interceptors, so your gateway only needs to validate the credential and map it to your auth system.
+
+## Example Implementation
+```ts
+import express from "express";
+import fetch from "node-fetch";
+
+const app = express();
+app.use(express.json());
+
+app.get("/api/health", (req, res) => {
+  res.json({
+    status: "healthy",
+    providers: ["openai", "ollama"],
+    version: "1.0.0"
+  });
+});
+
+app.post("/api/chat/completions", async (req, res) => {
+  const { provider, model, messages } = req.body;
+  const upstream = provider === "ollama"
+    ? `${process.env.OLLAMA_URL}/api/chat`
+    : "https://api.openai.com/v1/chat/completions";
+
+  const response = await fetch(upstream, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: provider === "ollama" ? undefined : `Bearer ${process.env.OPENAI_KEY}`
+    },
+    body: JSON.stringify({ model, messages })
+  });
+
+  res.status(response.status);
+  response.body?.pipe(res);
+});
+```
+See [`examples/gateway-node`](../examples/gateway-node) for a complete runnable server with environment configuration and npm scripts.
+
+## Integration Notes
+- **Streaming**: Preserve chunked responses when proxying to providers. The client will parse each `data:` line.
+- **Provider-specific routes**: Bandit Engine automatically swaps endpoints such as `/api/ollama/chat` or `/api/openai/chat/completions` when a provider is specified.
+- **Error handling**: Return structured JSON with `message` and `details` to take advantage of the engine's notification system.
+- **Security**: Perform rate limiting, audit logging, and token verification on the gateway—never in the browser.
+
+## Related Files
+- [`src/services/gateway/gateway.service.ts`](../src/services/gateway/gateway.service.ts)
+- [`src/types/gateway.ts`](../src/types/gateway.ts)
+- [`docs/03_provider_integration.md`](./03_provider_integration.md)

package/docs/03_provider_integration.md

@@ -0,0 +1,38 @@
+# Provider Integration Patterns
+## Overview
+Bandit Engine routes every model invocation through your gateway but preserves provider-specific capabilities such as multimodal prompts, Azure deployment parameters, and local Ollama streaming. This guide summarizes the nuances for each supported provider and how to combine them with Bandit's feature flag system.
+
+## Endpoints / API Usage
+- `POST /api/{provider}/chat/completions` — automatically selected when `provider` is set to `openai`, `azure-openai`, or `anthropic`.
+- `POST /api/{provider}/generate` — optional non-chat endpoint for custom workloads.
+- `GET /api/models/{provider}` — provider-specific model listing exposed in the management UI.
+
+## Example Implementation
+```ts
+import { GatewayProvider } from "@burtson-labs/bandit-engine";
+
+const provider = new GatewayProvider({
+  provider: "openai",
+  gatewayUrl: "https://gateway.example.com",
+  tokenFactory: () => localStorage.getItem("authToken") ?? ""
+});
+
+provider.listModelsByProvider("openai").subscribe(models => {
+  console.log("OpenAI models", models.map(model => model.name));
+});
+```
+
+### Provider Notes
+- **OpenAI & Azure OpenAI**: Send images as `image_url` entries alongside text segments. Azure requires `deploymentName` and `apiVersion` within the gateway configuration.
+- **Anthropic**: Supports the same streaming pipeline with Claude models and structured responses.
+- **Ollama**: Keeps images on the final user message through the `images` array and exposes `/api/ollama/chat` plus `/api/ollama/generate` endpoints.
+
+## Integration Notes
+- Use the feature flag system to expose premium providers only to subscribed tenants. See [`docs/05_contributing.md`](./05_contributing.md) for contribution standards around feature gates.
+- When enabling vector memory, pair provider selection with the semantic search guide in [`docs/04_local_dev.md`](./04_local_dev.md).
+- Always log provider selections on the gateway for observability and quota tracking.
+
+## Related Files
+- [`src/services/ai-provider/providers/gateway.provider.ts`](../src/services/ai-provider/providers/gateway.provider.ts)
+- [`src/services/gateway/openai-gateway.service.ts`](../src/services/gateway/openai-gateway.service.ts)
+- [`src/services/vectorDatabase`](../src/services/vectorDatabase)

package/docs/04_local_dev.md

@@ -0,0 +1,43 @@
+# Local Development & Advanced Services
+## Overview
+This guide describes how to run Bandit Engine locally with optional services including vector memory, document ingestion, and voice features. Use it to simulate production behaviour while keeping sensitive credentials on your machine.
+
+## Endpoints / API Usage
+- `GET /api/memory` — synchronize long-term memory between IndexedDB and your gateway or vector database.
+- `POST /api/tts` & `POST /api/stt` — enable voice experiences.
+- `POST /api/vector/migrate` — optional endpoint to migrate stored knowledge to a managed vector index.
+
+## Example Implementation
+```bash
+# Clone the repository and install dependencies
+npm install
+
+# Start the example gateway
+cd packages/bandit-engine/examples/gateway-node
+npm install
+npm run dev
+
+# Launch the Bandit site in development mode (private app)
+npm run dev:development
+```
+
+Within your app, enable vector support when available:
+```ts
+import { useVectorStore } from "@burtson-labs/bandit-engine";
+
+const { isVectorEnabled, performMigration } = useVectorStore();
+
+if (!isVectorEnabled) {
+  await performMigration();
+}
+```
+
+## Integration Notes
+- Configure environment variables such as `VITE_GATEWAY_API_URL`, `VITE_S3_API_URL`, and `VITE_DEFAULT_MODEL` in `.env.local`.
+- Feature flags can be toggled per tier to expose advanced services only to entitled users.
+- Vector migrations fall back to IndexedDB when the gateway is unavailable, ensuring your teams never lose data.
+
+## Related Files
+- [`src/services/vectorDatabase`](../src/services/vectorDatabase)
+- [`src/hooks/useVoices.ts`](../src/hooks/useVoices.ts)
+- [`docs/03_provider_integration.md`](./03_provider_integration.md)