guideai-app 0.3.4 → 0.4.1

package/workflow-trigger-usage.md

@@ -0,0 +1,398 @@
+# Workflow Trigger Feature - Usage Guide
+
+## Overview
+
+The GuideAI package now supports workflow triggers based on trigger words detected in user messages. This feature allows you to create dynamic workflows that are activated when specific keywords or phrases are mentioned by users. Workflows are configured entirely through the `initialize-session` API endpoint.
+
+## Features
+
+✅ **Trigger Word Detection**: Automatically detect trigger words in user messages  
+✅ **Workflow Integration**: Seamlessly integrate with your backend workflow system  
+✅ **Dynamic Prompts**: Workflow-specific prompts from the initialize-session API  
+✅ **Tool-based Triggers**: AI can call workflow triggers through function calls  
+✅ **Configurable**: Support for multiple workflows with different trigger patterns  
+✅ **No Additional API**: All workflow configuration handled through initialize-session  
+
+## Setup
+
+### 1. Backend API Endpoint
+
+You only need to implement the `initialize-session` endpoint:
+
+#### POST `/initialize-session`
+Returns workflow-specific prompts, session data, and available workflows:
+
+```json
+{
+  "organizationKey": "your-org-key",
+  "workflowKey": "customer-support",
+  "userId": "anonymous",
+  "date": "2024-01-15",
+  "time": "14:30:00",
+  "messages": []
+}
+```
+
+Response:
+```json
+{
+  "id": "conversation-uuid",
+  "ephemeralToken": "openai-realtime-token",
+  "prompt": "You are Guide AI. Your role is to help users...",
+  "workflows": [
+    {
+      "id": "workflow-uuid",
+      "name": "Customer Support Workflow",
+      "triggers": ["help", "support", "customer service"],
+      "organizationKey": "org-key-123",
+      "prompt": "You are a helpful customer support agent...",
+      "archived": false,
+      "createdAt": "2024-01-01T00:00:00.000Z",
+      "updatedAt": "2024-01-01T00:00:00.000Z"
+    }
+  ]
+}
+```
+
+### 2. Frontend Configuration
+
+#### Basic Usage
+
+```typescript
+import GuideAI from 'guideai-app';
+
+function App() {
+  return (
+    <GuideAI 
+      organizationKey="your-organization-key"
+      workflowKey="customer-support"
+      position={{ bottom: '2rem', right: '2rem' }}
+      onError={(error) => console.error(error)}
+    />
+  );
+}
+```
+
+#### Advanced Configuration
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  workflowKey="customer-support"
+  position={{ bottom: '2rem', right: '2rem' }}
+  onError={(error) => console.error(error)}
+  transcript={{
+    enabled: true,
+    showToggleButton: true,
+    position: 'right'
+  }}
+  input={{
+    enableTextInput: true,
+    showInputToggle: true,
+    defaultMode: 'voice',
+    placeholder: "How can I help you today?"
+  }}
+/>
+```
+
+## How It Works
+
+### 1. Session Initialization
+When a conversation starts, the system:
+- Calls `/initialize-session` with the `workflowKey`
+- Receives a workflow-specific prompt and available workflows
+- Configures the AI with trigger word detection capabilities for each workflow
+
+### 2. Workflow Configuration
+The system automatically:
+- Creates individual tools for each active workflow
+- Configures trigger words for each workflow
+- Sets up function call handlers for workflow activation
+
+### 3. Trigger Word Detection
+The AI automatically:
+- Analyzes user messages for trigger words from all workflows
+- Detects patterns like "help", "support", "issue", "problem", etc.
+- Calls the appropriate `trigger_workflow_[id]` function when triggers are found
+
+### 4. Workflow Execution
+When triggers are detected:
+- The AI calls the specific workflow trigger function
+- The workflow's prompt is sent as a system message to guide the AI
+- The AI continues the conversation using the workflow-specific instructions
+
+## Workflow Data Schema
+
+```typescript
+interface Workflow {
+  id: string;                    // Unique workflow identifier
+  name: string;                  // Human-readable workflow name
+  triggers: string[];            // Array of trigger words/phrases
+  organizationKey: string;       // Organization this workflow belongs to
+  prompt: string;                // Workflow-specific prompt for the AI
+  archived: boolean;             // Whether the workflow is archived
+  createdAt: string;             // ISO timestamp of creation
+  updatedAt: string;             // ISO timestamp of last update
+}
+```
+
+## Example Workflows
+
+### Customer Support Workflow
+
+```json
+{
+  "id": "support-workflow-123",
+  "name": "Customer Support Workflow",
+  "triggers": ["help", "support", "issue", "problem", "broken"],
+  "organizationKey": "acme-corp",
+  "prompt": "You are a helpful customer support agent. When users have issues, be empathetic and provide clear solutions. Always ask for specific details about their problem and offer to escalate if needed.",
+  "archived": false,
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "updatedAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### Sales Workflow
+
+```json
+{
+  "id": "sales-workflow-456",
+  "name": "Sales Inquiry Workflow",
+  "triggers": ["pricing", "cost", "buy", "purchase", "quote"],
+  "organizationKey": "acme-corp",
+  "prompt": "You are a sales representative. When users ask about pricing or purchasing, provide detailed information about our products and services. Always ask about their specific needs and budget to provide the best recommendations.",
+  "archived": false,
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "updatedAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+### Technical Support Workflow
+
+```json
+{
+  "id": "tech-support-789",
+  "name": "Technical Support Workflow",
+  "triggers": ["error", "bug", "crash", "not working", "technical"],
+  "organizationKey": "acme-corp",
+  "prompt": "You are a technical support specialist. When users report technical issues, ask for specific error messages, steps to reproduce, and their system information. Provide troubleshooting steps and escalate complex issues.",
+  "archived": false,
+  "createdAt": "2024-01-01T00:00:00.000Z",
+  "updatedAt": "2024-01-01T00:00:00.000Z"
+}
+```
+
+## Configuration Options
+
+### Workflow Keys
+Different workflow keys can be used for different scenarios:
+
+- `customer-support`: General customer service
+- `sales-inquiry`: Sales and pricing questions
+- `technical-support`: Technical issues and bugs
+- `onboarding`: New user guidance
+- `billing`: Payment and billing issues
+
+### Trigger Word Patterns
+The system supports various trigger patterns:
+
+- **Exact matches**: "help", "support"
+- **Phrases**: "how to", "what is", "can you"
+- **Contextual**: "broken", "not working", "issue"
+
+## Best Practices
+
+### 1. Define Clear Trigger Words
+- Use specific, actionable trigger words
+- Avoid overly broad terms that might cause false positives
+- Consider synonyms and variations
+
+### 2. Write Effective Workflow Prompts
+- Be specific about the AI's role and behavior
+- Include guidelines for handling different scenarios
+- Provide examples of good responses
+
+### 3. Monitor and Optimize
+- Track which triggers are most effective
+- Adjust trigger words based on user behavior
+- Optimize workflow prompts based on feedback
+
+### 4. Handle Edge Cases
+- Provide fallback responses for unclear triggers
+- Handle multiple trigger words in the same message
+- Consider user context and conversation history
+
+## Error Handling
+
+The system includes robust error handling:
+
+- **Network errors**: Graceful fallback to default behavior
+- **Invalid workflows**: Logging and user-friendly error messages
+- **Missing workflow data**: Fallback to default prompt
+- **Archived workflows**: Automatically excluded from triggers
+
+## Integration Examples
+
+### React Application
+```typescript
+import GuideAI from 'guideai-app';
+
+function CustomerSupportPage() {
+  return (
+    <div>
+      <h1>Customer Support</h1>
+      <GuideAI
+        organizationKey="acme-corp"
+        workflowKey="customer-support"
+        position={{ bottom: '2rem', right: '2rem' }}
+        onError={(error) => {
+          console.error('GuideAI Error:', error);
+          // Handle error appropriately
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Next.js Application
+```typescript
+// app/support/page.tsx
+'use client';
+
+import GuideAI from 'guideai-app';
+
+export default function SupportPage() {
+  return (
+    <div>
+      <GuideAI
+        organizationKey={process.env.NEXT_PUBLIC_ORG_KEY}
+        workflowKey="customer-support"
+        position={{ bottom: '2rem', right: '2rem' }}
+        transcript={{ enabled: true, position: 'right' }}
+        input={{ enableTextInput: true, defaultMode: 'text' }}
+      />
+    </div>
+  );
+}
+```
+
+## Logging and Monitoring
+
+The system provides comprehensive logging for workflow events:
+
+### Console Logs
+All workflow events are logged to the browser console with clear formatting:
+
+```
+🔧 [2:30:15 PM] Workflows initialized: 3 active workflow(s)
+🎯 [2:30:45 PM] Trigger words detected: Customer Support Workflow
+🚀 [2:30:46 PM] Workflow activated: Customer Support Workflow
+```
+
+### Transcript Logs
+Workflow events are also logged in the conversation transcript:
+
+- **Workflow Initialization**: Shows all available workflows and their trigger words
+- **Trigger Detection**: Indicates when trigger words are detected in user messages
+- **Workflow Activation**: Confirms when a workflow is activated and provides context
+
+### Log Event Types
+
+1. **Workflow Initialization** (`workflow_init`)
+   - Logged when workflows are loaded from the API
+   - Shows total workflows and active workflows
+   - Lists all trigger words for each workflow
+
+2. **Trigger Detection** (`trigger_detected`)
+   - Logged when trigger words are found in user messages
+   - Shows which workflows were triggered
+   - Includes the user message that triggered them
+
+3. **Workflow Activation** (`workflow_activated`)
+   - Logged when a workflow is actually activated
+   - Shows the workflow name and trigger words used
+   - Includes the user message that caused activation
+
+### Debug Mode
+Enable detailed logging by checking the browser console:
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  workflowKey="customer-support"
+  onError={(error, context) => {
+    console.log('GuideAI Error:', { error, context });
+  }}
+/>
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Workflows not triggering**
+   - Check that workflows are returned in the `/initialize-session` response
+   - Verify trigger words are correctly defined
+   - Ensure workflows are not archived
+   - Check console logs for workflow initialization messages
+
+2. **No workflow prompt received**
+   - Verify `/initialize-session` endpoint returns a `workflows` array
+   - Check that `workflowKey` is being sent in the request
+   - Ensure backend is properly configured for the workflow
+   - Look for workflow initialization logs in console
+
+3. **Function calls not working**
+   - Check browser console for errors
+   - Verify WebRTC connection is established
+   - Ensure session configuration includes the workflow trigger tools
+   - Check for trigger detection logs in console
+
+### Debug Mode
+Enable debug logging to troubleshoot issues:
+
+```typescript
+<GuideAI
+  organizationKey="your-org-key"
+  workflowKey="customer-support"
+  onError={(error, context) => {
+    console.log('GuideAI Error:', { error, context });
+  }}
+/>
+```
+
+## API Reference
+
+### GuideAI Props
+```typescript
+interface GuideAIProps {
+  organizationKey: string;        // Required: Your organization key
+  workflowKey?: string;          // Optional: Workflow key for filtering
+  position?: PositionConfig;     // Optional: Component positioning
+  onError?: ErrorHandler;        // Optional: Error handling
+  // ... other props
+}
+```
+
+### Workflow API Endpoints
+- `POST /initialize-session`: Initialize conversation with workflows
+- `POST /conversations/{id}/messages`: Log conversation messages
+
+### Workflow Utilities
+```typescript
+// Detect which workflows should be triggered
+detectWorkflowTriggers(message: string, workflows: Workflow[]): Workflow[]
+
+// Get trigger words for a specific workflow
+getWorkflowTriggerWords(message: string, workflow: Workflow): string[]
+
+// Check if any workflows should be triggered
+hasWorkflowTriggers(message: string, workflows: Workflow[]): boolean
+
+// Get the most relevant workflow
+getMostRelevantWorkflow(message: string, workflows: Workflow[]): Workflow | null
+```
+
+This workflow trigger system provides a powerful way to create dynamic, context-aware AI interactions that can seamlessly integrate with your existing business processes and workflows, all configured through a single API endpoint.

package/dist/utils/highlight.d.ts

@@ -1,2 +0,0 @@
-export declare const clickElement: (element: Element, rect: DOMRect) => Promise<void>;
-export declare const highlightElement: (selector: string | string[], isHighlighting: boolean, setIsHighlighting: (highlighting: boolean) => void, logMessage: (content: string, sender: "GUIDEAI" | "HUMAN") => void) => Promise<boolean>;