@hef2024/llmasaservice-ui 0.17.0 → 0.18.0

package/docs/CONVERSATION-STARTING.md

@@ -0,0 +1,815 @@
+# Conversation Starting Guide
+
+This guide covers the two ways to automatically start conversations with prompts in AIAgentPanel: the **declarative `initialPrompt` prop** and the **imperative `startNewConversation` API**.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Method 1: initialPrompt (Declarative)](#method-1-initialprompt-declarative)
+- [Method 2: startNewConversation (Imperative)](#method-2-startnewconversation-imperative)
+- [Comparison](#comparison)
+- [Common Use Cases](#common-use-cases)
+- [API Reference](#api-reference)
+- [Examples](#examples)
+
+---
+
+## Overview
+
+AIAgentPanel provides two complementary approaches for starting conversations with pre-filled prompts:
+
+| Feature | Type | When to Use |
+|---------|------|-------------|
+| **initialPrompt** | Declarative (prop) | Global default for all new conversations |
+| **startNewConversation** | Imperative (method) | Programmatic, conversation-specific prompts |
+
+### Key Differences
+
+```typescript
+// initialPrompt: Applies to ALL new conversations
+<AIAgentPanel initialPrompt="Hello!" {...props} />
+
+// startNewConversation: Specific to ONE conversation
+panelRef.current?.startNewConversation("Hello from code!");
+```
+
+---
+
+## Method 1: initialPrompt (Declarative)
+
+The `initialPrompt` prop sets a **global default prompt** that applies to all new conversations created through the UI.
+
+### Basic Usage
+
+```typescript
+import AIAgentPanel from '@hef2024/llmasaservice-ui';
+
+function App() {
+  return (
+    <AIAgentPanel
+      initialPrompt="Introduce yourself and explain what you can help with"
+      hideInitialPrompt={false}
+      agents={['agent-1', 'agent-2']}
+      customerId="user-123"
+    />
+  );
+}
+```
+
+### How It Works
+
+1. **Set Once**: You pass `initialPrompt` as a prop to AIAgentPanel
+2. **Applies Globally**: Every time a user clicks "New Conversation" (+ button), this prompt is automatically sent
+3. **User Can Override**: The prompt is sent via the existing AIChatPanel effect
+4. **Persistent**: Remains active until you change or remove the prop
+
+### When to Use initialPrompt
+
+✅ **Good for:**
+- Onboarding prompts for new users
+- Context-aware welcomes based on the current page
+- Setting a consistent starting experience
+- Guiding users on what the agent can do
+
+❌ **Not ideal for:**
+- One-time programmatic actions
+- Different prompts for different scenarios
+- Button-triggered specific queries
+- Dynamic conversation starting
+
+### Example: Context-Aware Welcome
+
+```typescript
+function App() {
+  const [currentPage, setCurrentPage] = useState('dashboard');
+  
+  // Different welcome message based on page
+  const contextPrompt = useMemo(() => {
+    switch (currentPage) {
+      case 'dashboard':
+        return 'Give me an overview of my dashboard metrics';
+      case 'analytics':
+        return 'What insights can you show me from my data?';
+      case 'settings':
+        return 'Help me understand my available settings';
+      default:
+        return 'What can you help me with?';
+    }
+  }, [currentPage]);
+  
+  return (
+    <AIAgentPanel
+      initialPrompt={contextPrompt}
+      hideInitialPrompt={false}
+      // ... other props
+    />
+  );
+}
+```
+
+### Props Related to initialPrompt
+
+```typescript
+interface AIAgentPanelProps {
+  initialPrompt?: string;           // The prompt to send automatically
+  hideInitialPrompt?: boolean;       // Show/hide the prompt in chat (default: true)
+  initialMessage?: string;           // Non-sent message (just displayed)
+}
+```
+
+---
+
+## Method 2: startNewConversation (Imperative)
+
+The `startNewConversation` API allows you to **programmatically create conversations** with specific prompts via a ref.
+
+### Basic Usage
+
+```typescript
+import { useRef } from 'react';
+import AIAgentPanel, { AIAgentPanelHandle } from '@hef2024/llmasaservice-ui';
+
+function App() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  const handleQuickStart = () => {
+    panelRef.current?.startNewConversation(
+      "What's my progress this week?",
+      "fitness-agent" // optional: specific agent
+    );
+  };
+  
+  return (
+    <>
+      <button onClick={handleQuickStart}>Quick Start</button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['fitness-agent', 'nutrition-agent']}
+        customerId="user-123"
+      />
+    </>
+  );
+}
+```
+
+### How It Works
+
+1. **Create Ref**: Use `useRef<AIAgentPanelHandle>(null)` to create a ref
+2. **Pass Ref**: Attach the ref to AIAgentPanel with `ref={panelRef}`
+3. **Call Method**: Invoke `panelRef.current?.startNewConversation(prompt, agent?)`
+4. **Auto-Send**: The prompt is automatically sent in the new conversation
+
+### API Signature
+
+```typescript
+interface AIAgentPanelHandle {
+  startNewConversation: (prompt: string, agent?: string) => void;
+}
+```
+
+**Parameters:**
+- `prompt` (string, required): The message to send automatically
+- `agent` (string, optional): Specific agent ID. If omitted, uses the currently selected agent
+
+**Returns:** `void`
+
+### When to Use startNewConversation
+
+✅ **Good for:**
+- Quick action buttons ("Get my summary", "Ask about X")
+- Programmatic conversation creation from external triggers
+- Different prompts for different UI actions
+- Context-specific queries from buttons/links
+- Integration with other app features
+
+❌ **Not ideal for:**
+- Setting a default welcome message (use `initialPrompt` instead)
+- Prompts that apply to all conversations
+- Non-programmatic scenarios
+
+### Example: Quick Action Buttons
+
+```typescript
+function QuickActions() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  return (
+    <div>
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(
+          'Give me a summary of my weekly progress'
+        )
+      }>
+        📊 Weekly Summary
+      </button>
+      
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(
+          'What should I focus on today?'
+        )
+      }>
+        🎯 Today's Focus
+      </button>
+      
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(
+          'Analyze my nutrition intake for this week',
+          'nutrition-agent' // specific agent
+        )
+      }>
+        🥗 Nutrition Check
+      </button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['fitness-agent', 'nutrition-agent']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Comparison
+
+### Feature Comparison Table
+
+| Feature | initialPrompt | startNewConversation |
+|---------|---------------|---------------------|
+| **Invocation** | Declarative (prop) | Imperative (method call) |
+| **Scope** | Global (all new conversations) | Per-conversation |
+| **When Applied** | When user clicks "+" button | When method is called |
+| **User Interaction** | Requires user to start conversation | Creates conversation immediately |
+| **Dynamic** | Changes affect future conversations | Each call is independent |
+| **Agent Selection** | Uses current agent | Can specify agent per call |
+| **Best For** | Default welcome prompts | Programmatic actions |
+
+### Side-by-Side Example
+
+```typescript
+function ComparisonExample() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  return (
+    <div>
+      {/* initialPrompt: User must click + button */}
+      <AIAgentPanel
+        ref={panelRef}
+        initialPrompt="Welcome! How can I help you today?"
+        hideInitialPrompt={false}
+        // This prompt applies when user creates conversation via UI
+      />
+      
+      {/* startNewConversation: Immediate, no user action needed */}
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(
+          "Show me my dashboard summary"
+        )
+      }>
+        Get Summary Now
+      </button>
+    </div>
+  );
+}
+```
+
+### Behavior Differences
+
+```typescript
+// Scenario 1: initialPrompt
+<AIAgentPanel initialPrompt="Hello" />
+// User clicks "+" → New conversation created → "Hello" is sent
+
+// Scenario 2: startNewConversation
+panelRef.current?.startNewConversation("Hello");
+// New conversation created immediately → "Hello" is sent → No user action needed
+```
+
+---
+
+## Common Use Cases
+
+### Use Case 1: Quick Action Dashboard
+
+Combine both approaches for maximum flexibility:
+
+```typescript
+function Dashboard() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  const [currentPage, setCurrentPage] = useState('home');
+  
+  // Global welcome for manually created conversations
+  const welcomePrompt = `Welcome to ${currentPage}! What would you like to know?`;
+  
+  return (
+    <div>
+      {/* Quick action buttons */}
+      <div className="quick-actions">
+        <button onClick={() => 
+          panelRef.current?.startNewConversation(
+            'Summarize my metrics for today'
+          )
+        }>
+          Daily Summary
+        </button>
+        
+        <button onClick={() => 
+          panelRef.current?.startNewConversation(
+            'What tasks need my attention?'
+          )
+        }>
+          Action Items
+        </button>
+      </div>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        initialPrompt={welcomePrompt}
+        hideInitialPrompt={false}
+        agents={['assistant']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Use Case 2: Contextual Help System
+
+```typescript
+function ContextualHelp({ currentFeature }: { currentFeature: string }) {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  const getHelpForFeature = () => {
+    const helpPrompts = {
+      'charts': 'Explain how to use the charts feature',
+      'export': 'Walk me through the export options',
+      'settings': 'What settings should I configure?',
+    };
+    
+    panelRef.current?.startNewConversation(
+      helpPrompts[currentFeature] || 'How can you help me?'
+    );
+  };
+  
+  return (
+    <div>
+      <button onClick={getHelpForFeature}>
+        Get Help with {currentFeature}
+      </button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        initialPrompt="I'm here to help! What do you need assistance with?"
+        agents={['help-agent']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Use Case 3: Onboarding Flow
+
+```typescript
+function OnboardingFlow() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  const [step, setStep] = useState(1);
+  
+  const startOnboarding = () => {
+    const onboardingSteps = [
+      "Let's get you started! Tell me about your goals.",
+      "Great! Now let's set up your preferences.",
+      "Finally, let me show you around the interface.",
+    ];
+    
+    panelRef.current?.startNewConversation(onboardingSteps[step - 1]);
+  };
+  
+  return (
+    <div>
+      <button onClick={startOnboarding}>
+        Start Onboarding Step {step}
+      </button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['onboarding-agent']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Use Case 4: URL-Based Conversation Starter
+
+```typescript
+function URLBasedStarter() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  const [searchParams] = useSearchParams();
+  
+  useEffect(() => {
+    // Start conversation based on URL parameter
+    const query = searchParams.get('ask');
+    if (query && panelRef.current) {
+      panelRef.current.startNewConversation(query);
+    }
+  }, [searchParams]);
+  
+  return (
+    <AIAgentPanel
+      ref={panelRef}
+      agents={['assistant']}
+      customerId="user-123"
+    />
+  );
+}
+
+// Usage: Navigate to /app?ask=What%20is%20my%20status
+```
+
+---
+
+## API Reference
+
+### AIAgentPanel Props
+
+```typescript
+interface AIAgentPanelProps {
+  // ... other props
+  
+  // Initial prompt for all new conversations (global)
+  initialPrompt?: string;
+  
+  // Whether to hide the initial prompt in chat UI
+  hideInitialPrompt?: boolean;
+  
+  // Initial message (displayed but not sent)
+  initialMessage?: string;
+}
+```
+
+### AIAgentPanelHandle (Ref API)
+
+```typescript
+export interface AIAgentPanelHandle {
+  /**
+   * Programmatically start a new conversation with an auto-sent prompt
+   * 
+   * @param prompt - The message to send automatically
+   * @param agent - (Optional) Specific agent ID. Defaults to current agent.
+   * 
+   * @example
+   * // Start conversation with default agent
+   * panelRef.current?.startNewConversation('Hello!');
+   * 
+   * @example
+   * // Start conversation with specific agent
+   * panelRef.current?.startNewConversation('Analyze my data', 'analytics-agent');
+   */
+  startNewConversation: (prompt: string, agent?: string) => void;
+}
+```
+
+### TypeScript Usage
+
+```typescript
+import { useRef } from 'react';
+import AIAgentPanel, { AIAgentPanelHandle } from '@hef2024/llmasaservice-ui';
+
+function TypedExample() {
+  // Properly typed ref
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  const handleAction = () => {
+    // TypeScript ensures type safety
+    panelRef.current?.startNewConversation(
+      'Your prompt here',
+      'optional-agent-id'
+    );
+  };
+  
+  return (
+    <AIAgentPanel
+      ref={panelRef}
+      agents={['agent-1']}
+      customerId="user-123"
+    />
+  );
+}
+```
+
+---
+
+## Examples
+
+### Example 1: Simple Quick Start Button
+
+```typescript
+import { useRef } from 'react';
+import AIAgentPanel, { AIAgentPanelHandle } from '@hef2024/llmasaservice-ui';
+
+function SimpleExample() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  return (
+    <div>
+      <button onClick={() => 
+        panelRef.current?.startNewConversation('Hello!')
+      }>
+        Quick Start
+      </button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['my-agent']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Example 2: Multiple Quick Actions
+
+```typescript
+function MultipleActions() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  const quickActions = [
+    { label: 'Daily Summary', prompt: 'Give me my daily summary' },
+    { label: 'To-Do List', prompt: 'What tasks do I have today?' },
+    { label: 'Recommendations', prompt: 'What should I focus on?' },
+  ];
+  
+  return (
+    <div>
+      {quickActions.map(action => (
+        <button
+          key={action.label}
+          onClick={() => panelRef.current?.startNewConversation(action.prompt)}
+        >
+          {action.label}
+        </button>
+      ))}
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['assistant']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Example 3: Agent-Specific Actions
+
+```typescript
+function AgentSpecificActions() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  
+  return (
+    <div>
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(
+          'Analyze my fitness data',
+          'fitness-agent'
+        )
+      }>
+        Fitness Check
+      </button>
+      
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(
+          'Review my nutrition plan',
+          'nutrition-agent'
+        )
+      }>
+        Nutrition Review
+      </button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['fitness-agent', 'nutrition-agent']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Example 4: Combining Both Approaches
+
+```typescript
+function CombinedApproach() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  const [page, setPage] = useState('dashboard');
+  
+  // Global welcome for UI-created conversations
+  const welcomePrompt = `Welcome to the ${page}! How can I help?`;
+  
+  return (
+    <div>
+      {/* Programmatic quick starts */}
+      <div className="quick-actions">
+        <button onClick={() => 
+          panelRef.current?.startNewConversation('Quick summary please')
+        }>
+          Quick Summary
+        </button>
+      </div>
+      
+      {/* Panel with initialPrompt for manual conversations */}
+      <AIAgentPanel
+        ref={panelRef}
+        initialPrompt={welcomePrompt}
+        hideInitialPrompt={false}
+        agents={['assistant']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+### Example 5: Dynamic Prompt Based on User Data
+
+```typescript
+function DynamicPromptExample() {
+  const panelRef = useRef<AIAgentPanelHandle>(null);
+  const { userData } = useUserData(); // Custom hook
+  
+  const getPersonalizedPrompt = () => {
+    const { name, lastActivity, goals } = userData;
+    return `Hi ${name}! Based on your ${lastActivity} activity and ${goals} goals, what would you like to know?`;
+  };
+  
+  return (
+    <div>
+      <button onClick={() => 
+        panelRef.current?.startNewConversation(getPersonalizedPrompt())
+      }>
+        Personalized Start
+      </button>
+      
+      <AIAgentPanel
+        ref={panelRef}
+        agents={['personal-agent']}
+        customerId="user-123"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ Do's
+
+1. **Use initialPrompt for global defaults**
+   ```typescript
+   <AIAgentPanel initialPrompt="Welcome! How can I help?" />
+   ```
+
+2. **Use startNewConversation for specific actions**
+   ```typescript
+   <button onClick={() => ref.current?.startNewConversation('Specific query')}>
+   ```
+
+3. **Combine both for flexible UX**
+   ```typescript
+   // Global welcome + programmatic quick actions
+   ```
+
+4. **Specify agents when relevant**
+   ```typescript
+   ref.current?.startNewConversation('Query', 'specific-agent');
+   ```
+
+5. **Keep prompts clear and actionable**
+   ```typescript
+   'Analyze my weekly progress' // Clear
+   vs
+   'Tell me stuff' // Vague
+   ```
+
+### ❌ Don'ts
+
+1. **Don't use startNewConversation for global defaults**
+   ```typescript
+   // ❌ Bad: Repeating for every button
+   onClick={() => ref.current?.startNewConversation('Same welcome')}
+   
+   // ✅ Good: Use initialPrompt instead
+   <AIAgentPanel initialPrompt="Same welcome" />
+   ```
+
+2. **Don't forget to check ref.current**
+   ```typescript
+   // ❌ Bad: Could crash if ref not ready
+   ref.current.startNewConversation('Query');
+   
+   // ✅ Good: Optional chaining
+   ref.current?.startNewConversation('Query');
+   ```
+
+3. **Don't create excessive conversations**
+   ```typescript
+   // ❌ Bad: Creates conversation on every render
+   useEffect(() => {
+     ref.current?.startNewConversation('Query');
+   }); // Missing dependency array
+   
+   // ✅ Good: Control when conversations start
+   useEffect(() => {
+     ref.current?.startNewConversation('Query');
+   }, []); // Empty array = once on mount
+   ```
+
+---
+
+## Migration Guide
+
+### Upgrading from Earlier Versions
+
+If you were using custom solutions to start conversations, here's how to migrate:
+
+#### Before (Custom Solution)
+
+```typescript
+// Old way: Managing conversation creation manually
+const [shouldSendPrompt, setShouldSendPrompt] = useState(false);
+const [promptToSend, setPromptToSend] = useState('');
+
+useEffect(() => {
+  if (shouldSendPrompt) {
+    // Custom logic to create conversation and send prompt
+    createConversationAndSend(promptToSend);
+    setShouldSendPrompt(false);
+  }
+}, [shouldSendPrompt]);
+
+<button onClick={() => {
+  setPromptToSend('My query');
+  setShouldSendPrompt(true);
+}}>
+```
+
+#### After (Using startNewConversation)
+
+```typescript
+// New way: Simple and clean
+const panelRef = useRef<AIAgentPanelHandle>(null);
+
+<button onClick={() => 
+  panelRef.current?.startNewConversation('My query')
+}>
+```
+
+---
+
+## Troubleshooting
+
+### Issue: startNewConversation not working
+
+**Solution:** Ensure you've:
+1. Created a ref: `const panelRef = useRef<AIAgentPanelHandle>(null)`
+2. Passed it to AIAgentPanel: `<AIAgentPanel ref={panelRef} />`
+3. Used optional chaining: `panelRef.current?.startNewConversation(...)`
+
+### Issue: initialPrompt not sending
+
+**Solution:** Check that:
+1. `hideInitialPrompt` is not set to `true` (default behavior)
+2. The conversation is actually new (not loading existing conversation)
+3. `initialPrompt` has a value (not empty string)
+
+### Issue: Prompt sent multiple times
+
+**Solution:** Ensure you're not:
+1. Calling `startNewConversation` in a render cycle
+2. Missing dependency arrays in useEffect
+3. Creating duplicate event handlers
+
+---
+
+## Version History
+
+- **v0.17.0** - Added `startNewConversation` imperative API
+- **v0.16.x** - Initial `initialPrompt` prop support
+
+---
+
+## Related Documentation
+
+- [Conversation History Settings](./CONVERSATION-HISTORY.md)
+- [AIAgentPanel API Reference](../local-dev-docs/AIAGENTPANEL.md)
+- [AIChatPanel Documentation](../local-dev-docs/AICHATPANEL.md)
+- [Quick Start Guide](../local-dev-docs/QUICK-START.md)