@makemore/agent-frontend 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Agent Frontend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,229 @@
+# Agent Frontend
+
+A standalone, zero-dependency chat widget for AI agents. Embed conversational AI into any website with a single script tag.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/vanilla-JavaScript-yellow" alt="Vanilla JS">
+  <img src="https://img.shields.io/badge/size-~15kb-green" alt="Size">
+  <img src="https://img.shields.io/badge/dependencies-0-blue" alt="Zero Dependencies">
+  <img src="https://img.shields.io/badge/license-MIT-purple" alt="MIT License">
+</p>
+
+## Why Agent Frontend?
+
+Most chat widgets are tightly coupled to specific frameworks or require complex build setups. Agent Frontend is different:
+
+- **Zero dependencies** - Pure vanilla JavaScript, no React/Vue/Angular required
+- **CSS isolated** - Won't conflict with your existing styles (uses `all: initial` reset)
+- **SSE streaming** - Real-time token-by-token responses, not polling
+- **Production ready** - Session management, error handling, conversation persistence
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 💬 **Real-time Streaming** | SSE-based message streaming for instant, token-by-token responses |
+| 🎨 **Theming** | Customize colors, titles, messages, and position |
+| 🌙 **Dark Mode** | Automatic dark mode based on system preferences |
+| 📱 **Responsive** | Works seamlessly on desktop and mobile |
+| 🔧 **Debug Mode** | Toggle visibility of tool calls and results |
+| 🤖 **Demo Flows** | Built-in auto-run mode for showcasing agent journeys |
+| 🔒 **Sessions** | Automatic anonymous session creation and management |
+| 💾 **Persistence** | Conversations persist across page reloads via localStorage |
+| 🛡️ **Isolated CSS** | Scoped styles that won't leak into or from your page |
+
+## Quick Start
+
+### 1. Include the files
+
+```html
+<link rel="stylesheet" href="https://your-cdn.com/chat-widget.css">
+<script src="https://your-cdn.com/chat-widget.js"></script>
+```
+
+### 2. Initialize the widget
+
+```html
+<script>
+  ChatWidget.init({
+    backendUrl: 'https://your-api.com',
+    agentKey: 'your-agent',
+    title: 'Support Chat',
+    primaryColor: '#0066cc',
+  });
+</script>
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `backendUrl` | string | `'http://localhost:8000'` | Backend API URL |
+| `agentKey` | string | `'insurance-agent'` | Agent identifier |
+| `title` | string | `'Chat Assistant'` | Widget header title |
+| `subtitle` | string | `'How can we help you today?'` | Widget subtitle |
+| `primaryColor` | string | `'#0066cc'` | Primary theme color |
+| `position` | string | `'bottom-right'` | Widget position (`bottom-right` or `bottom-left`) |
+| `defaultJourneyType` | string | `'general'` | Default journey type |
+| `enableDebugMode` | boolean | `true` | Show debug toggle button |
+| `enableAutoRun` | boolean | `true` | Show demo flows dropdown |
+| `placeholder` | string | `'Type your message...'` | Input placeholder text |
+| `emptyStateTitle` | string | `'Start a Conversation'` | Empty state heading |
+| `emptyStateMessage` | string | `'Send a message to get started.'` | Empty state description |
+| `journeyTypes` | object | `{}` | Journey type definitions for demo flows |
+| `anonymousTokenHeader` | string | `'X-Anonymous-Token'` | Header name for auth token |
+| `conversationIdKey` | string | `'chat_widget_conversation_id'` | localStorage key for conversation ID |
+| `sessionTokenKey` | string | `'chat_widget_session_token'` | localStorage key for session token |
+
+## Journey Types Configuration
+
+Define demo flows that users can trigger from the dropdown:
+
+```javascript
+ChatWidget.init({
+  // ... other options
+  journeyTypes: {
+    quote: {
+      label: '🏠 Get a Quote',
+      description: 'Get an insurance quote',
+      initialMessage: "Hi, I'd like to get a quote for home insurance.",
+    },
+    claim: {
+      label: '📋 File a Claim',
+      description: 'File an insurance claim',
+      initialMessage: 'Hi, I need to file a claim.',
+    },
+  },
+});
+```
+
+## JavaScript API
+
+### Methods
+
+```javascript
+// Initialize the widget
+ChatWidget.init(config);
+
+// Open the chat widget
+ChatWidget.open();
+
+// Close the chat widget
+ChatWidget.close();
+
+// Send a message programmatically
+ChatWidget.send('Hello, I need help!');
+
+// Clear the conversation
+ChatWidget.clearMessages();
+
+// Start a demo flow
+ChatWidget.startDemoFlow('quote');
+
+// Stop auto-run mode
+ChatWidget.stopAutoRun();
+
+// Remove the widget from the page
+ChatWidget.destroy();
+
+// Get current state (read-only)
+const state = ChatWidget.getState();
+
+// Get current config (read-only)
+const config = ChatWidget.getConfig();
+```
+
+## Backend Requirements
+
+The widget expects a backend API with the following endpoints:
+
+### Create Anonymous Session
+```
+POST /api/accounts/anonymous-session/
+Response: { "token": "..." }
+```
+
+### Create Agent Run
+```
+POST /api/agent-runtime/runs/
+Headers: { "X-Anonymous-Token": "..." }
+Body: {
+  "agentKey": "...",
+  "conversationId": "...",
+  "messages": [{ "role": "user", "content": "..." }],
+  "metadata": { "journey_type": "..." }
+}
+Response: { "id": "...", "conversationId": "..." }
+```
+
+### SSE Events Stream
+```
+GET /api/agent-runtime/runs/{runId}/events/?anonymous_token=...
+Events: assistant.message, tool.call, tool.result, run.succeeded, run.failed
+```
+
+### Simulate Customer (for demo flows)
+```
+POST /api/agent-runtime/simulate-customer/
+Body: { "messages": [...], "journey_type": "..." }
+Response: { "response": "..." }
+```
+
+## CSS Isolation
+
+The widget uses multiple techniques to prevent style conflicts:
+
+```css
+.cw-container {
+  all: initial;           /* Reset all inherited styles */
+  /* ... widget styles scoped here */
+}
+
+.cw-container *,
+.cw-container *::before,
+.cw-container *::after {
+  box-sizing: border-box; /* Consistent box model */
+}
+```
+
+- All CSS classes prefixed with `cw-`
+- CSS variables scoped to `.cw-container`, not `:root`
+- High z-index (99999) to stay above host page content
+- Font smoothing reset for consistent text rendering
+
+## Development
+
+```bash
+# Clone and serve locally
+git clone <repo-url>
+cd agent-frontend
+python -m http.server 8080
+
+# Open http://localhost:8080/demo.html
+```
+
+### File Structure
+
+```
+agent-frontend/
+├── dist/
+│   ├── chat-widget.js    # Main library (~750 lines, ~15kb)
+│   └── chat-widget.css   # Styles (~500 lines, ~8kb)
+├── demo.html             # Interactive demo page
+└── README.md
+```
+
+## Browser Support
+
+| Browser | Version |
+|---------|---------|
+| Chrome | 60+ |
+| Firefox | 55+ |
+| Safari | 11+ |
+| Edge | 79+ |
+
+Requires: `EventSource` (SSE), `fetch`, `localStorage`
+
+## License
+
+MIT © 2024