npm - @burtson-labs/bandit-engine - Versions diffs - 2.0.8 - Mend

@burtson-labs/bandit-engine 2.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (184) hide show

package/docs/api_reference/index.html ADDED Viewed

@@ -0,0 +1,756 @@
+<!DOCTYPE html><html class="default" lang="en"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@burtson-labs/bandit-engine</title><meta name="description" content="Documentation for @burtson-labs/bandit-engine"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@burtson-labs/bandit-engine</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@burtson-labs/bandit-engine</h1></div><div class="tsd-panel tsd-typography"><p><a href="https://burtson.ai"><img src="https://cdn.burtson.ai/logos/burtson-labs-logo-alt.png" alt="Burtson Labs Logo" width="140" /></a></p>
+<p><a href="https://www.npmjs.com/package/@burtson-labs/bandit-engine" target="_blank" class="external"><img src="https://img.shields.io/npm/v/%40burtson-labs%2Fbandit-engine" alt="npm version"></a>
+<a href="https://www.typescriptlang.org/" target="_blank" class="external"><img src="https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&amp;logoColor=white" alt="TypeScript"></a>
+<a href="./LICENSE"><img src="https://img.shields.io/badge/License-BUSL--1.1-red" alt="License: BUSL-1.1"></a></p>
+<blockquote>
+<p><strong>Welcome to the Bandit Engine – an AI chat interface toolkit from Burtson Labs.</strong>
+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.</p>
+</blockquote>
+<p>📚 Looking for docs? Start with the <a href="media/README.md">documentation index</a> or jump straight to the <a href="media/02_gateway_api.md">gateway contract</a>.</p>
+<p>🧪 Want to kick the tires? Clone the <a href="media/README-1.md">Node.js gateway example</a> for a ready-to-run backend.</p>
+<a id="md:⚡-cli-quick-start" class="tsd-anchor"></a><h2 class="tsd-anchor-link">⚡ CLI Quick Start<a href="#md:⚡-cli-quick-start" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Want a working playground instantly? Scaffold a Bandit app and gateway in one command:</p>
+<pre><code class="bash"><span class="hl-0">npx</span><span class="hl-1"> </span><span class="hl-2">@burtson-labs/bandit-engine</span><span class="hl-1"> </span><span class="hl-2">create</span><span class="hl-1"> </span><span class="hl-2">my-bandit-app</span>
+</code><button type="button">Copy</button></pre>
+<p><img src="https://cdn.burtson.ai/images/cli-quickstart.jpg" alt="Bandit CLI quickstart walkthrough"></p>
+<p>What you get out of the box:</p>
+<ul>
+<li>Vite + React project wired with <code>Chat</code>, <code>ChatModal</code>, and <code>ChatProvider</code></li>
+<li>Express gateway that proxies OpenAI or Ollama behind <code>/api</code></li>
+<li>Branding + persona config in <code>public/config.json</code>, ready for your logo or prompts</li>
+</ul>
+<p>Customize the output with options such as:</p>
+<ul>
+<li><code>--branding-text &quot;Bandit Support&quot;</code> to set the assistant display name</li>
+<li><code>--frontend-port 5190</code> to change the Vite dev server port</li>
+<li><code>--gateway-port 9090</code> to run the sample gateway on an alternate port</li>
+<li><code>--yes</code> / <code>--skip-prompts</code> to accept defaults non-interactively</li>
+<li><code>--force</code> to overwrite a non-empty directory</li>
+</ul>
+<blockquote>
+<p>🗝️ The generated project includes an <code>.npmrc</code> that targets <code>https://npm.pkg.github.com/</code> and expects a <code>GITHUB_NPM_TOKEN</code> environment variable. Run <code>npm login --registry=https://npm.pkg.github.com --scope=@burtson-labs</code> (or export <code>GITHUB_NPM_TOKEN</code>) before installing dependencies.</p>
+</blockquote>
+<p>Check out the <a href="media/05_cli_quickstart.md">CLI quick start guide</a> for the full walkthrough, option matrix, and project anatomy.</p>
+<a id="md:cli-options" class="tsd-anchor"></a><h3 class="tsd-anchor-link">CLI Options<a href="#md:cli-options" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><table>
+<thead>
+<tr>
+<th>Flag</th>
+<th>Description</th>
+<th>Example</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><code>--branding-text &lt;text&gt;</code></td>
+<td>Set the assistant name shown in the UI.</td>
+<td><code>--branding-text &quot;Bandit Support&quot;</code></td>
+</tr>
+<tr>
+<td><code>--frontend-port &lt;port&gt;</code></td>
+<td>Change the Vite dev server port (default <code>5183</code>).</td>
+<td><code>--frontend-port 5190</code></td>
+</tr>
+<tr>
+<td><code>--gateway-port &lt;port&gt;</code></td>
+<td>Change the sample gateway port (default <code>8080</code>).</td>
+<td><code>--gateway-port 9090</code></td>
+</tr>
+<tr>
+<td><code>--yes</code>, <code>--skip-prompts</code></td>
+<td>Accept defaults without interactive questions.</td>
+<td><code>--yes</code></td>
+</tr>
+<tr>
+<td><code>--force</code></td>
+<td>Overwrite the target directory if it already exists.</td>
+<td><code>--force</code></td>
+</tr>
+</tbody>
+</table>
+<p>The CLI prints next steps (install, copy <code>.env</code>, run dev server) once scaffolding completes, so you can copy-paste and ship immediately.</p>
+<a id="md:🛠️-getting-started--plug--play-ai" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🛠️ Getting Started – Plug &amp; Play AI<a href="#md:🛠️-getting-started--plug--play-ai" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ol>
+<li><strong>Add a config.json</strong> to your public folder (or host it on a CDN) and point <code>brandingConfigUrl</code> at it:</li>
+</ol>
+<p><em>Host it locally in <code>/public</code> or serve it from a CDN and reference it via <code>brandingConfigUrl</code>.</em></p>
+<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;theme&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;bandit-dark&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;branding&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-3">&quot;brandingText&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;Bandit Chat Premium Beta&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-3">&quot;logoBase64&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;&quot;</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;models&quot;</span><span class="hl-1">: [</span><br/><span class="hl-1">    { </span><span class="hl-3">&quot;name&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;Bandit-Core&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;General purpose model&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1">    { </span><span class="hl-3">&quot;name&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;Bandit-Muse&quot;</span><span class="hl-1">, </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;Creative writing model&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">  ]</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<p>No bloated setup. No magic strings. Just drop in your <code>config.json</code>, hook up a few props, and let your AI speak for itself.</p>
+<ol start="2">
+<li><strong>Wrap your entire app with <code>ChatProvider</code> to enable Bandit features globally:</strong></li>
+</ol>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> </span><span class="hl-5">React</span><span class="hl-1"> </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;react&quot;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> </span><span class="hl-5">ReactDOM</span><span class="hl-1"> </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;react-dom/client&quot;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> </span><span class="hl-5">App</span><span class="hl-1"> </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;./App&quot;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">CssBaseline</span><span class="hl-1">, </span><span class="hl-5">ThemeProvider</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@mui/material&quot;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">banditDarkTheme</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;./theme/banditTheme&quot;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">AppInitializer</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;./app-initializer&quot;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">ChatProvider</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&quot;@burtson-labs/bandit-engine&quot;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">chatPackageSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-8">// New Gateway Provider Configuration (Recommended)</span><br/><span class="hl-1">  </span><span class="hl-5">aiProvider:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;gateway&quot;</span><span class="hl-1"> </span><span class="hl-4">as</span><span class="hl-1"> </span><span class="hl-6">const</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">gatewayUrl:</span><span class="hl-1"> </span><span class="hl-4">import</span><span class="hl-1">.</span><span class="hl-5">meta</span><span class="hl-1">.</span><span class="hl-5">env</span><span class="hl-1">.</span><span class="hl-7">VITE_GATEWAY_API_URL</span><span class="hl-1">!,</span><br/><span class="hl-1">    </span><span class="hl-5">provider:</span><span class="hl-1"> </span><span class="hl-2">&quot;openai&quot;</span><span class="hl-1"> </span><span class="hl-8">// Backend: openai, azure-openai, anthropic, ollama</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Legacy Ollama Configuration (Still Supported)</span><br/><span class="hl-1">  </span><span class="hl-8">// ollamaUrl: import.meta.env.VITE_OLLAMA_URL!,</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Model Configuration</span><br/><span class="hl-1">  </span><span class="hl-5">defaultModel:</span><span class="hl-1"> </span><span class="hl-4">import</span><span class="hl-1">.</span><span class="hl-5">meta</span><span class="hl-1">.</span><span class="hl-5">env</span><span class="hl-1">.</span><span class="hl-7">VITE_DEFAULT_MODEL</span><span class="hl-1">!,</span><br/><span class="hl-1">  </span><span class="hl-5">fallbackModel:</span><span class="hl-1"> </span><span class="hl-4">import</span><span class="hl-1">.</span><span class="hl-5">meta</span><span class="hl-1">.</span><span class="hl-5">env</span><span class="hl-1">.</span><span class="hl-7">VITE_FALLBACK_MODEL</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-5">gatewayApiUrl:</span><span class="hl-1"> </span><span class="hl-4">import</span><span class="hl-1">.</span><span class="hl-5">meta</span><span class="hl-1">.</span><span class="hl-5">env</span><span class="hl-1">.</span><span class="hl-7">VITE_GATEWAY_API_URL</span><span class="hl-1">!,</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Branding and optional overrides</span><br/><span class="hl-1">  </span><span class="hl-5">brandingConfigUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;/config.json&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-8">// s3ApiUrl: import.meta.env.VITE_S3_API_URL,</span><br/><span class="hl-1">  </span><span class="hl-8">// homeUrl: &quot;https://yourapp.com&quot;,</span><br/><span class="hl-1">  </span><span class="hl-8">// feedbackEmail: &quot;feedback@yourapp.com&quot;,</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-5">ReactDOM</span><span class="hl-1">.</span><span class="hl-0">createRoot</span><span class="hl-1">(</span><span class="hl-5">document</span><span class="hl-1">.</span><span class="hl-0">getElementById</span><span class="hl-1">(</span><span class="hl-2">&quot;root&quot;</span><span class="hl-1">)!).</span><span class="hl-0">render</span><span class="hl-1">(</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-10">React.StrictMode</span><span class="hl-9">&gt;</span><br/><span class="hl-1">    </span><span class="hl-9">&lt;</span><span class="hl-10">ThemeProvider</span><span class="hl-1"> </span><span class="hl-11">theme</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-5">banditDarkTheme</span><span class="hl-6">}</span><span class="hl-9">&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-10">CssBaseline</span><span class="hl-1"> </span><span class="hl-9">/&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-10">AppInitializer</span><span class="hl-1"> </span><span class="hl-9">/&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-10">ChatProvider</span><span class="hl-1"> </span><span class="hl-11">packageSettings</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-5">chatPackageSettings</span><span class="hl-6">}</span><span class="hl-9">&gt;</span><br/><span class="hl-1">        </span><span class="hl-9">&lt;</span><span class="hl-10">App</span><span class="hl-1"> </span><span class="hl-9">/&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;/</span><span class="hl-10">ChatProvider</span><span class="hl-9">&gt;</span><br/><span class="hl-1">    </span><span class="hl-9">&lt;/</span><span class="hl-10">ThemeProvider</span><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;/</span><span class="hl-10">React.StrictMode</span><span class="hl-9">&gt;</span><br/><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+<blockquote>
+<p>🚀 Within minutes, you'll have a fully functional chat interface that can read, speak, and reason – all brandable, themeable, and extensible.</p>
+</blockquote>
+<a id="md:🔄-quick-provider-setup" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🔄 Quick Provider Setup<a href="#md:🔄-quick-provider-setup" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p><strong>Option 1: Gateway Provider (Recommended)</strong></p>
+<pre><code class="tsx"><span class="hl-8">// Most secure - API keys stay on your backend</span><br/><span class="hl-8">// Your gateway can be built in ANY language: Node.js, Python, .NET, Java, PHP, Go, etc.</span><br/><span class="hl-12">aiProvider</span><span class="hl-1">: {</span><br/><span class="hl-1">  </span><span class="hl-12">type</span><span class="hl-1">: </span><span class="hl-2">&quot;gateway&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-12">gatewayUrl</span><span class="hl-1">: </span><span class="hl-2">&quot;https://your-api-gateway.com&quot;</span><span class="hl-1">, </span><span class="hl-8">// Your backend API</span><br/><span class="hl-1">  </span><span class="hl-12">provider</span><span class="hl-1">: </span><span class="hl-2">&quot;openai&quot;</span><span class="hl-1"> </span><span class="hl-8">// Specify which AI provider to use</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Option 2: Direct Provider (Development)</strong></p>
+<pre><code class="tsx"><span class="hl-8">// Quick start - API keys in frontend (not for production)</span><br/><span class="hl-12">aiProvider</span><span class="hl-1">: {</span><br/><span class="hl-1">  </span><span class="hl-12">type</span><span class="hl-1">: </span><span class="hl-2">&quot;ollama&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-12">baseUrl</span><span class="hl-1">: </span><span class="hl-2">&quot;http://localhost:11434&quot;</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Gateway Requirements:</strong> Your backend needs to implement these endpoints:</p>
+<ul>
+<li><code>GET /api/health</code> - Health check</li>
+<li><code>POST /api/chat/completions</code> - Chat completions</li>
+<li><code>POST /api/generate</code> - Text generation</li>
+<li><code>POST /api/tts</code> - Text-to-Speech (optional, for voice features)</li>
+<li><code>GET /api/tts/available-models</code> - TTS model listing (optional)</li>
+<li><code>POST /api/stt</code> - Speech-to-Text (optional, for voice input)</li>
+</ul>
+<blockquote>
+<p><strong>⚠️ Important:</strong> The Bandit Engine automatically routes to provider-specific endpoints:</p>
+<ul>
+<li><strong>Ollama</strong> → <code>/api/ollama/chat</code> (native Ollama format)</li>
+<li><strong>OpenAI/Azure/Anthropic</strong> → <code>/api/{provider}/chat/completions</code> (OpenAI format)</li>
+<li><strong>TTS/STT</strong> → Technology-agnostic endpoints that work with any backend implementation</li>
+</ul>
+</blockquote>
+<a id="md:ollama-env-setup" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Ollama .env Setup<a href="#md:ollama-env-setup" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>To run the quickstart purely against an Ollama daemon:</p>
+<ol>
+<li>
+<p>Install (or build) the models you want to expose, e.g.:</p>
+<pre><code class="bash"><span class="hl-0">ollama</span><span class="hl-1"> </span><span class="hl-2">pull</span><span class="hl-1"> </span><span class="hl-2">llava:latest</span><br/><span class="hl-0">ollama</span><span class="hl-1"> </span><span class="hl-2">pull</span><span class="hl-1"> </span><span class="hl-2">gemma2:9b-instruct</span>
+</code><button type="button">Copy</button></pre>
+</li>
+<li>
+<p>Edit the generated <code>.env</code> and point both the frontend and gateway at Ollama:</p>
+<pre><code class="ini"># Frontend
+VITE_GATEWAY_PROVIDER=ollama
+VITE_DEFAULT_MODEL=llava:latest        # any model installed on your Ollama box
+VITE_FALLBACK_MODEL=gemma2:9b-instruct # optional, but handy for text-only fallbacks
+# Gateway / server
+OLLAMA_URL=http://localhost:11434      # or the remote daemon address
+</code><button type="button">Copy</button></pre>
+<p>Set <code>VITE_DEFAULT_MODEL</code> / <code>VITE_FALLBACK_MODEL</code> to the exact Ollama model tags you have available (<code>gemma</code>, <code>llava</code>, <code>moondream</code>, or your own custom builds). Bandit automatically detects multimodal Ollama models, so setting <code>llava</code>, <code>moondream</code>, or other vision-capable variants enables image understanding with no extra code.</p>
+</li>
+</ol>
+<a id="md:🎤-voice-services-ttsstt" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🎤 Voice Services (TTS/STT)<a href="#md:🎤-voice-services-ttsstt" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The Bandit Engine supports Text-to-Speech (TTS) and Speech-to-Text (STT) through your gateway API. These services are <strong>technology-agnostic</strong> - you can implement them using any backend technology:</p>
+<p><strong>TTS Endpoint (<code>POST /api/tts</code>)</strong></p>
+<ul>
+<li><strong>Input</strong>: <code>{ text: string, voice?: string, speed?: number }</code></li>
+<li><strong>Output</strong>: Audio file (MP3, WAV, etc.) or streaming audio</li>
+<li><strong>Compatible with</strong>: OpenAI TTS, Azure Speech, Google Cloud TTS, AWS Polly, local TTS servers, or custom implementations</li>
+</ul>
+<p><strong>STT Endpoint (<code>POST /api/stt</code>)</strong></p>
+<ul>
+<li><strong>Input</strong>: Audio file upload (multipart/form-data)</li>
+<li><strong>Output</strong>: <code>{ text: string }</code> or <code>{ transcription: string }</code></li>
+<li><strong>Compatible with</strong>: OpenAI Whisper, Azure Speech, Google Speech, AWS Transcribe, local Whisper servers, or custom implementations</li>
+</ul>
+<p><strong>Service Discovery (<code>GET /api/tts/available-models</code>)</strong></p>
+<ul>
+<li><strong>Output</strong>: <code>{ models: string[], defaultModel: string, fallbackModel: string }</code></li>
+<li>Used for automatic service availability detection and voice model selection</li>
+</ul>
+<p>See the <a href="media/02_gateway_api.md">Gateway API Contract</a> for complete implementation examples in multiple languages.</p>
+<p>Use the Management interface to switch providers anytime or migrate from direct to gateway setup.</p>
+<ol start="3">
+<li><strong>Development</strong></li>
+</ol>
+<ul>
+<li>Use <code>npm link</code> or a monorepo workspace to test locally before publishing.</li>
+<li>Build with <code>tsup</code>.</li>
+</ul>
+<hr>
+<a id="md:🧩-consuming-the-components" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🧩 Consuming the Components<a href="#md:🧩-consuming-the-components" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Once you've wrapped your app with <code>ChatProvider</code>, you can selectively integrate Bandit's components as needed:</p>
+<ul>
+<li><code>&lt;Chat /&gt;</code>: The main chat interface, designed to be used on a dedicated page or embedded into your product.</li>
+<li><code>&lt;Management /&gt;</code>: A full-featured admin and model configuration UI. This should not be on the same page as <code>&lt;Chat /&gt;</code>. Use this to allow authenticated users to manage themes, models, and embedded knowledge.</li>
+<li><code>&lt;ChatModal /&gt;</code>: A flexible, mobile-friendly modal that can be launched anywhere in your app for quick AI interactions. Features include:
+<ul>
+<li><strong>Chat Control Center</strong>: Built-in conversation management, voice model switching, and memory controls</li>
+<li><strong>Context Switching</strong>: Toggle between local session and saved conversation history</li>
+<li><strong>Voice Integration</strong>: Voice model selection with real-time preview (when TTS is configured)</li>
+<li><strong>Navigation</strong>: Seamless transition from modal to full chat interface</li>
+<li><strong>Auto-theming</strong>: Automatically uses the theme configured in the Management interface</li>
+</ul>
+</li>
+</ul>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Chat</span><span class="hl-1">, </span><span class="hl-5">Management</span><span class="hl-1">, </span><span class="hl-5">ChatModal</span><span class="hl-1">, </span><span class="hl-5">ChatProvider</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">useState</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;react&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">function</span><span class="hl-1"> </span><span class="hl-0">YourPage</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> [</span><span class="hl-7">isModalOpen</span><span class="hl-1">, </span><span class="hl-7">setIsModalOpen</span><span class="hl-1">] = </span><span class="hl-0">useState</span><span class="hl-1">(</span><span class="hl-6">false</span><span class="hl-1">);</span><br/><br/><span class="hl-1">  </span><span class="hl-4">return</span><span class="hl-1"> (</span><br/><span class="hl-1">    </span><span class="hl-9">&lt;&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-10">Chat</span><span class="hl-1"> </span><span class="hl-9">/&gt;</span><br/><span class="hl-1">      </span><span class="hl-6">{</span><span class="hl-8">/* Use &lt;Management /&gt; on a separate admin route with access controls */</span><span class="hl-6">}</span><br/><span class="hl-1">      </span><br/><span class="hl-1">      </span><span class="hl-6">{</span><span class="hl-8">/* Trigger the AI modal anywhere in your app */</span><span class="hl-6">}</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-13">button</span><span class="hl-1"> </span><span class="hl-11">onClick</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-14">() </span><span class="hl-6">=&gt;</span><span class="hl-14"> </span><span class="hl-0">setIsModalOpen</span><span class="hl-14">(</span><span class="hl-6">true</span><span class="hl-14">)</span><span class="hl-6">}</span><span class="hl-9">&gt;</span><br/><span class="hl-1">        Ask AI</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;/</span><span class="hl-13">button</span><span class="hl-9">&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-10">ChatModal</span><span class="hl-1"> </span><br/><span class="hl-1">        </span><span class="hl-11">open</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-5">isModalOpen</span><span class="hl-6">}</span><span class="hl-1"> </span><br/><span class="hl-1">        </span><span class="hl-11">onClose</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-14">() </span><span class="hl-6">=&gt;</span><span class="hl-14"> </span><span class="hl-0">setIsModalOpen</span><span class="hl-14">(</span><span class="hl-6">false</span><span class="hl-14">)</span><span class="hl-6">}</span><br/><span class="hl-1">      </span><span class="hl-9">/&gt;</span><br/><span class="hl-1">    </span><span class="hl-9">&lt;/&gt;</span><br/><span class="hl-1">  );</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:🛠️-utility-functions--hooks" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🛠️ Utility Functions &amp; Hooks<a href="#md:🛠️-utility-functions--hooks" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Bandit Engine exports several utility functions for advanced use cases:</p>
+<a id="md:debug-logger" class="tsd-anchor"></a><h4 class="tsd-anchor-link">Debug Logger<a href="#md:debug-logger" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>Replace console statements with structured logging:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">debugLogger</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">debugLogger</span><span class="hl-1">.</span><span class="hl-0">info</span><span class="hl-1">(</span><span class="hl-2">&#39;Chat session started&#39;</span><span class="hl-1">);</span><br/><span class="hl-5">debugLogger</span><span class="hl-1">.</span><span class="hl-0">warn</span><span class="hl-1">(</span><span class="hl-2">&#39;Fallback model selected&#39;</span><span class="hl-1">);</span><br/><span class="hl-5">debugLogger</span><span class="hl-1">.</span><span class="hl-0">error</span><span class="hl-1">(</span><span class="hl-2">&#39;Connection failed&#39;</span><span class="hl-1">, { </span><span class="hl-5">error:</span><span class="hl-1"> </span><span class="hl-5">details</span><span class="hl-1"> });</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:ai-prompt-utilities" class="tsd-anchor"></a><h4 class="tsd-anchor-link">AI Prompt Utilities<a href="#md:ai-prompt-utilities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>Access the same prompt functions used internally:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><br/><span class="hl-1">  </span><span class="hl-5">generateConversationStarters</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">detectMessageMood</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">detectUserInterestAndExcitement</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">summarizeDocument</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">determineRelevantDocuments</span><span class="hl-1"> </span><br/><span class="hl-1">} </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// Generate conversation starters</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">starters</span><span class="hl-1"> = </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-0">generateConversationStarters</span><span class="hl-1">({</span><br/><span class="hl-1">  </span><span class="hl-5">limit:</span><span class="hl-1"> </span><span class="hl-15">5</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">topicOfInterest:</span><span class="hl-1"> </span><span class="hl-2">&quot;technology, coding, AI&quot;</span><br/><span class="hl-1">});</span><br/><br/><span class="hl-8">// Detect user mood for adaptive responses</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">mood</span><span class="hl-1"> = </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-0">detectMessageMood</span><span class="hl-1">(</span><span class="hl-2">&quot;I&#39;m so excited about this project!&quot;</span><span class="hl-1">);</span><br/><span class="hl-8">// Returns: &quot;high&quot; | &quot;neutral&quot; | &quot;low&quot;</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:datetime-context" class="tsd-anchor"></a><h4 class="tsd-anchor-link">Date/Time Context<a href="#md:datetime-context" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>All AI interactions automatically include current date/time context to improve relevance and accuracy of responses.</p>
+<blockquote>
+<p>⚠️ <strong>Important:</strong> Each component (<code>&lt;Chat /&gt;</code>, <code>&lt;Management /&gt;</code>, <code>&lt;ChatModal /&gt;</code>) <strong>must</strong> be wrapped in a <code>ChatProvider</code> to function correctly.<br>
+In React, you can wrap your app once at the root.<br>
+In Angular or Vue, you may need to wrap each usage with a <code>&lt;bandit-chat-provider&gt;</code> tag and pass settings each time until full reactive context is supported.</p>
+</blockquote>
+<hr>
+<a id="md:🎛️-chat-control-center-chatmodal-feature" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🎛️ Chat Control Center (ChatModal Feature)<a href="#md:🎛️-chat-control-center-chatmodal-feature" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>The <code>&lt;ChatModal /&gt;</code> includes a comprehensive Chat Control Center that provides advanced session management:</p>
+<a id="md:🔧-core-features" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🔧 Core Features<a href="#md:🔧-core-features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>Session vs. Conversation Context</strong>: Toggle between local modal session and persistent conversation history</li>
+<li><strong>Voice Model Selection</strong>: Real-time voice switching with preview greetings (requires TTS gateway configuration)</li>
+<li><strong>Memory Management</strong>: View and manage AI personal memory entries</li>
+<li><strong>Conversation Navigation</strong>: Seamless transition from modal to full chat interface</li>
+<li><strong>Manual Refresh</strong>: Force reload of conversations and voice models for troubleshooting</li>
+</ul>
+<a id="md:🎤-voice-integration" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🎤 Voice Integration<a href="#md:🎤-voice-integration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>When your gateway API includes TTS endpoints, the Chat Control Center provides:</p>
+<ul>
+<li><strong>Voice Selection Dropdown</strong>: Choose from available voice models (e.g., Mark, Amy, Kathleen, Lessac, Ryan)</li>
+<li><strong>Real-time Preview</strong>: Hear voice greetings when switching models</li>
+<li><strong>Consistent Formatting</strong>: Voice names display as proper titles (e.g., &quot;Mark&quot; instead of &quot;en_US-mark-premium&quot;)</li>
+<li><strong>Availability Detection</strong>: Automatic detection and fallback when voice services are unavailable</li>
+</ul>
+<a id="md:🔄-context-switching" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🔄 Context Switching<a href="#md:🔄-context-switching" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>Local Session</strong>: Quick interactions within the modal scope</li>
+<li><strong>Main Conversation</strong>: Access full conversation history with automatic navigation to <code>/chat</code> route</li>
+<li><strong>Smart Conversation Selection</strong>: Automatically loads most recent conversation when switching contexts</li>
+</ul>
+<a id="md:💾-memory-features" class="tsd-anchor"></a><h3 class="tsd-anchor-link">💾 Memory Features<a href="#md:💾-memory-features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>Personal Memory Display</strong>: View AI's stored personal information about the user</li>
+<li><strong>Memory Entry Count</strong>: Real-time count of stored memory entries</li>
+<li><strong>Memory Management Modal</strong>: Full CRUD operations for memory entries</li>
+</ul>
+<p><strong>Example Usage:</strong></p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">ChatModal</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">function</span><span class="hl-1"> </span><span class="hl-0">App</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> [</span><span class="hl-7">modalOpen</span><span class="hl-1">, </span><span class="hl-7">setModalOpen</span><span class="hl-1">] = </span><span class="hl-0">useState</span><span class="hl-1">(</span><span class="hl-6">false</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-4">return</span><span class="hl-1"> (</span><br/><span class="hl-1">    </span><span class="hl-9">&lt;&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-13">button</span><span class="hl-1"> </span><span class="hl-11">onClick</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-14">() </span><span class="hl-6">=&gt;</span><span class="hl-14"> </span><span class="hl-0">setModalOpen</span><span class="hl-14">(</span><span class="hl-6">true</span><span class="hl-14">)</span><span class="hl-6">}</span><span class="hl-9">&gt;</span><br/><span class="hl-1">        Open AI Assistant</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;/</span><span class="hl-13">button</span><span class="hl-9">&gt;</span><br/><span class="hl-1">      </span><span class="hl-9">&lt;</span><span class="hl-10">ChatModal</span><span class="hl-1"> </span><br/><span class="hl-1">        </span><span class="hl-11">open</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-5">modalOpen</span><span class="hl-6">}</span><span class="hl-1"> </span><br/><span class="hl-1">        </span><span class="hl-11">onClose</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-14">() </span><span class="hl-6">=&gt;</span><span class="hl-14"> </span><span class="hl-0">setModalOpen</span><span class="hl-14">(</span><span class="hl-6">false</span><span class="hl-14">)</span><span class="hl-6">}</span><br/><span class="hl-1">        </span><span class="hl-8">// Chat Control Center is automatically included</span><br/><span class="hl-1">      </span><span class="hl-9">/&gt;</span><br/><span class="hl-1">    </span><span class="hl-9">&lt;/&gt;</span><br/><span class="hl-1">  );</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:📧-feedback-system" class="tsd-anchor"></a><h3 class="tsd-anchor-link">📧 Feedback System<a href="#md:📧-feedback-system" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The Bandit Engine includes a comprehensive feedback system that can be configured and customized for your application.</p>
+<p><strong>Configuration:</strong></p>
+<pre><code class="tsx"><span class="hl-8">// Package Settings - Configure feedback email</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">chatPackageSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-8">// ... other settings</span><br/><span class="hl-1">  </span><span class="hl-5">feedbackEmail:</span><span class="hl-1"> </span><span class="hl-2">&quot;feedback@yourcompany.com&quot;</span><span class="hl-1">, </span><span class="hl-8">// Optional: custom feedback email</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-8">// Preferences - Enable/disable feedback in management UI</span><br/><span class="hl-8">// Users can toggle feedback button on/off in preferences</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Standalone Usage:</strong></p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">FeedbackButton</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// Floating FAB button (default)</span><br/><span class="hl-9">&lt;</span><span class="hl-10">FeedbackButton</span><span class="hl-1"> </span><br/><span class="hl-1">  </span><span class="hl-11">feedbackEmail</span><span class="hl-1">=</span><span class="hl-2">&quot;support@myapp.com&quot;</span><span class="hl-1"> </span><span class="hl-8">// Optional: override default</span><br/><span class="hl-1">  </span><span class="hl-11">size</span><span class="hl-1">=</span><span class="hl-2">&quot;small&quot;</span><span class="hl-1"> </span><span class="hl-8">// small | medium | large</span><br/><span class="hl-1">  </span><span class="hl-11">position</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-14">{ </span><span class="hl-5">bottom:</span><span class="hl-14"> </span><span class="hl-15">24</span><span class="hl-14">, </span><span class="hl-5">right:</span><span class="hl-14"> </span><span class="hl-15">24</span><span class="hl-14"> }</span><span class="hl-6">}</span><span class="hl-1"> </span><span class="hl-8">// Custom positioning</span><br/><span class="hl-9">/&gt;</span><br/><br/><span class="hl-8">// Inline button</span><br/><span class="hl-9">&lt;</span><span class="hl-10">FeedbackButton</span><span class="hl-1"> </span><br/><span class="hl-1">  </span><span class="hl-11">inline</span><span class="hl-1">=</span><span class="hl-6">{true}</span><br/><span class="hl-1">  </span><span class="hl-11">buttonText</span><span class="hl-1">=</span><span class="hl-2">&quot;Send Feedback&quot;</span><br/><span class="hl-1">  </span><span class="hl-11">size</span><span class="hl-1">=</span><span class="hl-2">&quot;medium&quot;</span><br/><span class="hl-9">/&gt;</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Features:</strong></p>
+<ul>
+<li>📱 <strong>Responsive Design</strong>: Automatic floating FAB on desktop, inline button on mobile</li>
+<li>🎨 <strong>Category System</strong>: Bug reports, feature requests, general feedback</li>
+<li>📊 <strong>Priority Levels</strong>: Low, medium, high, critical</li>
+<li>😤 <strong>Annoyance Slider</strong>: Measure user frustration (1-5 scale)</li>
+<li>📎 <strong>Single Image Support</strong>: Automatic clipboard integration</li>
+<li>📧 <strong>Email Fallback</strong>: Generates mailto URLs when API unavailable</li>
+<li>⚙️ <strong>User Preferences</strong>: Can be enabled/disabled in management UI</li>
+</ul>
+<p><strong>Auto-Integration:</strong></p>
+<ul>
+<li>Desktop: Floating feedback button (when <code>preferences.feedbackEnabled</code> is true)</li>
+<li>Mobile: Integrated into chat input controls</li>
+<li>Preferences: Toggle available in management interface</li>
+</ul>
+<hr>
+<a id="md:⚙️-angular-integration-experimental" class="tsd-anchor"></a><h2 class="tsd-anchor-link">⚙️ Angular Integration (Experimental)<a href="#md:⚙️-angular-integration-experimental" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>To use Bandit Engine in an Angular project:</p>
+<ol>
+<li>Install the package:</li>
+</ol>
+<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">@burtson-labs/bandit-engine</span>
+</code><button type="button">Copy</button></pre>
+<ol start="2">
+<li><strong>Usage:</strong></li>
+</ol>
+<pre><code class="ts"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Chat</span><span class="hl-1">, </span><span class="hl-5">Management</span><span class="hl-1">, </span><span class="hl-5">ChatModal</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">defineCustomElement</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-chat&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">Chat</span><span class="hl-1">));</span><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-management&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">Management</span><span class="hl-1">));</span><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-modal&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">ChatModal</span><span class="hl-1">));</span>
+</code><button type="button">Copy</button></pre>
+<p>These components can now be used in your templates inside a <code>&lt;bandit-chat-provider&gt;</code> block.</p>
+<p>Usage in HTML:</p>
+<pre><code class="html"><span class="hl-9">&lt;</span><span class="hl-13">bandit-chat-provider</span><br/><span class="hl-1">  </span><span class="hl-11">packageSettings</span><span class="hl-1">=</span><span class="hl-16">&#39;{&quot;ollamaUrl&quot;:&quot;https://your-ollama-url.com&quot;,&quot;defaultModel&quot;:&quot;Bandit-Core&quot;,&quot;brandingConfigUrl&quot;:&quot;https://cdn.burtson.ai/configs/default-config.json&quot;}&#39;</span><br/><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-13">bandit-chat</span><span class="hl-9">&gt;&lt;/</span><span class="hl-13">bandit-chat</span><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-13">bandit-management</span><span class="hl-9">&gt;&lt;/</span><span class="hl-13">bandit-management</span><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-13">bandit-modal</span><span class="hl-9">&gt;&lt;/</span><span class="hl-13">bandit-modal</span><span class="hl-9">&gt;</span><br/><span class="hl-9">&lt;/</span><span class="hl-13">bandit-chat-provider</span><span class="hl-9">&gt;</span>
+</code><button type="button">Copy</button></pre>
+<p>Note: You only need to define the elements you intend to use. Don't mount all components on the same page. Use <code>&lt;bandit-management&gt;</code> for secure admin routes and <code>&lt;bandit-modal&gt;</code> for contextual triggers.</p>
+<hr>
+<a id="md:⚙️-vuejs-integration-experimental" class="tsd-anchor"></a><h2 class="tsd-anchor-link">⚙️ Vue.js Integration (Experimental)<a href="#md:⚙️-vuejs-integration-experimental" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>To use Bandit Engine in a Vue 3 project:</p>
+<ol>
+<li>Install the package:</li>
+</ol>
+<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">install</span><span class="hl-1"> </span><span class="hl-2">@burtson-labs/bandit-engine</span>
+</code><button type="button">Copy</button></pre>
+<ol start="2">
+<li><strong>Usage:</strong></li>
+</ol>
+<pre><code class="ts"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">Chat</span><span class="hl-1">, </span><span class="hl-5">Management</span><span class="hl-1">, </span><span class="hl-5">ChatModal</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">defineCustomElement</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-chat&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">Chat</span><span class="hl-1">));</span><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-management&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">Management</span><span class="hl-1">));</span><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-modal&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">ChatModal</span><span class="hl-1">));</span>
+</code><button type="button">Copy</button></pre>
+<p>These components can now be used in your templates inside a <code>&lt;bandit-chat-provider&gt;</code> block.</p>
+<p>Usage in HTML:</p>
+<pre><code class="html"><span class="hl-9">&lt;</span><span class="hl-13">bandit-chat-provider</span><br/><span class="hl-1">  </span><span class="hl-11">packageSettings</span><span class="hl-1">=</span><span class="hl-16">&#39;{&quot;ollamaUrl&quot;:&quot;https://your-ollama-url.com&quot;,&quot;defaultModel&quot;:&quot;Bandit-Core&quot;,&quot;brandingConfigUrl&quot;:&quot;https://cdn.burtson.ai/configs/default-config.json&quot;}&#39;</span><br/><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-13">bandit-chat</span><span class="hl-9">&gt;&lt;/</span><span class="hl-13">bandit-chat</span><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-13">bandit-management</span><span class="hl-9">&gt;&lt;/</span><span class="hl-13">bandit-management</span><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-13">bandit-modal</span><span class="hl-9">&gt;&lt;/</span><span class="hl-13">bandit-modal</span><span class="hl-9">&gt;</span><br/><span class="hl-9">&lt;/</span><span class="hl-13">bandit-chat-provider</span><span class="hl-9">&gt;</span>
+</code><button type="button">Copy</button></pre>
+<p>Note: You only need to define the elements you intend to use. Don't mount all components on the same page. Use <code>&lt;bandit-management&gt;</code> for secure admin routes and <code>&lt;bandit-modal&gt;</code> for contextual triggers.</p>
+<blockquote>
+<p><code>defineCustomElement</code> allows usage in Vue and Angular apps via native Web Components, making Bandit fully framework-agnostic.</p>
+</blockquote>
+<blockquote>
+<p>🔄 Similar to Angular, when using <code>&lt;Management /&gt;</code> or <code>&lt;ChatModal /&gt;</code>, wrap each one with a <code>&lt;bandit-chat-provider&gt;</code> to ensure proper context injection.</p>
+</blockquote>
+<blockquote>
+<p>Make sure <code>packageSettings</code> is passed as a serialized JSON string when using with HTML-based custom elements.</p>
+</blockquote>
+<blockquote>
+<p>Note: Ensure React and ReactDOM are correctly bundled and available to your Vue project. You may need additional tooling or wrappers to handle lifecycle and rendering behavior between frameworks. Full Vue support is on our roadmap.</p>
+</blockquote>
+<hr>
+<a id="md:📦-custom-element-support" class="tsd-anchor"></a><h2 class="tsd-anchor-link">📦 Custom Element Support<a href="#md:📦-custom-element-support" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>To use Bandit components (<code>Chat</code>, <code>Management</code>, <code>ChatModal</code>) in any modern JS framework (Angular, Vue, Svelte, etc.), you can register them as native custom elements:</p>
+<pre><code class="ts"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">defineCustomElement</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">BanditModal</span><span class="hl-1"> = </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-2">&#39;ChatModal&#39;</span><span class="hl-1">);</span><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-modal&#39;</span><span class="hl-1">, </span><span class="hl-5">BanditModal</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+<p>Wrap it in <code>&lt;bandit-chat-provider&gt;</code> and you’re ready to go. Ideal for environments where React isn’t used directly.</p>
+<blockquote>
+<p>🧠 <strong>Note for Non-React Users:</strong><br>
+When using Bandit components as custom elements (e.g., in Angular, Vue, or static HTML), make sure the compiled custom elements script is loaded before usage. You can do this by importing or referencing it in your HTML or entry file. This ensures the custom elements are defined before being rendered.</p>
+</blockquote>
+<p>To create custom elements, you must import the React components and pass them to <code>defineCustomElement</code>. For example:</p>
+<pre><code class="ts"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">ChatModal</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">defineCustomElement</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><span class="hl-5">customElements</span><span class="hl-1">.</span><span class="hl-0">define</span><span class="hl-1">(</span><span class="hl-2">&#39;bandit-modal&#39;</span><span class="hl-1">, </span><span class="hl-0">defineCustomElement</span><span class="hl-1">(</span><span class="hl-5">ChatModal</span><span class="hl-1">));</span>
+</code><button type="button">Copy</button></pre>
+<hr>
+<a id="md:📸-live-preview" class="tsd-anchor"></a><h2 class="tsd-anchor-link">📸 Live Preview<a href="#md:📸-live-preview" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Here are some screenshots of Bandit Chat in action:</p>
+<p><strong>Chat Demo – Your AI-powered UI</strong></p>
+<p align="center">
+  <img src="./public/images/chat-demo.jpg" alt="Bandit chat session showing multi-turn conversation with inline actions" width="600" />
+</p>
+<p><strong>Conversation Drawer &amp; Project Context</strong></p>
+<p align="center">
+  <img src="./public/images/chat-demo-2.jpg" alt="Chat drawer open with projects list and answered question" width="600" />
+</p>
+<p><strong>Chat Modal – Quick Assist Anywhere</strong></p>
+<p align="center">
+  <img src="./public/images/chat-modal.jpg" alt="Chat modal with control center options and message composer" width="600" />
+</p>
+<p><strong>Management – Branding Controls</strong></p>
+<p align="center">
+  <img src="./public/images/mgmt-branding.jpg" alt="Management interface branding tab showing logo and color options" width="600" />
+</p>
+<p><strong>Management – Personas</strong></p>
+<p align="center">
+  <img src="./public/images/mgmt-personalities.jpg" alt="Management interface personas tab with configurable AI personalities" width="600" />
+</p>
+<p><strong>Management – Preferences</strong></p>
+<p align="center">
+  <img src="./public/images/mgmt-preferences.jpg" alt="Management interface preferences tab with feature toggles" width="600" />
+</p>
+<ol start="4">
+<li><strong>🌐 CDN-Based Config (Optional)</strong></li>
+</ol>
+<p>To streamline configuration, you can host your <code>config.json</code> (and related assets like model presets or branding) via your own CDN or edge cache.</p>
+<p>Update the <code>brandingConfigUrl</code> like this:</p>
+<pre><code class="tsx"><span class="hl-9">&lt;</span><span class="hl-10">ChatProvider</span><br/><span class="hl-1">  </span><span class="hl-11">packageSettings</span><span class="hl-1">=</span><span class="hl-6">{</span><span class="hl-14">{</span><br/><span class="hl-14">    </span><span class="hl-1">...</span><span class="hl-5">chatPackageSettings</span><span class="hl-14">,</span><br/><span class="hl-14">    </span><span class="hl-5">brandingConfigUrl:</span><span class="hl-14"> </span><span class="hl-2">&quot;https://cdn.burtson.ai/configs/default-config.json&quot;</span><br/><span class="hl-14">  }</span><span class="hl-6">}</span><br/><span class="hl-9">&gt;</span><br/><span class="hl-1">  </span><span class="hl-9">&lt;</span><span class="hl-10">App</span><span class="hl-1"> </span><span class="hl-9">/&gt;</span><br/><span class="hl-9">&lt;/</span><span class="hl-10">ChatProvider</span><span class="hl-9">&gt;</span>
+</code><button type="button">Copy</button></pre>
+<p>This enables remote control of Bandit appearance, available models, and more — without redeploying your frontend.</p>
+<blockquote>
+<p>ℹ️ Note: All CDN assets such as logos, avatars, config, and workers are available at <code>https://cdn.burtson.ai/</code>. You may override these by hosting your own versions and pointing <code>packageSettings</code> to the appropriate URLs.</p>
+</blockquote>
+<hr>
+<a id="md:⚙️-configuration-options" class="tsd-anchor"></a><h2 class="tsd-anchor-link">⚙️ Configuration Options<a href="#md:⚙️-configuration-options" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul>
+<li><code>defaultModel</code>: Primary chat model (string; required)</li>
+<li><code>fallbackModel</code>: Optional fallback model if the default is unavailable</li>
+<li><code>gatewayApiUrl</code>: Gateway API base URL for AI, TTS, STT, and MCP</li>
+<li><code>aiProvider</code>: Provider configuration object (recommended for new installs)</li>
+<li><code>ollamaUrl</code>: Legacy Ollama base URL (deprecated, prefer <code>aiProvider</code>)</li>
+<li><code>s3ApiUrl</code>: Optional file storage API base URL (defaults to <code>gatewayApiUrl</code>)</li>
+<li><code>brandingConfigUrl</code>: Hosted branding JSON used to hydrate UI theming</li>
+<li><code>homeUrl</code>: Optional URL for the home button in management UI</li>
+<li><code>feedbackEmail</code>: Optional email address for feedback submissions</li>
+<li><code>featureFlags</code>: Optional feature flag configuration (see examples below)</li>
+</ul>
+<a id="md:🤖-ai-provider-system" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🤖 AI Provider System<a href="#md:🤖-ai-provider-system" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Bandit Engine features a unified, gateway-based AI provider architecture that supports multiple AI services through a secure backend:</p>
+<a id="md:supported-providers" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Supported Providers<a href="#md:supported-providers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>🌟 Gateway Provider</strong> (Recommended): Routes all requests through your secure .NET 9 backend</li>
+<li><strong>Ollama</strong>: Self-hosted models and Ollama-compatible endpoints</li>
+<li><strong>OpenAI</strong>: GPT models via OpenAI API</li>
+<li><strong>Azure OpenAI</strong>: Azure-hosted OpenAI models</li>
+<li><strong>Anthropic</strong>: Claude models via Anthropic API</li>
+</ul>
+<a id="md:gateway-provider-recommended" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Gateway Provider (Recommended)<a href="#md:gateway-provider-recommended" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The gateway provider offers the most secure and scalable approach by routing all requests through your backend API:</p>
+<pre><code class="tsx"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">chatPackageSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-8">// Gateway provider configuration</span><br/><span class="hl-1">  </span><span class="hl-5">aiProvider:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;gateway&quot;</span><span class="hl-1"> </span><span class="hl-4">as</span><span class="hl-1"> </span><span class="hl-6">const</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">gatewayUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-gateway-api.example.com&quot;</span><span class="hl-1">, </span><br/><span class="hl-1">    </span><span class="hl-5">provider:</span><span class="hl-1"> </span><span class="hl-2">&quot;openai&quot;</span><span class="hl-1"> </span><span class="hl-8">// Backend provider: openai, azure-openai, anthropic, ollama</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-8">// ... other settings</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Benefits:</strong></p>
+<ul>
+<li>🔒 <strong>Security</strong>: API keys stay on your server</li>
+<li>📊 <strong>Monitoring</strong>: Request logging and usage analytics</li>
+<li>🚦 <strong>Rate Limiting</strong>: Built-in throttling and quotas</li>
+<li>🔄 <strong>Provider Switching</strong>: Change backends without frontend updates</li>
+<li>🛡️ <strong>Authentication</strong>: Unified auth across all AI services</li>
+</ul>
+<p><strong>Gateway Requirements:</strong>
+Your gateway API can be built with any technology (Node.js, Python, .NET, Java, etc.) as long as it implements:</p>
+<ul>
+<li><code>GET /api/health</code> - Health check endpoint</li>
+<li><code>POST /api/chat/completions</code> - Chat completions with provider in request body</li>
+<li><code>POST /api/generate</code> - Text generation with provider in request body</li>
+</ul>
+<a id="md:legacy-direct-providers" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Legacy Direct Providers<a href="#md:legacy-direct-providers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Direct providers are still supported but marked as deprecated for production use:</p>
+<pre><code class="tsx"><span class="hl-8">// ⚠️ Deprecated: Direct OpenAI (exposes API keys)</span><br/><span class="hl-12">aiProvider</span><span class="hl-1">: {</span><br/><span class="hl-1">  </span><span class="hl-12">type</span><span class="hl-1">: </span><span class="hl-2">&quot;openai&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-12">apiKey</span><span class="hl-1">: </span><span class="hl-2">&quot;sk-...&quot;</span><span class="hl-1">, </span><span class="hl-8">// Exposed in frontend</span><br/><span class="hl-1">  </span><span class="hl-12">baseUrl</span><span class="hl-1">: </span><span class="hl-2">&quot;https://api.openai.com/v1&quot;</span><br/><span class="hl-1">}</span><br/><br/><span class="hl-8">// ⚠️ Deprecated: Direct Ollama (no auth/monitoring)  </span><br/><span class="hl-12">aiProvider</span><span class="hl-1">: {</span><br/><span class="hl-1">  </span><span class="hl-12">type</span><span class="hl-1">: </span><span class="hl-2">&quot;ollama&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-12">baseUrl</span><span class="hl-1">: </span><span class="hl-2">&quot;http://localhost:11434&quot;</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:migration-to-gateway" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Migration to Gateway<a href="#md:migration-to-gateway" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ol>
+<li><strong>Deploy Gateway Backend</strong>: Set up your .NET 9 gateway service</li>
+<li><strong>Update Configuration</strong>: Switch from direct to gateway provider</li>
+<li><strong>Test Connection</strong>: Use the Management interface to validate</li>
+<li><strong>Update API Keys</strong>: Move keys from frontend to backend config</li>
+</ol>
+<p>See <code>GATEWAY_MIGRATION_GUIDE.md</code> for detailed migration steps.</p>
+<a id="md:imagemultimodal-support" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Image/Multimodal Support<a href="#md:imagemultimodal-support" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The Bandit Engine provides comprehensive image support across all AI providers through the gateway architecture:</p>
+<p><strong>Supported Providers &amp; Models:</strong></p>
+<ul>
+<li><strong>Ollama</strong>: <code>llava</code>, <code>llava:13b</code>, <code>bakllava</code>, <code>llava-phi3</code></li>
+<li><strong>OpenAI</strong>: <code>gpt-4-vision-preview</code>, <code>gpt-4o</code>, <code>gpt-4o-mini</code></li>
+<li><strong>Azure OpenAI</strong>: <code>gpt-4-vision-preview</code> (deployed models)</li>
+<li><strong>Anthropic</strong>: <code>claude-3-opus</code>, <code>claude-3-sonnet</code>, <code>claude-3-haiku</code></li>
+</ul>
+<p><strong>Key Features:</strong></p>
+<ul>
+<li>🖼️ <strong>Universal Image Input</strong>: Drop, paste, or upload images directly in chat</li>
+<li>🔄 <strong>Provider-Specific Formatting</strong>: Automatic conversion to each provider's image format</li>
+<li>📱 <strong>Multi-Image Support</strong>: Send multiple images in a single message</li>
+<li>🎯 <strong>Vision Models</strong>: Seamless integration with multimodal AI models</li>
+</ul>
+<p><strong>Usage Example:</strong></p>
+<pre><code class="tsx"><span class="hl-8">// Images are automatically handled by the chat interface</span><br/><span class="hl-8">// Users can:</span><br/><span class="hl-8">// 1. Drag &amp; drop images into the chat input</span><br/><span class="hl-8">// 2. Paste images from clipboard (Ctrl+V / Cmd+V)  </span><br/><span class="hl-8">// 3. Use the attach button to select image files</span><br/><span class="hl-8">// 4. Ask questions about the images naturally</span><br/><br/><span class="hl-8">// The gateway provider automatically formats images correctly:</span><br/><span class="hl-8">// - Ollama: base64 arrays in message.images</span><br/><span class="hl-8">// - OpenAI/Azure/Anthropic: structured content with image_url objects</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Backend Requirements:</strong>
+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.</p>
+<pre><code class="javascript"><span class="hl-8">// Example: Gateway forwards images as-is to each provider</span><br/><span class="hl-5">app</span><span class="hl-1">.</span><span class="hl-0">post</span><span class="hl-1">(</span><span class="hl-2">&#39;/api/chat/completions&#39;</span><span class="hl-1">, </span><span class="hl-6">async</span><span class="hl-1"> (</span><span class="hl-5">req</span><span class="hl-1">, </span><span class="hl-5">res</span><span class="hl-1">) </span><span class="hl-6">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> { </span><span class="hl-7">provider</span><span class="hl-1">, </span><span class="hl-7">messages</span><span class="hl-1">, ...</span><span class="hl-7">options</span><span class="hl-1"> } = </span><span class="hl-5">req</span><span class="hl-1">.</span><span class="hl-5">body</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Messages already contain properly formatted images</span><br/><span class="hl-1">  </span><span class="hl-8">// Forward directly to the target provider API</span><br/><span class="hl-1">  </span><span class="hl-4">switch</span><span class="hl-1"> (</span><span class="hl-5">provider</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-4">case</span><span class="hl-1"> </span><span class="hl-2">&#39;ollama&#39;</span><span class="hl-1">:</span><br/><span class="hl-1">      </span><span class="hl-8">// messages[].images format (base64 arrays)</span><br/><span class="hl-1">      </span><span class="hl-4">return</span><span class="hl-1"> </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-5">ollamaClient</span><span class="hl-1">.</span><span class="hl-0">chat</span><span class="hl-1">({ </span><span class="hl-5">messages</span><span class="hl-1">, ...</span><span class="hl-5">options</span><span class="hl-1"> });</span><br/><span class="hl-1">    </span><span class="hl-4">case</span><span class="hl-1"> </span><span class="hl-2">&#39;openai&#39;</span><span class="hl-1">:  </span><br/><span class="hl-1">      </span><span class="hl-8">// messages[].content[].image_url format (structured)</span><br/><span class="hl-1">      </span><span class="hl-4">return</span><span class="hl-1"> </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-5">openaiClient</span><span class="hl-1">.</span><span class="hl-5">chat</span><span class="hl-1">.</span><span class="hl-5">completions</span><span class="hl-1">.</span><span class="hl-0">create</span><span class="hl-1">({ </span><span class="hl-5">messages</span><span class="hl-1">, ...</span><span class="hl-5">options</span><span class="hl-1"> });</span><br/><span class="hl-1">    </span><span class="hl-4">default</span><span class="hl-1">:</span><br/><span class="hl-1">      </span><span class="hl-4">throw</span><span class="hl-1"> </span><span class="hl-6">new</span><span class="hl-1"> </span><span class="hl-0">Error</span><span class="hl-1">(</span><span class="hl-2">`Unsupported provider: </span><span class="hl-6">${</span><span class="hl-5">provider</span><span class="hl-6">}</span><span class="hl-2">`</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:using-the-ai-provider" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Using the AI Provider<a href="#md:using-the-ai-provider" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>All chat interactions use the unified provider system regardless of backend:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">useAIProvider</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">function</span><span class="hl-1"> </span><span class="hl-0">MyComponent</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> { </span><span class="hl-7">generateResponse</span><span class="hl-1">, </span><span class="hl-7">isLoading</span><span class="hl-1"> } = </span><span class="hl-0">useAIProvider</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-0">handleChat</span><span class="hl-1"> = </span><span class="hl-6">async</span><span class="hl-1"> (</span><span class="hl-5">message</span><span class="hl-1">: </span><span class="hl-10">string</span><span class="hl-1">) </span><span class="hl-6">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">response</span><span class="hl-1"> = </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-0">generateResponse</span><span class="hl-1">(</span><span class="hl-5">message</span><span class="hl-1">);</span><br/><span class="hl-1">    </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-5">response</span><span class="hl-1">);</span><br/><span class="hl-1">  };</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:🔧-model-context-protocol-mcp-integration" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🔧 Model Context Protocol (MCP) Integration<a href="#md:🔧-model-context-protocol-mcp-integration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Bandit Engine now supports <strong>Model Context Protocol (MCP)</strong> for extending AI capabilities with external tools and services:</p>
+<a id="md:mcp-features" class="tsd-anchor"></a><h3 class="tsd-anchor-link">MCP Features<a href="#md:mcp-features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>Tool Integration</strong>: Connect external APIs and services to your AI conversations</li>
+<li><strong>Dynamic Tool Discovery</strong>: Automatically detect and configure available MCP tools</li>
+<li><strong>Secure Execution</strong>: All MCP tool calls go through your gateway API with proper authentication</li>
+<li><strong>Real-time Updates</strong>: Tools can be enabled/disabled without restarting the application</li>
+</ul>
+<a id="md:using-mcp-tools" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Using MCP Tools<a href="#md:using-mcp-tools" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>MCP tools are automatically available in chat conversations when configured:</p>
+<pre><code class="tsx"><span class="hl-8">// MCP tools are managed through the store</span><br/><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">useMCPToolsStore</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">function</span><span class="hl-1"> </span><span class="hl-0">MCPManager</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> { </span><span class="hl-7">tools</span><span class="hl-1">, </span><span class="hl-7">toggleTool</span><span class="hl-1">, </span><span class="hl-7">getEnabledTools</span><span class="hl-1"> } = </span><span class="hl-0">useMCPToolsStore</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Enable/disable tools</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-0">handleToggle</span><span class="hl-1"> = (</span><span class="hl-5">toolId</span><span class="hl-1">: </span><span class="hl-10">string</span><span class="hl-1">) </span><span class="hl-6">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-0">toggleTool</span><span class="hl-1">(</span><span class="hl-5">toolId</span><span class="hl-1">);</span><br/><span class="hl-1">  };</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Get currently enabled tools</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">enabledTools</span><span class="hl-1"> = </span><span class="hl-0">getEnabledTools</span><span class="hl-1">();</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:mcp-tool-configuration" class="tsd-anchor"></a><h3 class="tsd-anchor-link">MCP Tool Configuration<a href="#md:mcp-tool-configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Tools are configured through your gateway API and automatically discovered by the engine:</p>
+<pre><code class="json"><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;function&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-3">&quot;name&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;search_web&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;Search the web for current information&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-3">&quot;parameters&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">      </span><span class="hl-3">&quot;type&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;object&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">      </span><span class="hl-3">&quot;properties&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">        </span><span class="hl-3">&quot;query&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">          </span><span class="hl-3">&quot;type&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;string&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">          </span><span class="hl-3">&quot;description&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;Search query&quot;</span><br/><span class="hl-1">        }</span><br/><span class="hl-1">      }</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;endpoint&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;/mcp/search&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;method&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;POST&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-3">&quot;enabled&quot;</span><span class="hl-1">: </span><span class="hl-6">true</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:mcp-service-api" class="tsd-anchor"></a><h3 class="tsd-anchor-link">MCP Service API<a href="#md:mcp-service-api" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>For advanced usage, you can directly execute MCP tools:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">executeMCPTool</span><span class="hl-1">, </span><span class="hl-5">isMCPAvailable</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// Check if MCP is available</span><br/><span class="hl-4">if</span><span class="hl-1"> (</span><span class="hl-0">isMCPAvailable</span><span class="hl-1">()) {</span><br/><span class="hl-1">  </span><span class="hl-8">// Execute a tool</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">result</span><span class="hl-1"> = </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-0">executeMCPTool</span><span class="hl-1">({</span><br/><span class="hl-1">    </span><span class="hl-5">toolName:</span><span class="hl-1"> </span><span class="hl-2">&quot;search_web&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">parameters:</span><span class="hl-1"> { </span><span class="hl-5">query:</span><span class="hl-1"> </span><span class="hl-2">&quot;latest AI news&quot;</span><span class="hl-1"> }</span><br/><span class="hl-1">  });</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-4">if</span><span class="hl-1"> (</span><span class="hl-5">result</span><span class="hl-1">.</span><span class="hl-5">success</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-5">console</span><span class="hl-1">.</span><span class="hl-0">log</span><span class="hl-1">(</span><span class="hl-5">result</span><span class="hl-1">.</span><span class="hl-5">data</span><span class="hl-1">);</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<hr>
+<a id="md:🎛️-feature-flags--subscription-tiers" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🎛️ Feature Flags &amp; Subscription Tiers<a href="#md:🎛️-feature-flags--subscription-tiers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Bandit Engine includes a comprehensive <strong>tier-based feature flag system</strong> that enables subscription-based access control and feature gating:</p>
+<a id="md:subscription-tiers" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Subscription Tiers<a href="#md:subscription-tiers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The engine supports multiple subscription tiers with different feature access levels:</p>
+<ul>
+<li><strong>Basic</strong>: Core chat functionality with limitations</li>
+<li><strong>Premium</strong>: Enhanced features and higher limits</li>
+<li><strong>Pro</strong>: Advanced features for power users</li>
+<li><strong>Team</strong>: Collaboration features and team management</li>
+<li><strong>Trial</strong>: Temporary access with premium features</li>
+<li><strong>Expired</strong>: Limited access for expired subscriptions</li>
+</ul>
+<a id="md:feature-flag-configuration" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Feature Flag Configuration<a href="#md:feature-flag-configuration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Configure feature flags in your package settings:</p>
+<pre><code class="tsx"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">chatPackageSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-8">// ... other settings</span><br/><span class="hl-1">  </span><span class="hl-5">featureFlags:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">// Default tier (fallback when no JWT subscription info available)</span><br/><span class="hl-1">    </span><span class="hl-5">subscriptionType:</span><span class="hl-1"> </span><span class="hl-2">&quot;premium&quot;</span><span class="hl-1">, </span><span class="hl-8">// basic | premium | pro | team | trial</span><br/><span class="hl-1">    </span><br/><span class="hl-1">    </span><span class="hl-8">// JWT claim configuration for authentication</span><br/><span class="hl-1">    </span><span class="hl-5">rolesClaimKey:</span><span class="hl-1"> </span><span class="hl-2">&quot;roles&quot;</span><span class="hl-1">, </span><span class="hl-8">// JWT claim key for user roles</span><br/><span class="hl-1">    </span><span class="hl-5">subscriptionTypeClaimKey:</span><span class="hl-1"> </span><span class="hl-2">&quot;subscriptionType&quot;</span><span class="hl-1">, </span><span class="hl-8">// JWT claim for subscription type</span><br/><span class="hl-1">    </span><span class="hl-5">isSubscribedClaimKey:</span><span class="hl-1"> </span><span class="hl-2">&quot;isSubscribed&quot;</span><span class="hl-1">, </span><span class="hl-8">// JWT claim for subscription status</span><br/><span class="hl-1">    </span><span class="hl-5">jwtStorageKey:</span><span class="hl-1"> </span><span class="hl-2">&quot;authToken&quot;</span><span class="hl-1">, </span><span class="hl-8">// Local storage key for JWT token</span><br/><span class="hl-1">    </span><span class="hl-5">adminRole:</span><span class="hl-1"> </span><span class="hl-2">&quot;admin&quot;</span><span class="hl-1">, </span><span class="hl-8">// Admin role name for elevated access</span><br/><span class="hl-1">    </span><br/><span class="hl-1">    </span><span class="hl-8">// Development settings</span><br/><span class="hl-1">    </span><span class="hl-5">debug:</span><span class="hl-1"> </span><span class="hl-5">process</span><span class="hl-1">.</span><span class="hl-5">env</span><span class="hl-1">.</span><span class="hl-7">NODE_ENV</span><span class="hl-1"> === </span><span class="hl-2">&quot;development&quot;</span><span class="hl-1">, </span><span class="hl-8">// Enable debug logging</span><br/><span class="hl-1">    </span><br/><span class="hl-1">    </span><span class="hl-8">// Optional: Override specific features</span><br/><span class="hl-1">    </span><span class="hl-5">featureMatrix:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-5">tts:</span><span class="hl-1"> </span><span class="hl-6">true</span><span class="hl-1">, </span><span class="hl-8">// Enable/disable Text-to-Speech</span><br/><span class="hl-1">      </span><span class="hl-5">stt:</span><span class="hl-1"> </span><span class="hl-6">true</span><span class="hl-1">, </span><span class="hl-8">// Enable/disable Speech-to-Text</span><br/><span class="hl-1">      </span><span class="hl-8">// ... other feature overrides</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:tier-based-feature-matrix" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Tier-Based Feature Matrix<a href="#md:tier-based-feature-matrix" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Different subscription tiers have access to different features:</p>
+<table>
+<thead>
+<tr>
+<th>Feature</th>
+<th>Basic</th>
+<th>Premium</th>
+<th>Pro</th>
+<th>Team</th>
+<th>Trial</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td><strong>Core Chat</strong></td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+</tr>
+<tr>
+<td><strong>Text-to-Speech</strong></td>
+<td>❌</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+</tr>
+<tr>
+<td><strong>Speech-to-Text</strong></td>
+<td>❌</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+</tr>
+<tr>
+<td><strong>Document Upload</strong></td>
+<td>❌</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+<td>✅</td>
+</tr>
+<tr>
+<td><strong>Model Management</strong></td>
+<td>❌</td>
+<td>❌</td>
+<td>✅</td>
+<td>✅</td>
+<td>❌</td>
+</tr>
+<tr>
+<td><strong>Admin Dashboard</strong></td>
+<td>❌</td>
+<td>❌</td>
+<td>✅</td>
+<td>✅</td>
+<td>❌</td>
+</tr>
+<tr>
+<td><strong>API Access</strong></td>
+<td>❌</td>
+<td>❌</td>
+<td>✅</td>
+<td>✅</td>
+<td>❌</td>
+</tr>
+<tr>
+<td><strong>Team Collaboration</strong></td>
+<td>❌</td>
+<td>❌</td>
+<td>❌</td>
+<td>✅</td>
+<td>❌</td>
+</tr>
+<tr>
+<td><strong>Custom Branding</strong></td>
+<td>❌</td>
+<td>❌</td>
+<td>❌</td>
+<td>✅</td>
+<td>❌</td>
+</tr>
+</tbody>
+</table>
+<a id="md:jwt-based-authentication" class="tsd-anchor"></a><h3 class="tsd-anchor-link">JWT-Based Authentication<a href="#md:jwt-based-authentication" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The feature flag system integrates with JWT tokens for dynamic subscription management:</p>
+<pre><code class="tsx"><span class="hl-8">// Example JWT payload structure</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-2">&quot;sub&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;user123&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-2">&quot;subscriptionType&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;pro&quot;</span><span class="hl-1">, </span><span class="hl-8">// Controls tier access</span><br/><span class="hl-1">  </span><span class="hl-2">&quot;isSubscribed&quot;</span><span class="hl-1">: </span><span class="hl-6">true</span><span class="hl-1">, </span><span class="hl-8">// Overall subscription status</span><br/><span class="hl-1">  </span><span class="hl-2">&quot;roles&quot;</span><span class="hl-1">: [</span><span class="hl-2">&quot;user&quot;</span><span class="hl-1">, </span><span class="hl-2">&quot;admin&quot;</span><span class="hl-1">], </span><span class="hl-8">// User roles for admin features</span><br/><span class="hl-1">  </span><span class="hl-2">&quot;exp&quot;</span><span class="hl-1">: </span><span class="hl-15">1640995200</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:using-feature-flags-in-components" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Using Feature Flags in Components<a href="#md:using-feature-flags-in-components" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Access feature flags throughout your application:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">useFeatureFlags</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">function</span><span class="hl-1"> </span><span class="hl-0">MyComponent</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> { </span><br/><span class="hl-1">    </span><span class="hl-7">hasFeature</span><span class="hl-1">, </span><br/><span class="hl-1">    </span><span class="hl-7">currentTier</span><span class="hl-1">, </span><br/><span class="hl-1">    </span><span class="hl-7">isAdmin</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-7">isSubscribed</span><span class="hl-1"> </span><br/><span class="hl-1">  } = </span><span class="hl-0">useFeatureFlags</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Check specific features</span><br/><span class="hl-1">  </span><span class="hl-4">if</span><span class="hl-1"> (</span><span class="hl-0">hasFeature</span><span class="hl-1">(</span><span class="hl-2">&#39;tts&#39;</span><span class="hl-1">)) {</span><br/><span class="hl-1">    </span><span class="hl-8">// Show text-to-speech controls</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Check subscription tier</span><br/><span class="hl-1">  </span><span class="hl-4">if</span><span class="hl-1"> (</span><span class="hl-5">currentTier</span><span class="hl-1"> === </span><span class="hl-2">&#39;pro&#39;</span><span class="hl-1"> || </span><span class="hl-5">currentTier</span><span class="hl-1"> === </span><span class="hl-2">&#39;team&#39;</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">// Show advanced features</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Check admin access</span><br/><span class="hl-1">  </span><span class="hl-4">if</span><span class="hl-1"> (</span><span class="hl-5">isAdmin</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-8">// Show admin controls</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:subscription-state-management" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Subscription State Management<a href="#md:subscription-state-management" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The engine automatically handles subscription state changes:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">useAuthenticationStore</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-6">function</span><span class="hl-1"> </span><span class="hl-0">SubscriptionManager</span><span class="hl-1">() {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> { </span><br/><span class="hl-1">    </span><span class="hl-7">subscriptionType</span><span class="hl-1">, </span><br/><span class="hl-1">    </span><span class="hl-7">isSubscribed</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-7">refreshSubscription</span><span class="hl-1"> </span><br/><span class="hl-1">  } = </span><span class="hl-0">useAuthenticationStore</span><span class="hl-1">();</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Handle subscription upgrades</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-0">handleUpgrade</span><span class="hl-1"> = </span><span class="hl-6">async</span><span class="hl-1"> () </span><span class="hl-6">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-8">// After successful payment processing</span><br/><span class="hl-1">    </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-0">refreshSubscription</span><span class="hl-1">(); </span><span class="hl-8">// Reload JWT and feature access</span><br/><span class="hl-1">  };</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Display upgrade prompts for limited features</span><br/><span class="hl-1">  </span><span class="hl-4">if</span><span class="hl-1"> (!</span><span class="hl-5">isSubscribed</span><span class="hl-1"> &amp;&amp; </span><span class="hl-5">attemptedRestrictedFeature</span><span class="hl-1">) {</span><br/><span class="hl-1">    </span><span class="hl-4">return</span><span class="hl-1"> </span><span class="hl-9">&lt;</span><span class="hl-10">UpgradePrompt</span><span class="hl-1"> </span><span class="hl-9">/&gt;</span><span class="hl-1">;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:feature-restrictions--upgrade-prompts" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Feature Restrictions &amp; Upgrade Prompts<a href="#md:feature-restrictions--upgrade-prompts" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The engine automatically shows upgrade prompts when users try to access restricted features:</p>
+<ul>
+<li><strong>Graceful Degradation</strong>: Features are hidden or disabled based on subscription tier</li>
+<li><strong>Upgrade Prompts</strong>: Users see contextual upgrade suggestions when attempting restricted actions</li>
+<li><strong>Real-time Updates</strong>: Subscription changes take effect immediately without app restart</li>
+</ul>
+<a id="md:development--testing" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Development &amp; Testing<a href="#md:development--testing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>For development and testing environments:</p>
+<pre><code class="tsx"><span class="hl-8">// Override subscription tier for testing</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">devSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-5">featureFlags:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">subscriptionType:</span><span class="hl-1"> </span><span class="hl-2">&quot;team&quot;</span><span class="hl-1">, </span><span class="hl-8">// Test with highest tier</span><br/><span class="hl-1">    </span><span class="hl-5">debug:</span><span class="hl-1"> </span><span class="hl-6">true</span><span class="hl-1">, </span><span class="hl-8">// Enable detailed logging</span><br/><span class="hl-1">    </span><span class="hl-5">featureMatrix:</span><span class="hl-1"> {</span><br/><span class="hl-1">      </span><span class="hl-8">// Force enable specific features for testing</span><br/><span class="hl-1">      </span><span class="hl-5">experimentalFeature:</span><span class="hl-1"> </span><span class="hl-6">true</span><span class="hl-1">,</span><br/><span class="hl-1">    }</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:backend-integration" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Backend Integration<a href="#md:backend-integration" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Your gateway API should validate subscription tiers and return appropriate feature access:</p>
+<pre><code class="javascript"><span class="hl-8">// Example: Gateway API subscription validation</span><br/><span class="hl-5">app</span><span class="hl-1">.</span><span class="hl-0">post</span><span class="hl-1">(</span><span class="hl-2">&#39;/api/chat/completions&#39;</span><span class="hl-1">, </span><span class="hl-5">authenticateJWT</span><span class="hl-1">, </span><span class="hl-6">async</span><span class="hl-1"> (</span><span class="hl-5">req</span><span class="hl-1">, </span><span class="hl-5">res</span><span class="hl-1">) </span><span class="hl-6">=&gt;</span><span class="hl-1"> {</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> { </span><span class="hl-7">subscriptionType</span><span class="hl-1">, </span><span class="hl-7">isSubscribed</span><span class="hl-1"> } = </span><span class="hl-5">req</span><span class="hl-1">.</span><span class="hl-5">user</span><span class="hl-1">;</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Validate tier access for requested features</span><br/><span class="hl-1">  </span><span class="hl-4">if</span><span class="hl-1"> (</span><span class="hl-5">req</span><span class="hl-1">.</span><span class="hl-5">body</span><span class="hl-1">.</span><span class="hl-5">tts</span><span class="hl-1"> &amp;&amp; !</span><span class="hl-0">hasFeature</span><span class="hl-1">(</span><span class="hl-5">subscriptionType</span><span class="hl-1">, </span><span class="hl-2">&#39;tts&#39;</span><span class="hl-1">)) {</span><br/><span class="hl-1">    </span><span class="hl-4">return</span><span class="hl-1"> </span><span class="hl-5">res</span><span class="hl-1">.</span><span class="hl-0">status</span><span class="hl-1">(</span><span class="hl-15">403</span><span class="hl-1">).</span><span class="hl-0">json</span><span class="hl-1">({ </span><br/><span class="hl-1">      </span><span class="hl-5">error:</span><span class="hl-1"> </span><span class="hl-2">&#39;TTS requires Premium subscription or higher&#39;</span><span class="hl-1"> </span><br/><span class="hl-1">    });</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">  </span><br/><span class="hl-1">  </span><span class="hl-8">// Proceed with AI request</span><br/><span class="hl-1">  </span><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">response</span><span class="hl-1"> = </span><span class="hl-4">await</span><span class="hl-1"> </span><span class="hl-0">processAIRequest</span><span class="hl-1">(</span><span class="hl-5">req</span><span class="hl-1">.</span><span class="hl-5">body</span><span class="hl-1">);</span><br/><span class="hl-1">  </span><span class="hl-5">res</span><span class="hl-1">.</span><span class="hl-0">json</span><span class="hl-1">(</span><span class="hl-5">response</span><span class="hl-1">);</span><br/><span class="hl-1">});</span>
+</code><button type="button">Copy</button></pre>
+<p>This feature flag system enables you to build sophisticated subscription-based AI products with fine-grained access control and seamless upgrade flows.</p>
+<hr>
+<a id="md:🐛-debug-logger" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🐛 Debug Logger<a href="#md:🐛-debug-logger" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Bandit Engine exports a debug logger for consistent logging across your application:</p>
+<pre><code class="tsx"><span class="hl-4">import</span><span class="hl-1"> { </span><span class="hl-5">debugLogger</span><span class="hl-1"> } </span><span class="hl-4">from</span><span class="hl-1"> </span><span class="hl-2">&#39;@burtson-labs/bandit-engine&#39;</span><span class="hl-1">;</span><br/><br/><span class="hl-8">// Use instead of console.log/warn/error</span><br/><span class="hl-5">debugLogger</span><span class="hl-1">.</span><span class="hl-0">info</span><span class="hl-1">(</span><span class="hl-2">&#39;Chat message sent&#39;</span><span class="hl-1">);</span><br/><span class="hl-5">debugLogger</span><span class="hl-1">.</span><span class="hl-0">warn</span><span class="hl-1">(</span><span class="hl-2">&#39;Fallback model used&#39;</span><span class="hl-1">);</span><br/><span class="hl-5">debugLogger</span><span class="hl-1">.</span><span class="hl-0">error</span><span class="hl-1">(</span><span class="hl-2">&#39;Failed to connect to AI service&#39;</span><span class="hl-1">);</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:🔒-security-best-practices" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🔒 Security Best Practices<a href="#md:🔒-security-best-practices" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p><strong>⚠️ Important Security Notice:</strong></p>
+<p>While Bandit Engine supports direct API key configuration for development and testing, <strong>we strongly recommend against using API keys directly in frontend applications</strong> for production environments.</p>
+<a id="md:recommended-architecture" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Recommended Architecture<a href="#md:recommended-architecture" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ol>
+<li><strong>Use an API Gateway/Wrapper</strong>: Deploy the OllamaGateway (soon to be renamed AiGateway) or similar backend service</li>
+<li><strong>Proxy AI Requests</strong>: Route all AI requests through your secure backend</li>
+<li><strong>Environment Isolation</strong>: Keep API keys and sensitive configuration on the server side</li>
+<li><strong>Authentication</strong>: Implement proper user authentication and request validation</li>
+</ol>
+<a id="md:gateway-setup" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Gateway Setup<a href="#md:gateway-setup" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The recommended approach is to use a gateway service that:</p>
+<ul>
+<li>Handles API key management securely</li>
+<li>Provides rate limiting and usage tracking</li>
+<li>Exposes standardized endpoints for AI, TTS, and STT services</li>
+<li>Manages provider switching and fallback logic</li>
+<li><strong>Technology-agnostic</strong>: Works with any backend implementation</li>
+</ul>
+<pre><code class="tsx"><span class="hl-8">// Recommended: Use gateway with unified API</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">chatPackageSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-5">aiProvider:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;gateway&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">gatewayUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-api-gateway.com&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">provider:</span><span class="hl-1"> </span><span class="hl-2">&quot;openai&quot;</span><span class="hl-1"> </span><span class="hl-8">// or &quot;anthropic&quot;, &quot;azure-openai&quot;, &quot;ollama&quot;</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-5">gatewayApiUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-api-gateway.com&quot;</span><span class="hl-1">, </span><span class="hl-8">// Same URL for TTS/STT services</span><br/><span class="hl-1">  </span><span class="hl-8">// No API keys in frontend code</span><br/><span class="hl-1">  </span><span class="hl-8">// ... other settings</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:legacy-configuration-deprecated" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Legacy Configuration (Deprecated)<a href="#md:legacy-configuration-deprecated" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>⚠️ <strong>Legacy TTS/STT URLs are deprecated.</strong> Use the unified <code>gatewayApiUrl</code> instead:</p>
+<pre><code class="tsx"><span class="hl-8">// ❌ Deprecated (still works but not recommended)</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">oldSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-5">ttsUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;/api/tts&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">sttUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;/api/stt&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">ollamaUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;http://localhost:11434&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">};</span><br/><br/><span class="hl-8">// ✅ Recommended (unified gateway approach)</span><br/><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">newSettings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-5">aiProvider:</span><span class="hl-1"> { </span><span class="hl-5">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;gateway&quot;</span><span class="hl-1">, </span><span class="hl-5">gatewayUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-gateway.com&quot;</span><span class="hl-1">, </span><span class="hl-5">provider:</span><span class="hl-1"> </span><span class="hl-2">&quot;openai&quot;</span><span class="hl-1"> },</span><br/><span class="hl-1">  </span><span class="hl-5">gatewayApiUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-gateway.com&quot;</span><span class="hl-1">, </span><span class="hl-8">// Handles TTS, STT, and MCP</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<a id="md:development-vs-production" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Development vs Production<a href="#md:development-vs-production" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>Development</strong>: Direct provider API keys are acceptable for local testing</li>
+<li><strong>Production</strong>: Always use a gateway/wrapper service to protect sensitive credentials</li>
+</ul>
+<a id="md:requirements" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Requirements<a href="#md:requirements" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><a id="md:gateway-api-services" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Gateway API Services<a href="#md:gateway-api-services" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>The Bandit Engine uses a <strong>unified gateway approach</strong> for all backend services. Your gateway API should implement these endpoints:</p>
+<p><strong>Core AI Services:</strong></p>
+<ul>
+<li><code>GET /api/health</code> - Health check and service discovery</li>
+<li><code>POST /api/chat/completions</code> - Chat completions (OpenAI format)</li>
+<li><code>POST /api/generate</code> - Text generation</li>
+<li>Provider-specific routing (automatically handled)</li>
+</ul>
+<p><strong>Voice Services (Optional):</strong></p>
+<ul>
+<li>
+<p><code>POST /api/tts</code> - Text-to-Speech conversion</p>
+<ul>
+<li>Input: <code>{ text: string, voice?: string, speed?: number }</code></li>
+<li>Output: Audio file or streaming audio</li>
+<li><strong>Technology-agnostic</strong>: Works with OpenAI TTS, Azure Speech, Google TTS, AWS Polly, Whisper.cpp, or custom implementations</li>
+</ul>
+</li>
+<li>
+<p><code>POST /api/stt</code> - Speech-to-Text transcription</p>
+<ul>
+<li>Input: Audio file upload (multipart/form-data)</li>
+<li>Output: <code>{ text: string }</code> or <code>{ transcription: string }</code></li>
+<li><strong>Technology-agnostic</strong>: Works with OpenAI Whisper, Azure Speech, Google Speech, AWS Transcribe, local Whisper, or custom implementations</li>
+</ul>
+</li>
+<li>
+<p><code>GET /api/tts/available-models</code> - Voice model discovery</p>
+<ul>
+<li>Output: <code>{ models: string[], defaultModel: string, fallbackModel: string }</code></li>
+<li>Used for automatic service availability detection</li>
+</ul>
+</li>
+</ul>
+<p><strong>MCP Services (Optional):</strong></p>
+<ul>
+<li>Model Context Protocol endpoints for tool integration</li>
+</ul>
+<a id="md:technology-agnostic-implementation" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Technology-Agnostic Implementation<a href="#md:technology-agnostic-implementation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Your gateway can be implemented in <strong>any language or framework</strong>:</p>
+<ul>
+<li><strong>Node.js/Express</strong>, <strong>Python/FastAPI</strong>, <strong>.NET Core</strong>, <strong>Java/Spring</strong></li>
+<li><strong>PHP/Laravel</strong>, <strong>Ruby on Rails</strong>, <strong>Go/Gin</strong>, <strong>Rust/Axum</strong></li>
+<li><strong>Serverless</strong> (AWS Lambda, Vercel Functions, Cloudflare Workers)</li>
+</ul>
+<p>The Bandit Engine only requires that your endpoints follow the expected input/output contracts. The underlying implementation is completely flexible.</p>
+<a id="md:additional-resources" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Additional Resources<a href="#md:additional-resources" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li><strong>PDF Worker</strong>: For document embedding features, the engine uses the PDF parsing worker from <code>https://cdn.burtson.ai/scripts/pdf.worker.js</code></li>
+<li><strong>CDN Resources</strong>: Default avatars, logos, and configurations load from <code>https://cdn.burtson.ai/</code> if not overridden locally</li>
+</ul>
+<a id="md:💡-vision--roadmap" class="tsd-anchor"></a><h2 class="tsd-anchor-link">💡 Vision &amp; Roadmap<a href="#md:💡-vision--roadmap" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>Bandit Engine isn't just a component – it's a foundation. Coming soon:</p>
+<ul>
+<li>Multi-modal input: image, voice, document uploads</li>
+<li>Agentic flow support with visualized cards and suggestions</li>
+<li>Pluggable memory and long-term knowledge</li>
+<li>Customizable avatars and real-time voice playback</li>
+<li>Client-defined RAG and embedding search</li>
+</ul>
+<p>We’re building this to be the interface layer of your AI-first products. Own the UX. Own the brand. Own the experience.</p>
+<hr>
+<a id="md:📌-migration-guide" class="tsd-anchor"></a><h2 class="tsd-anchor-link">📌 Migration Guide<a href="#md:📌-migration-guide" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><a id="md:from-legacy-ttsstt-urls-to-gateway-api" class="tsd-anchor"></a><h3 class="tsd-anchor-link">From Legacy TTS/STT URLs to Gateway API<a href="#md:from-legacy-ttsstt-urls-to-gateway-api" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>If you're currently using separate <code>ttsUrl</code> and <code>sttUrl</code> settings, migrate to the unified gateway approach:</p>
+<p><strong>Before (Deprecated):</strong></p>
+<pre><code class="tsx"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">settings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-5">ttsUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-tts-service.com/api/tts&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">sttUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-stt-service.com/api/stt&quot;</span><span class="hl-1">, </span><br/><span class="hl-1">  </span><span class="hl-5">ollamaUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-ollama.com&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>After (Recommended):</strong></p>
+<pre><code class="tsx"><span class="hl-6">const</span><span class="hl-1"> </span><span class="hl-7">settings</span><span class="hl-1"> = {</span><br/><span class="hl-1">  </span><span class="hl-5">aiProvider:</span><span class="hl-1"> {</span><br/><span class="hl-1">    </span><span class="hl-5">type:</span><span class="hl-1"> </span><span class="hl-2">&quot;gateway&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">gatewayUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-gateway.com&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">provider:</span><span class="hl-1"> </span><span class="hl-2">&quot;openai&quot;</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-5">gatewayApiUrl:</span><span class="hl-1"> </span><span class="hl-2">&quot;https://your-gateway.com&quot;</span><span class="hl-1">, </span><span class="hl-8">// Unified endpoint for all services</span><br/><span class="hl-1">};</span>
+</code><button type="button">Copy</button></pre>
+<p>The new approach provides:</p>
+<ul>
+<li>✅ <strong>Unified API</strong>: One endpoint for all services</li>
+<li>✅ <strong>Better Security</strong>: Centralized authentication and rate limiting</li>
+<li>✅ <strong>Technology Flexibility</strong>: Use any backend implementation</li>
+<li>✅ <strong>Automatic Discovery</strong>: Real-time service availability detection</li>
+</ul>
+<hr>
+<a id="md:🛡️-license--protection" class="tsd-anchor"></a><h2 class="tsd-anchor-link">🛡️ License &amp; Protection<a href="#md:🛡️-license--protection" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><p>This software is protected under the <strong>Business Source License (BUSL) 1.1</strong> by Burtson Labs LLC.</p>
+<a id="md:⚖️-license-summary" class="tsd-anchor"></a><h3 class="tsd-anchor-link">⚖️ License Summary<a href="#md:⚖️-license-summary" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><ul>
+<li>✅ <strong>Development &amp; Evaluation</strong>: Free for internal development, testing, and evaluation</li>
+<li>✅ <strong>Non-Commercial Use</strong>: Free for educational, research, and personal projects</li>
+<li>❌ <strong>Commercial Production</strong>: Requires commercial license for production deployment</li>
+<li>❌ <strong>Competitive Use</strong>: Cannot be used to create competing AI chat products</li>
+<li>❌ <strong>AI Training</strong>: Cannot be used as training data for AI models</li>
+</ul>
+<a id="md:📋-usage-rights" class="tsd-anchor"></a><h3 class="tsd-anchor-link">📋 Usage Rights<a href="#md:📋-usage-rights" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p><strong>Permitted:</strong></p>
+<ul>
+<li>Internal development and testing</li>
+<li>Educational and research purposes</li>
+<li>Evaluation for potential commercial licensing</li>
+<li>Contributions back to the project (under same license)</li>
+</ul>
+<p><strong>Prohibited:</strong></p>
+<ul>
+<li>Production use without commercial license</li>
+<li>Creating derivative commercial products</li>
+<li>Using as training data for AI/ML models</li>
+<li>Removing or modifying license notices and watermarks</li>
+</ul>
+<a id="md:🔒-protection-features" class="tsd-anchor"></a><h3 class="tsd-anchor-link">🔒 Protection Features<a href="#md:🔒-protection-features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>This codebase includes multiple protection layers:</p>
+<ul>
+<li><strong>Embedded Watermarks</strong>: Visible and stealth fingerprints in all source files</li>
+<li><strong>Audit Trails</strong>: Usage tracking and compliance monitoring</li>
+<li><strong>License Validation</strong>: Runtime checks for compliance</li>
+<li><strong>Honey Pot Files</strong>: Trap files that trigger license violations when accessed</li>
+</ul>
+<p><strong>⚠️ Warning</strong>: Removing, modifying, or bypassing these protection mechanisms constitutes a license violation and may result in immediate license termination.</p>
+<a id="md:💼-commercial-licensing" class="tsd-anchor"></a><h3 class="tsd-anchor-link">💼 Commercial Licensing<a href="#md:💼-commercial-licensing" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p><strong>Production License</strong>: Required for commercial deployment</p>
+<ul>
+<li>Full production rights</li>
+<li>Priority support and maintenance</li>
+<li>Custom integrations and features</li>
+<li>Enterprise SLA options</li>
+</ul>
+<p><strong>Contact for Licensing:</strong></p>
+<ul>
+<li><strong>Email</strong>: <a href="mailto:legal@burtson.ai">legal@burtson.ai</a></li>
+<li><strong>Website</strong>: <a href="https://burtson.ai/license" target="_blank" class="external">https://burtson.ai/license</a></li>
+<li><strong>Sales</strong>: <a href="mailto:sales@burtson.ai">sales@burtson.ai</a></li>
+</ul>
+<a id="md:👨💻-for-contributors--developers" class="tsd-anchor"></a><h3 class="tsd-anchor-link">👨‍💻 For Contributors &amp; Developers<a href="#md:👨💻-for-contributors--developers" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Before contributing or making changes to this codebase:</p>
+<pre><code class="bash"><span class="hl-8"># Essential pre-push workflow - run before every commit</span><br/><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">pre-push</span>
+</code><button type="button">Copy</button></pre>
+<p><strong>Developer Resources:</strong></p>
+<ul>
+<li><strong><a href="media/PROTECTION-README.md">PROTECTION-README.md</a></strong> - Quick protection system guide</li>
+<li><strong><a href="media/PRE-PUSH-CHECKLIST.md">PRE-PUSH-CHECKLIST.md</a></strong> - Complete workflow documentation</li>
+<li><strong><a href="media/PROTECTION-NOTICE.md">PROTECTION-NOTICE.md</a></strong> - Legal notices and compliance requirements</li>
+<li><strong><a href="media/LICENSE">LICENSE</a></strong> - Full BUSL 1.1 license text</li>
+</ul>
+<a id="md:📝-license-compliance" class="tsd-anchor"></a><h3 class="tsd-anchor-link">📝 License Compliance<a href="#md:📝-license-compliance" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>All source files must include proper license headers and watermarks. The protection system automatically:</p>
+<ul>
+<li>Adds license headers to new files</li>
+<li>Validates compliance on every build</li>
+<li>Tracks usage and modifications</li>
+<li>Prevents unauthorized distribution</li>
+</ul>
+<p><strong>Quick Commands:</strong></p>
+<pre><code class="bash"><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">protect</span><span class="hl-1">             </span><span class="hl-8"># Apply protection to new files</span><br/><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">validate-protection</span><span class="hl-1"> </span><span class="hl-8"># Check for license violations  </span><br/><span class="hl-0">npm</span><span class="hl-1"> </span><span class="hl-2">run</span><span class="hl-1"> </span><span class="hl-2">pre-push</span><span class="hl-1">           </span><span class="hl-8"># Complete pre-push validation</span>
+</code><button type="button">Copy</button></pre>
+<hr>
+<p><strong>© 2025 Burtson Labs LLC. All rights reserved.</strong></p>
+</div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility"><span class="settings-label">Member Visibility</span><ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Protected</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>Inherited</span></label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg><span>External</span></label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></div></details></div><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none"><use href="assets/icons.svg#icon-chevronDown"></use></svg>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#md:⚡-cli-quick-start"><span>⚡ CLI <wbr/>Quick <wbr/>Start</span></a><ul><li><a href="#md:cli-options"><span>CLI <wbr/>Options</span></a></li></ul><a href="#md:🛠️-getting-started--plug--play-ai"><span>🛠️ <wbr/>Getting <wbr/>Started – <wbr/>Plug &amp; <wbr/>Play AI</span></a><ul><li><a href="#md:🔄-quick-provider-setup"><span>🔄 <wbr/>Quick <wbr/>Provider <wbr/>Setup</span></a></li><li><a href="#md:ollama-env-setup"><span>Ollama .env <wbr/>Setup</span></a></li><li><a href="#md:🎤-voice-services-ttsstt"><span>🎤 <wbr/>Voice <wbr/>Services (TTS/STT)</span></a></li></ul><a href="#md:🧩-consuming-the-components"><span>🧩 <wbr/>Consuming the <wbr/>Components</span></a><ul><li><a href="#md:🛠️-utility-functions--hooks"><span>🛠️ <wbr/>Utility <wbr/>Functions &amp; <wbr/>Hooks</span></a></li><li><ul><li><a href="#md:debug-logger"><span>Debug <wbr/>Logger</span></a></li><li><a href="#md:ai-prompt-utilities"><span>AI <wbr/>Prompt <wbr/>Utilities</span></a></li><li><a href="#md:datetime-context"><span>Date/<wbr/>Time <wbr/>Context</span></a></li></ul></li></ul><a href="#md:🎛️-chat-control-center-chatmodal-feature"><span>🎛️ <wbr/>Chat <wbr/>Control <wbr/>Center (<wbr/>Chat<wbr/>Modal <wbr/>Feature)</span></a><ul><li><a href="#md:🔧-core-features"><span>🔧 <wbr/>Core <wbr/>Features</span></a></li><li><a href="#md:🎤-voice-integration"><span>🎤 <wbr/>Voice <wbr/>Integration</span></a></li><li><a href="#md:🔄-context-switching"><span>🔄 <wbr/>Context <wbr/>Switching</span></a></li><li><a href="#md:💾-memory-features"><span>💾 <wbr/>Memory <wbr/>Features</span></a></li><li><a href="#md:📧-feedback-system"><span>📧 <wbr/>Feedback <wbr/>System</span></a></li></ul><a href="#md:⚙️-angular-integration-experimental"><span>⚙️ <wbr/>Angular <wbr/>Integration (<wbr/>Experimental)</span></a><a href="#md:⚙️-vuejs-integration-experimental"><span>⚙️ <wbr/>Vue.js <wbr/>Integration (<wbr/>Experimental)</span></a><a href="#md:📦-custom-element-support"><span>📦 <wbr/>Custom <wbr/>Element <wbr/>Support</span></a><a href="#md:📸-live-preview"><span>📸 <wbr/>Live <wbr/>Preview</span></a><a href="#md:⚙️-configuration-options"><span>⚙️ <wbr/>Configuration <wbr/>Options</span></a><a href="#md:🤖-ai-provider-system"><span>🤖 AI <wbr/>Provider <wbr/>System</span></a><ul><li><a href="#md:supported-providers"><span>Supported <wbr/>Providers</span></a></li><li><a href="#md:gateway-provider-recommended"><span>Gateway <wbr/>Provider (<wbr/>Recommended)</span></a></li><li><a href="#md:legacy-direct-providers"><span>Legacy <wbr/>Direct <wbr/>Providers</span></a></li><li><a href="#md:migration-to-gateway"><span>Migration to <wbr/>Gateway</span></a></li><li><a href="#md:imagemultimodal-support"><span>Image/<wbr/>Multimodal <wbr/>Support</span></a></li><li><a href="#md:using-the-ai-provider"><span>Using the AI <wbr/>Provider</span></a></li></ul><a href="#md:🔧-model-context-protocol-mcp-integration"><span>🔧 <wbr/>Model <wbr/>Context <wbr/>Protocol (MCP) <wbr/>Integration</span></a><ul><li><a href="#md:mcp-features"><span>MCP <wbr/>Features</span></a></li><li><a href="#md:using-mcp-tools"><span>Using MCP <wbr/>Tools</span></a></li><li><a href="#md:mcp-tool-configuration"><span>MCP <wbr/>Tool <wbr/>Configuration</span></a></li><li><a href="#md:mcp-service-api"><span>MCP <wbr/>Service API</span></a></li></ul><a href="#md:🎛️-feature-flags--subscription-tiers"><span>🎛️ <wbr/>Feature <wbr/>Flags &amp; <wbr/>Subscription <wbr/>Tiers</span></a><ul><li><a href="#md:subscription-tiers"><span>Subscription <wbr/>Tiers</span></a></li><li><a href="#md:feature-flag-configuration"><span>Feature <wbr/>Flag <wbr/>Configuration</span></a></li><li><a href="#md:tier-based-feature-matrix"><span>Tier-<wbr/>Based <wbr/>Feature <wbr/>Matrix</span></a></li><li><a href="#md:jwt-based-authentication"><span>JWT-<wbr/>Based <wbr/>Authentication</span></a></li><li><a href="#md:using-feature-flags-in-components"><span>Using <wbr/>Feature <wbr/>Flags in <wbr/>Components</span></a></li><li><a href="#md:subscription-state-management"><span>Subscription <wbr/>State <wbr/>Management</span></a></li><li><a href="#md:feature-restrictions--upgrade-prompts"><span>Feature <wbr/>Restrictions &amp; <wbr/>Upgrade <wbr/>Prompts</span></a></li><li><a href="#md:development--testing"><span>Development &amp; <wbr/>Testing</span></a></li><li><a href="#md:backend-integration"><span>Backend <wbr/>Integration</span></a></li></ul><a href="#md:🐛-debug-logger"><span>🐛 <wbr/>Debug <wbr/>Logger</span></a><a href="#md:🔒-security-best-practices"><span>🔒 <wbr/>Security <wbr/>Best <wbr/>Practices</span></a><ul><li><a href="#md:recommended-architecture"><span>Recommended <wbr/>Architecture</span></a></li><li><a href="#md:gateway-setup"><span>Gateway <wbr/>Setup</span></a></li><li><a href="#md:legacy-configuration-deprecated"><span>Legacy <wbr/>Configuration (<wbr/>Deprecated)</span></a></li><li><a href="#md:development-vs-production"><span>Development vs <wbr/>Production</span></a></li></ul><a href="#md:requirements"><span>Requirements</span></a><ul><li><a href="#md:gateway-api-services"><span>Gateway API <wbr/>Services</span></a></li><li><a href="#md:technology-agnostic-implementation"><span>Technology-<wbr/>Agnostic <wbr/>Implementation</span></a></li><li><a href="#md:additional-resources"><span>Additional <wbr/>Resources</span></a></li></ul><a href="#md:💡-vision--roadmap"><span>💡 <wbr/>Vision &amp; <wbr/>Roadmap</span></a><a href="#md:📌-migration-guide"><span>📌 <wbr/>Migration <wbr/>Guide</span></a><ul><li><a href="#md:from-legacy-ttsstt-urls-to-gateway-api"><span>From <wbr/>Legacy TTS/STT URLs to <wbr/>Gateway API</span></a></li></ul><a href="#md:🛡️-license--protection"><span>🛡️ <wbr/>License &amp; <wbr/>Protection</span></a><ul><li><a href="#md:⚖️-license-summary"><span>⚖️ <wbr/>License <wbr/>Summary</span></a></li><li><a href="#md:📋-usage-rights"><span>📋 <wbr/>Usage <wbr/>Rights</span></a></li><li><a href="#md:🔒-protection-features"><span>🔒 <wbr/>Protection <wbr/>Features</span></a></li><li><a href="#md:💼-commercial-licensing"><span>💼 <wbr/>Commercial <wbr/>Licensing</span></a></li><li><a href="#md:👨💻-for-contributors--developers"><span>👨‍💻 <wbr/>For <wbr/>Contributors &amp; <wbr/>Developers</span></a></li><li><a href="#md:📝-license-compliance"><span>📝 <wbr/>License <wbr/>Compliance</span></a></li></ul></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="modules.html" class="current"><svg class="tsd-kind-icon" viewBox="0 0 24 24"><use href="assets/icons.svg#icon-1"></use></svg><span>@burtson-labs/bandit-engine</span></a><ul class="tsd-small-nested-navigation" id="tsd-nav-container" data-base="."><li>Loading...</li></ul></nav></div></div></div><footer><p class="tsd-generator">Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></p></footer><div class="overlay"></div></body></html>