cosmic-ai-genius 0.3.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Genius Team
+
+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,689 @@
+# Genius SDK for React
+
+A powerful, customizable AI chatbot SDK for React applications with voice capabilities and modern UI design.
+
+## Features
+
+- ✨ **Modern UI** - Beautiful, responsive chatbot interface matching Figma designs
+- 🎤 **Voice Integration** - Voice call functionality with animated waveforms
+- 🎨 **Fully Customizable** - Themes, positioning, and behavior customization
+- 📱 **Mobile Responsive** - Optimized for all screen sizes
+- 🚀 **Easy Integration** - Simple provider pattern for seamless integration
+- ⚡ **TypeScript Support** - Full type safety and IntelliSense
+- 🎯 **Multiple Components** - Flexible component architecture
+- 🔄 **Streaming Support** - Real-time streaming responses with SSE
+- 🤖 **Backend Integration** - Connect to AI backends with RAG support
+- 📝 **Markdown Rendering** - Rich text formatting in messages
+- 📚 **Source Citations** - Display grounding sources for AI responses
+
+## Installation
+
+This package is published to a private Google Cloud Artifact Registry. Development team members need to set up authentication:
+
+#### Prerequisites
+- Google Cloud CLI installed: `gcloud --version`
+- Authenticated with your Juspay Google account: `gcloud auth login`
+- Access to the `genius-dev-393512` GCP project
+
+#### Quick Setup
+
+1. **Run the authentication script:**
+   ```bash
+   ./refresh-npm-auth.sh
+   ```
+
+2. **Install the package in the repository where you want to integrate the Genius SDK:**
+   ```bash
+   npm install @genius/sdk-js
+   ```
+
+#### Manual Setup (Alternative)
+
+If you prefer to set up authentication manually:
+
+1. **Get an access token:**
+   ```bash
+   gcloud auth print-access-token
+   ```
+
+2. **Update your `~/.npmrc` file:**
+   ```
+   @genius:registry=https://us-central1-npm.pkg.dev/genius-dev-393512/genius-npm-registry/
+   //us-central1-npm.pkg.dev/genius-dev-393512/genius-npm-registry/:_authToken="YOUR_ACCESS_TOKEN_HERE"
+   //us-central1-npm.pkg.dev/genius-dev-393512/genius-npm-registry/:always-auth=true
+   ```
+
+#### Token Refresh
+
+Access tokens expire after ~1 hour. When you get authentication errors:
+
+```bash
+# Run the refresh script again
+./refresh-npm-auth.sh
+
+# Or manually refresh
+gcloud auth print-access-token
+# Update your ~/.npmrc with the new token
+```
+
+#### Troubleshooting Registry Access
+
+- **Authentication errors**: Run `./refresh-npm-auth.sh` to refresh your token
+- **Permission denied**: Ensure you're authenticated with the correct Google account
+- **Package not found**: Verify the package name and registry URL are correct
+
+## Quick Start
+
+### 1. Basic Setup
+
+Wrap your app with the `GeniusChatbotProvider`:
+
+```tsx
+import { GeniusChatbotProvider, GeniusToggle } from '@genius/sdk-js';
+
+function App() {
+  return (
+    <GeniusChatbotProvider 
+      config={{
+        welcomeMessage: "Hi! How can I help you today?",
+        suggestions: ['How to get started?', 'Pricing', 'Support'],
+        position: 'bottom-right'
+      }}
+    >
+      <YourAppContent />
+      <GeniusToggle />
+    </GeniusChatbotProvider>
+  );
+}
+```
+
+### 2. Programmatic Control
+
+Use the `useGeniusChatbot` hook for programmatic control:
+
+```tsx
+import { useGeniusChatbot } from '@genius/sdk-js';
+
+function MyComponent() {
+  const { openChatbot, closeChatbot, toggleChatbot, isOpen } = useGeniusChatbot();
+
+  return (
+    <div>
+      <button onClick={openChatbot}>Open Chat</button>
+      <button onClick={toggleChatbot}>Toggle Chat</button>
+      <p>Chat is {isOpen ? 'open' : 'closed'}</p>
+    </div>
+  );
+}
+```
+
+## Components
+
+### GeniusChatbotProvider
+
+The main provider component that manages chatbot state and configuration.
+
+```tsx
+<GeniusChatbotProvider
+  config={{
+    // API Configuration
+    apiKey: "your-api-key",
+    apiEndpoint: "https://your-api.com/chat",
+    
+    // UI Customization
+    welcomeMessage: "Welcome to Genius AI!",
+    placeholder: "Type your message...",
+    suggestions: ['FAQ', 'Pricing', 'Contact'],
+    
+    // Positioning & Theming
+    position: 'bottom-right',
+    width: 440,
+    height: 680,
+    theme: {
+      primaryColor: '#1b85ff',
+      backgroundColor: '#ffffff'
+    },
+    
+    // Event Handlers
+    onMessage: (message) => console.log('New message:', message),
+    onClose: () => console.log('Chatbot closed'),
+    onExpand: () => console.log('Chatbot expanded')
+  }}
+  defaultOpen={false}
+>
+  {children}
+</GeniusChatbotProvider>
+```
+
+### GeniusChatbot
+
+The main chatbot interface component (automatically rendered by provider):
+
+```tsx
+// Rendered automatically when chatbot is open
+// Features:
+// - Expandable interface (50% screen width on desktop)
+// - Voice call integration
+// - Message history
+// - Suggested replies
+// - Mobile responsive design
+```
+
+### GeniusToggle
+
+A floating toggle button to open the chatbot:
+
+```tsx
+<GeniusToggle
+  position="bottom-right"  // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
+  offsetX={20}            // Horizontal offset from edge
+  offsetY={20}            // Vertical offset from edge
+/>
+```
+
+### VoiceCall
+
+Voice call interface component (automatically shown when voice is activated):
+
+```tsx
+// Activated when waveform icon is clicked
+// Features:
+// - Animated waveform visualization
+// - Microphone and end call controls
+// - Compact floating design
+// - Smooth transitions
+```
+
+## Configuration Options
+
+### GeniusChatbotConfig
+
+```typescript
+interface GeniusChatbotConfig {
+  // API Settings
+  apiKey?: string;
+  baseUrl?: string;  // Base URL for backend (e.g., 'https://api.example.com')
+  endpoints?: {      // Custom endpoints (optional)
+    chat?: string;   // Non-streaming chat endpoint
+    stream?: string; // Streaming chat endpoint
+  };
+  useStreaming?: boolean; // Enable real-time streaming responses
+  
+  // Content
+  welcomeMessage?: string;
+  placeholder?: string;
+  suggestions?: string[];
+  
+  // Layout
+  position?: 'bottom-right' | 'bottom-left' | 'center';
+  width?: number;
+  height?: number;
+  
+  // Theming
+  theme?: {
+    primaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderRadius?: number;
+    fontFamily?: string;
+    [key: string]: any;
+  };
+  
+  // Event Handlers
+  onMessage?: (message: Message) => void;
+  onClose?: () => void;
+  onExpand?: () => void;
+}
+```
+
+### Message Interface
+
+```typescript
+interface Message {
+  id: string;
+  content: string;
+  role: 'user' | 'assistant';
+  timestamp: Date;
+  sources?: GroundingChunk[]; // Optional source citations
+}
+
+interface GroundingChunk {
+  text: string;
+  title: string;
+  uri: string;
+}
+```
+
+## Backend Integration
+
+The SDK supports integration with AI backends, including the provided Python FastAPI server with Google Gemini and RAG support.
+
+### Quick Backend Setup
+
+1. **Start the backend server** (see `/backend/README.md` for details):
+   ```bash
+   cd backend
+   ./run.sh
+   ```
+
+2. **Configure the SDK with backend URL**:
+   ```tsx
+   <GeniusChatbotProvider
+     config={{
+       baseUrl: 'http://localhost:8001',
+       useStreaming: true,  // Enable real-time responses
+     }}
+   >
+   ```
+
+### Backend Configuration Options
+
+```tsx
+// Option 1: Simple base URL (recommended)
+config={{
+  baseUrl: 'https://api.example.com',
+  // SDK will append /chat and /chat/stream
+}}
+
+// Option 2: Custom endpoints
+config={{
+  endpoints: {
+    chat: 'https://api.example.com/v1/chat',
+    stream: 'https://streaming.example.com/sse'
+  }
+}}
+
+// Option 3: Mix and match
+config={{
+  baseUrl: 'https://api.example.com',
+  endpoints: {
+    stream: 'https://fast-stream.example.com/chat'
+  }
+}}
+```
+
+## Advanced Usage
+
+### Custom API Integration
+
+```tsx
+<GeniusChatbotProvider
+  config={{
+    baseUrl: "https://your-api.com",
+    apiKey: "your-secret-key",
+    useStreaming: true,
+    onMessage: async (message) => {
+      // Custom message handling
+      console.log('User sent:', message.content);
+      
+      // Send to your analytics
+      analytics.track('chat_message_sent', {
+        content: message.content,
+        timestamp: message.timestamp
+      });
+    }
+  }}
+>
+```
+
+### Custom Theming
+
+```tsx
+<GeniusChatbotProvider
+  config={{
+    theme: {
+      // Override CSS custom properties
+      '--genius-primary-blue': '#your-brand-color',
+      '--genius-background': '#f8f9fa',
+      '--genius-text-primary': '#1a1a1a',
+      '--genius-border-radius': '16px',
+      fontFamily: 'Inter, sans-serif'
+    }
+  }}
+>
+```
+
+### Multiple Chatbot Instances
+
+```tsx
+// You can have multiple chatbot providers for different contexts
+function App() {
+  return (
+    <div>
+      {/* Support chatbot */}
+      <GeniusChatbotProvider config={{ 
+        welcomeMessage: "Need help? I'm here to assist!",
+        position: 'bottom-right'
+      }}>
+        <SupportSection />
+        <GeniusToggle />
+      </GeniusChatbotProvider>
+      
+      {/* Sales chatbot */}
+      <GeniusChatbotProvider config={{ 
+        welcomeMessage: "Interested in our products?",
+        position: 'bottom-left'
+      }}>
+        <SalesSection />
+        <GeniusToggle position="bottom-left" />
+      </GeniusChatbotProvider>
+    </div>
+  );
+}
+```
+
+### Voice Call Integration
+
+The voice call feature is automatically available when using the chatbot:
+
+1. **Activation**: Click the waveform icon when no text is entered
+2. **Interface**: Shows compact voice call UI with animated waveform
+3. **Controls**: Microphone status and end call button
+4. **Exit**: Click end call button to return to chat interface
+
+```tsx
+// Voice call is automatically integrated
+// No additional setup required
+// Activated by clicking waveform icon in chat input
+```
+
+## Responsive Behavior
+
+### Desktop
+- Default size: 440px × 680px
+- Expandable to 50% screen width
+- Floating position with shadows
+
+### Mobile
+- Full screen overlay
+- Auto-collapse when expanded
+- Hide expand/collapse buttons
+- Touch-optimized interface
+
+### Tablet
+- Responsive sizing between mobile and desktop
+- Optimized button sizes and spacing
+
+## Events & Callbacks
+
+### Message Events
+
+```tsx
+const handleMessage = (message: Message) => {
+  console.log('New message:', message);
+  
+  // Send to analytics
+  if (message.role === 'user') {
+    analytics.track('user_message', { content: message.content });
+  }
+};
+
+<GeniusChatbotProvider config={{ onMessage: handleMessage }} />
+```
+
+### Lifecycle Events
+
+```tsx
+const config = {
+  onClose: () => {
+    console.log('Chatbot closed');
+    // Save conversation state
+  },
+  
+  onExpand: () => {
+    console.log('Chatbot expanded');
+    // Track engagement
+  }
+};
+```
+
+## Styling & Customization
+
+### CSS Custom Properties
+
+The SDK uses CSS custom properties for easy theming:
+
+```css
+:root {
+  --genius-primary-blue: #1B85FF;
+  --genius-grey-600: #8A8A8E;
+  --genius-grey-500: #9C9C9F;
+  --genius-grey-200: #E0E0E0;
+  --genius-grey-100: #EDEDED;
+  --genius-text-primary: #1c1c1c;
+  --genius-text-secondary: #5f5f5f;
+  --genius-white: #ffffff;
+  --genius-background: #fcfcfc;
+}
+```
+
+### Override Styles
+
+```css
+/* Custom styles for your application */
+.genius-chatbot-container {
+  border-radius: 20px !important;
+  box-shadow: 0 20px 40px rgba(0,0,0,0.1) !important;
+}
+
+.genius-chatbot-send-button {
+  background: linear-gradient(45deg, #ff6b6b, #4ecdc4) !important;
+}
+```
+
+## TypeScript Support
+
+The SDK is fully typed with TypeScript. Import types as needed:
+
+```typescript
+import type { 
+  GeniusChatbotConfig, 
+  Message,
+  GeniusChatbotContextType 
+} from '@genius/sdk-js';
+
+const config: GeniusChatbotConfig = {
+  welcomeMessage: "Hello!",
+  suggestions: ["Help", "Info"]
+};
+
+const handleMessage = (message: Message) => {
+  // Fully typed message object
+  console.log(message.content, message.role, message.timestamp);
+};
+```
+
+## Browser Support
+
+- ✅ Chrome 90+
+- ✅ Firefox 88+
+- ✅ Safari 14+
+- ✅ Edge 90+
+- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Performance
+
+- **Bundle size**: ~45KB gzipped
+- **Runtime**: Lightweight React components
+- **Memory**: Efficient state management
+- **Animations**: Hardware-accelerated CSS animations
+
+## Development
+
+### Publishing to Private Registry
+
+For development team members with publishing access:
+
+1. **Ensure authentication is set up** (see Installation section above)
+
+2. **Update package version:**
+   ```bash
+   npm version patch  # or minor/major
+   ```
+
+3. **Publish to private registry:**
+   ```bash
+   npm publish
+   ```
+
+4. **Verify publication:**
+   ```bash
+   npm view @genius/sdk-js --registry=https://us-central1-npm.pkg.dev/genius-dev-393512/genius-npm-registry/
+   ```
+
+### Registry Authentication for CI/CD
+
+For automated publishing in CI/CD pipelines, use service account authentication:
+
+```bash
+# In your CI/CD environment
+gcloud auth activate-service-account --key-file=service-account-key.json
+gcloud auth configure-docker us-central1-docker.pkg.dev
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Chatbot not appearing**
+   ```tsx
+   // Ensure you're using the provider
+   <GeniusChatbotProvider>
+     <YourApp />
+   </GeniusChatbotProvider>
+   ```
+
+2. **Styling conflicts**
+   ```css
+   /* Use more specific selectors */
+   .your-app .genius-chatbot-container {
+     /* Your overrides */
+   }
+   ```
+
+3. **TypeScript errors**
+   ```tsx
+   // Import types explicitly
+   import type { GeniusChatbotConfig } from '@genius/sdk-js';
+   ```
+
+4. **Registry authentication errors**
+   ```bash
+   # Refresh your authentication
+   ./refresh-npm-auth.sh
+   
+   # Or check your gcloud authentication
+   gcloud auth list
+   gcloud auth login  # if needed
+   ```
+
+### Debug Mode
+
+Enable debug logging:
+
+```tsx
+<GeniusChatbotProvider 
+  config={{ 
+    debug: true,  // Enable console logs
+    onMessage: (msg) => console.log('Debug:', msg)
+  }}
+/>
+```
+
+## ReScript Integration
+
+The SDK can be used with ReScript by creating bindings:
+
+### 1. Create SDK bindings (`GeniusSDK.res`):
+
+```rescript
+module GeniusChatbotProvider = {
+  @module("@genius/sdk-js") @react.component
+  external make: (
+    ~config: GeniusConfig.t,
+    ~defaultOpen: bool=?,
+    ~children: React.element
+  ) => React.element = "GeniusChatbotProvider"
+}
+
+module GeniusToggle = {
+  @module("@genius/sdk-js") @react.component
+  external make: (
+    ~position: [#"bottom-right" | #"bottom-left" | #"top-right" | #"top-left"]=?,
+    ~offsetX: int=?,
+    ~offsetY: int=?
+  ) => React.element = "GeniusToggle"
+}
+
+@module("@genius/sdk-js")
+external useGeniusChatbot: unit => {
+  "openChatbot": unit => unit,
+  "closeChatbot": unit => unit,
+  "toggleChatbot": unit => unit,
+  "isOpen": bool
+} = "useGeniusChatbot"
+```
+
+### 2. Define configuration types (`GeniusConfig.res`):
+
+```rescript
+type theme = {
+  primaryColor?: string,
+  backgroundColor?: string,
+  textColor?: string,
+}
+
+type endpoints = {
+  chat?: string,
+  stream?: string,
+}
+
+type message = {
+  id: string,
+  content: string,
+  role: [#user | #assistant],
+  timestamp: Js.Date.t,
+}
+
+type t = {
+  apiKey?: string,
+  baseUrl?: string,
+  endpoints?: endpoints,
+  welcomeMessage?: string,
+  placeholder?: string,
+  suggestions?: array<string>,
+  position?: [#"bottom-right" | #"bottom-left" | #center],
+  useStreaming?: bool,
+  onMessage?: message => unit,
+  onClose?: unit => unit,
+  onExpand?: unit => unit,
+}
+```
+
+### 3. Use in your app:
+
+```rescript
+@react.component
+let make = () => {
+  let config = {
+    GeniusConfig.welcomeMessage: Some("How can I help you?"),
+    suggestions: Some(["Question 1", "Question 2"]),
+    baseUrl: Some("http://localhost:8001"),
+    useStreaming: Some(true),
+    // ... other fields
+  }
+
+  <GeniusSDK.GeniusChatbotProvider config defaultOpen=false>
+    <div className="app">
+      <YourAppContent />
+      <GeniusSDK.GeniusToggle />
+    </div>
+  </GeniusSDK.GeniusChatbotProvider>
+}
+```
+
+## Examples
+
+Check out the `/src/App.tsx` file in this repository for a complete working example with all features demonstrated.
+
+Made with ❤️ by the Genius team