@astermind/chatbot-template 1.0.3 → 2.1.2

package/README.md

@@ -9,11 +9,12 @@ Embeddable AI chatbot widget for [AsterMind](https://astermind.ai) RAG - a drop-
 
 ## Table of Contents
 
+- [Architecture](#architecture)
 - [Features](#features)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
+- [Configuration in Your Application](#configuration-in-your-application)
 - [Configuration Reference](#configuration-reference)
-- [Cybernetic Chatbot Integration](#cybernetic-chatbot-integration)
 - [Theming](#theming)
 - [React Hooks API](#react-hooks-api)
 - [Components API](#components-api)
@@ -24,24 +25,63 @@ Embeddable AI chatbot widget for [AsterMind](https://astermind.ai) RAG - a drop-
 
 ---
 
+## Architecture
+
+This package is the **UI layer** for the AsterMind Chatbot system. It provides pre-built React components and hooks for embedding a chatbot in your application.
+
+### Package Dependencies
+
+```
+Your Application
+    │
+    └── @astermind/chatbot-template (this package - UI components)
+            │
+            └── @astermind/cybernetic-chatbot-client (required - API client)
+```
+
+**Important**: `@astermind/cybernetic-chatbot-client` is automatically installed as a dependency. It provides:
+
+- **API Communication** - Connects to your AsterMind backend
+- **Streaming Responses** - SSE-based token-by-token message display
+- **Offline Fallback** - Local RAG processing with IndexedDB cache
+- **Agentic Capabilities** - DOM interactions (optional, tree-shakeable)
+
+### Where to Configure
+
+All configuration is done in **your application code**, not in node_modules:
+
+| Configuration Method | Where to Set |
+|---------------------|--------------|
+| React Props | In your component: `<ChatbotWidget apiKey="..." />` |
+| Environment Variables | In your `.env` file |
+| SSR Injection | In your server template |
+| Global Object | In your HTML/JS before loading |
+| Data Attributes | On your script tag |
+
+---
+
 ## Features
 
-### Core Widget Features
+### Core Widget Features (this package)
 
 - **Embeddable Floating Chat Bubble** - Position anywhere on the page (4 corners)
 - **React Components Library** - 11 fully customizable components
 - **Vanilla JS Standalone Bundle** - IIFE format with React bundled for non-React sites
 - **Full TypeScript Support** - Complete type definitions exported
+- **Theming System** - 20+ CSS custom properties for full visual customization
 
-### RAG Integration
+### RAG & Backend Features (via cybernetic-chatbot-client)
 
 - **AsterMind Backend Integration** - Connects to `/api/external/chat` endpoints
 - **Streaming Responses** - SSE-based token-by-token message display
 - **Source Citations** - Collapsible source references with confidence levels
 - **Session Management** - Automatic sessionId handling across conversations
-- **Confidence Indicators** - Visual display of high/medium/low/none confidence
+- **Offline Fallback** - Local RAG processing when backend is unavailable
+- **Connection Status** - Automatic online/offline/connecting/error states
+
+### Agentic Capabilities (via cybernetic-chatbot-client)
 
-### Agentic Capabilities
+When enabled, the chatbot can perform actions on your page:
 
 - **Navigation Actions** - Navigate users to specific pages
 - **Form Filling** - Auto-fill form fields with suggested values
@@ -50,26 +90,8 @@ Embeddable AI chatbot widget for [AsterMind](https://astermind.ai) RAG - a drop-
 - **Scrolling** - Scroll to specific elements
 - **Element Highlighting** - Draw attention to page elements
 - **Custom Action Handlers** - Define your own action types
-- **Action Cards UI** - Confirm/cancel interface for proposed actions
-- **Confidence Thresholds** - Auto-execute high-confidence actions
-- **Site Map Configuration** - Define navigable pages for the agent
-
-### Offline & Fallback
-
-- **Graceful Degradation** - Works when connection is lost
-- **Custom Offline Message** - Configure what users see offline
-- **Connection Status Indicator** - Shows online/offline/connecting/error states
-- **Optional Local RAG Fallback** - Use Cybernetic RAG locally when offline
 
-### Theming & Customization
-
-- **20+ CSS Custom Properties** - Full visual customization via CSS variables
-- **JavaScript Theme Object** - Configure themes programmatically
-- **4 Position Options** - bottom-right, bottom-left, top-right, top-left
-- **Configurable Dimensions** - Width, height, bubble size
-- **Full Color Customization** - Every color is customizable
-- **Typography Settings** - Font family and size
-- **Border Radius & Shadows** - Visual effects customization
+Agentic capabilities are tree-shakeable - they're only included in your bundle if you import and use them.
 
 ---
 
@@ -81,6 +103,8 @@ Embeddable AI chatbot widget for [AsterMind](https://astermind.ai) RAG - a drop-
 npm install @astermind/chatbot-template
 ```
 
+This automatically installs `@astermind/cybernetic-chatbot-client` as a dependency.
+
 ### CDN (Vanilla JS)
 
 ```html
@@ -134,14 +158,108 @@ function App() {
 
 ---
 
+## Configuration in Your Application
+
+All configuration is done in **your application code**. The chatbot-template reads configuration from several sources in your project.
+
+### React Applications
+
+**Option 1: Pass props directly**
+```tsx
+<ChatbotWidget
+  apiUrl="https://api.astermind.ai"
+  apiKey="am_your-api-key"
+  position="bottom-right"
+/>
+```
+
+**Option 2: Use environment variables**
+
+Create a `.env` file in your project root:
+
+```env
+# Vite projects
+VITE_ASTERMIND_RAG_API_KEY=am_your_api_key
+VITE_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai
+
+# Create React App projects
+REACT_APP_ASTERMIND_RAG_API_KEY=am_your_api_key
+REACT_APP_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai
+```
+
+Then use the widget without explicit props:
+```tsx
+<ChatbotWidget position="bottom-right" />
+```
+
+### Vanilla JS Applications
+
+**Option 1: Pass config to init()**
+```javascript
+AsterMindChatbot.init({
+  apiKey: 'am_your_api_key',
+  apiUrl: 'https://api.astermind.ai',
+  position: 'bottom-right'
+});
+```
+
+**Option 2: Global config object**
+```html
+<script>
+  window.astermindConfig = {
+    apiKey: 'am_your_api_key',
+    apiUrl: 'https://api.astermind.ai'
+  };
+</script>
+<script src="astermind-chatbot.min.js"></script>
+<script>
+  AsterMindChatbot.init();
+</script>
+```
+
+**Option 3: Script data attributes**
+```html
+<script
+  src="astermind-chatbot.min.js"
+  data-astermind-key="am_your_api_key"
+  data-astermind-url="https://api.astermind.ai"
+></script>
+```
+
+### SSR / Server-Side Rendering
+
+For Next.js, Nuxt, or other SSR frameworks:
+
+```html
+<script>
+  window.__ASTERMIND_CONFIG__ = {
+    apiKey: '<%= process.env.ASTERMIND_RAG_API_KEY %>',
+    apiUrl: '<%= process.env.ASTERMIND_RAG_API_SERVER_URL %>'
+  };
+</script>
+```
+
+---
+
 ## Configuration Reference
 
-### Required Options
+### Configuration Priority
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `apiKey` | `string` | Your AsterMind API key (starts with `am_`) |
-| `apiUrl` | `string` | Backend API URL (e.g., `https://api.example.com`) |
+The widget supports multiple configuration methods with this priority (highest to lowest):
+
+1. **Props / init() config** - Direct configuration passed to the component or `init()` function
+2. **Environment variables** - `VITE_ASTERMIND_RAG_API_KEY`, `REACT_APP_ASTERMIND_RAG_API_KEY`
+3. **SSR-injected config** - `window.__ASTERMIND_CONFIG__`
+4. **Global object** - `window.astermindConfig`
+5. **Script data attributes** - `data-astermind-key`, `data-astermind-url`
+
+### API Key and URL
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | (from env) | Your AsterMind API key (starts with `am_`). Falls back to environment variables. |
+| `apiUrl` | `string` | `'https://api.astermind.ai'` | Backend API URL. Falls back to environment variables. |
+| `throwOnMissingKey` | `boolean` | `true` | Throw error if API key is missing. Set to `false` to log warning instead. |
 
 ### Widget Options
 
@@ -163,21 +281,21 @@ Customize appearance via the `theme` object:
 ```javascript
 {
   theme: {
-    primaryColor: '#4F46E5',        // Primary brand color
-    primaryHover: '#4338CA',        // Primary color on hover
-    backgroundColor: '#ffffff',     // Background color
-    surfaceColor: '#f3f4f6',        // Surface/card background
-    textColor: '#1f2937',           // Primary text color
-    textMuted: '#6b7280',           // Muted/secondary text
-    borderColor: '#e5e7eb',         // Border color
-    userBubbleBackground: '#4F46E5', // User message background
-    userBubbleText: '#ffffff',      // User message text
-    botBubbleBackground: '#f3f4f6', // Bot message background
-    botBubbleText: '#1f2937',       // Bot message text
-    widgetWidth: '380px',           // Widget width
-    widgetHeight: '520px',          // Widget height
-    bubbleSize: '60px',             // Trigger bubble size
-    borderRadius: '12px',           // Border radius
+    primaryColor: '#4F46E5',
+    primaryHover: '#4338CA',
+    backgroundColor: '#ffffff',
+    surfaceColor: '#f3f4f6',
+    textColor: '#1f2937',
+    textMuted: '#6b7280',
+    borderColor: '#e5e7eb',
+    userBubbleBackground: '#4F46E5',
+    userBubbleText: '#ffffff',
+    botBubbleBackground: '#f3f4f6',
+    botBubbleText: '#1f2937',
+    widgetWidth: '380px',
+    widgetHeight: '520px',
+    bubbleSize: '60px',
+    borderRadius: '12px',
     fontFamily: "'Inter', system-ui, sans-serif",
     fontSize: '14px',
     shadow: '0 4px 20px rgba(0, 0, 0, 0.15)'
@@ -187,26 +305,20 @@ Customize appearance via the `theme` object:
 
 ### Agent Configuration
 
-Enable agentic capabilities:
+Enable agentic capabilities (powered by cybernetic-chatbot-client):
 
 ```javascript
 {
   agent: {
     enabled: true,
-    confidenceThreshold: 0.8,     // Minimum confidence for auto-execution
+    confidenceThreshold: 0.8,
     siteMap: [
       { path: '/products', name: 'Products', description: 'View products' },
-      { path: '/contact', name: 'Contact', description: 'Contact us' },
-      { path: '/pricing', name: 'Pricing', description: 'View pricing plans' }
+      { path: '/contact', name: 'Contact', description: 'Contact us' }
     ],
     customActions: {
       openModal: async (params) => {
-        // Custom action handler - open a modal
         document.getElementById(params.modalId).showModal();
-      },
-      trackEvent: async (params) => {
-        // Custom analytics tracking
-        analytics.track(params.eventName, params.data);
       }
     }
   }
@@ -238,48 +350,6 @@ Configure offline behavior:
 
 ---
 
-## Cybernetic Chatbot Integration
-
-This widget is designed to work seamlessly with the `@astermind/cybernetic-chatbot-client` for advanced RAG capabilities.
-
-### How It Works
-
-1. **Widget sends messages** to your AsterMind backend via the configured `apiUrl`
-2. **Backend processes queries** using your RAG pipeline and returns responses
-3. **Streaming responses** arrive via Server-Sent Events (SSE) for real-time display
-4. **Agentic actions** are proposed by the AI and confirmed via Action Cards
-
-### API Endpoints
-
-The widget connects to these backend endpoints:
-
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/api/external/health` | GET | Health check, verifies connection |
-| `/api/external/chat` | POST | Non-streaming chat endpoint |
-| `/api/external/chat/stream` | POST | Streaming chat endpoint (SSE) |
-
-### SSE Event Format
-
-```
-data: {"type": "chunk", "content": "Hello"}
-data: {"type": "chunk", "content": " there!"}
-data: {"type": "sources", "sources": [{"title": "Doc", "url": "..."}]}
-data: {"type": "action", "action": {"type": "navigate", "path": "/products"}}
-data: {"type": "done", "sessionId": "sess_xxx"}
-data: {"type": "error", "error": "Error message"}
-```
-
-### Offline Fallback
-
-When offline or disconnected:
-
-1. Widget shows connection status indicator
-2. Custom offline message is displayed
-3. If `@astermind/cybernetic-chatbot-client` is installed with local RAG enabled, queries can still be processed locally
-
----
-
 ## Theming
 
 ### CSS Variables
@@ -288,7 +358,6 @@ Override CSS variables in your stylesheet for quick customization:
 
 ```css
 :root {
-  /* Colors */
   --astermind-primary: #10B981;
   --astermind-primary-hover: #059669;
   --astermind-background: #ffffff;
@@ -296,25 +365,15 @@ Override CSS variables in your stylesheet for quick customization:
   --astermind-text: #1f2937;
   --astermind-text-muted: #6b7280;
   --astermind-border: #e5e7eb;
-
-  /* User messages */
   --astermind-user-bubble-bg: #10B981;
   --astermind-user-bubble-text: #ffffff;
-
-  /* Bot messages */
   --astermind-bot-bubble-bg: #f3f4f6;
   --astermind-bot-bubble-text: #1f2937;
-
-  /* Dimensions */
   --astermind-widget-width: 400px;
   --astermind-widget-height: 600px;
   --astermind-bubble-size: 64px;
-
-  /* Effects */
   --astermind-border-radius: 16px;
   --astermind-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
-
-  /* Typography */
   --astermind-font-family: 'Inter', system-ui, sans-serif;
   --astermind-font-size: 14px;
 }
@@ -322,7 +381,7 @@ Override CSS variables in your stylesheet for quick customization:
 
 ### CSS Classes
 
-All elements use the `astermind-` prefix for easy targeting:
+All elements use the `astermind-` prefix:
 
 | Class | Element |
 |-------|---------|
@@ -343,12 +402,12 @@ All elements use the `astermind-` prefix for easy targeting:
 
 ## React Hooks API
 
-### useOmega
+### useCybernetic
 
 Direct API client access for custom implementations:
 
 ```tsx
-import { useOmega } from '@astermind/chatbot-template';
+import { useCybernetic } from '@astermind/chatbot-template';
 
 function MyComponent() {
   const {
@@ -358,8 +417,10 @@ function MyComponent() {
     isProcessing,       // Whether a request is in progress
     lastError,          // Last error that occurred
     sessionId,          // Current session ID
-    clearSession        // Clear the current session
-  } = useOmega({
+    clearSession,       // Clear the current session
+    syncCache,          // Sync cache for offline use
+    client              // Underlying CyberneticClient instance
+  } = useCybernetic({
     apiUrl: 'https://api.example.com',
     apiKey: 'am_your-api-key'
   });
@@ -368,15 +429,6 @@ function MyComponent() {
     const response = await sendMessage('Hello!');
     console.log(response.reply, response.sources);
   };
-
-  const handleStreamingSend = () => {
-    sendMessageStream('Tell me about...', {
-      onChunk: (chunk) => console.log('Chunk:', chunk),
-      onSources: (sources) => console.log('Sources:', sources),
-      onDone: (sessionId) => console.log('Done:', sessionId),
-      onError: (error) => console.error('Error:', error)
-    });
-  };
 }
 ```
 
@@ -412,7 +464,6 @@ function MyComponent() {
     borderRadius: '16px'
   });
 
-  // cssVariables contains the CSS custom property declarations
   return <div style={cssVariables}>...</div>;
 }
 ```
@@ -457,48 +508,6 @@ import {
 } from '@astermind/chatbot-template';
 ```
 
-### Component Example
-
-Build a custom chat interface:
-
-```tsx
-import {
-  ChatWindow,
-  ChatHeader,
-  MessageList,
-  MessageBubble,
-  ChatInput,
-  StatusIndicator
-} from '@astermind/chatbot-template';
-import '@astermind/chatbot-template/styles';
-
-function CustomChat({ messages, onSend, status }) {
-  return (
-    <ChatWindow>
-      <ChatHeader
-        title="Support Bot"
-        subtitle="Always here to help"
-      />
-      <StatusIndicator status={status} />
-      <MessageList>
-        {messages.map(msg => (
-          <MessageBubble
-            key={msg.id}
-            content={msg.content}
-            role={msg.role}
-            timestamp={msg.timestamp}
-          />
-        ))}
-      </MessageList>
-      <ChatInput
-        onSend={onSend}
-        placeholder="Ask a question..."
-      />
-    </ChatWindow>
-  );
-}
-```
-
 ---
 
 ## TypeScript Support
@@ -507,33 +516,35 @@ Full TypeScript support with exported types:
 
 ```typescript
 import type {
-  // Configuration
-  ChatbotConfig,
-  ThemeConfig,
-  AgentConfig,
-  FallbackConfig,
-
-  // Messages
+  // Template-specific types
+  AsterMindChatbotProps,
+  ChatbotTheme,
   ChatMessage,
-  MessageRole,
-
-  // Actions
   AgentAction,
-  ActionType,
-  NavigateAction,
-  FormFillAction,
-  ClickAction,
-
-  // Sources
+  ChatState,
+  WidgetPosition,
+  AgentConfig,
+  FallbackConfig,
+  SiteMapEntry,
+  VanillaInitConfig,
+  SendOptions,
+
+  // Re-exported from @astermind/cybernetic-chatbot-client
+  CyberneticConfig,
+  CyberneticResponse,
+  CyberneticError,
   Source,
-  SourceCitation,
-
-  // Status
   ConnectionStatus,
-
-  // Events
-  ChatbotCallbacks
+  ConfidenceLevel,
+  StreamCallbacks,
+  AskOptions,
+  CachedDocument,
+  CacheStatus,
+  AgenticConfig
 } from '@astermind/chatbot-template';
+
+// CyberneticClient class is also re-exported for advanced usage
+import { CyberneticClient } from '@astermind/chatbot-template';
 ```
 
 ---