sarvam-conv-ai-sdk 0.0.1 → 0.0.2

package/README.md

@@ -1,207 +1,325 @@
-# Sarvam Conversational AI SDK - TypeScript
+# Sarvam Conv AI SDK
 
-TypeScript SDK for building real-time voice-to-voice conversational AI applications in the browser.
+TypeScript SDK for building real-time voice-to-voice and text-based conversational AI applications in browser and Node.js environments.
+
+## Features
+
+- Real-time voice-to-voice conversations in the browser
+- Text-based chat with streaming responses
+- Automatic microphone capture and speaker playback
+- Multi-language support (11 Indian languages + English)
+- WebSocket-based real-time communication
+- Browser and Node.js compatible
 
 ## Installation
 
 ```bash
-npm install @sarvam/conv-ai-sdk
+npm install sarvam-conv-ai-sdk
 ```
 
-For React applications:
+For Node.js, install `ws` peer dependency:
+
 ```bash
-npm install react react-dom
-npm install --save-dev @types/react @types/react-dom
+npm install sarvam-conv-ai-sdk ws
 ```
 
 ## Quick Start
 
-Here's a complete React component example for voice-to-voice interaction:
+### Voice-to-Voice Conversation (Browser)
 
-```tsx
-import React, { useEffect, useRef, useState } from 'react';
+```typescript
+import React, { useRef, useState } from 'react';
 import {
-  AsyncSamvaadAgent,
+  ConversationAgent,
   BrowserAudioInterface,
-  InteractionConfig,
   InteractionType,
-  ServerTextChunkMsg,
-  UserIdentifierType,
-} from '@sarvam/conv-ai-sdk';
-
-interface VoiceChatProps {
-  apiKey: string;
-  appId: string;
-  orgId: string;
-  workspaceId: string;
-  userId?: string;
-}
+  ServerTextMsgType,
+} from 'sarvam-conv-ai-sdk';
 
-export const VoiceChat: React.FC<VoiceChatProps> = ({
-  apiKey,
-  appId,
-  orgId,
-  workspaceId,
-  userId = 'react_user',
-}) => {
+function VoiceChat() {
   const [isConnected, setIsConnected] = useState(false);
-  const [isConnecting, setIsConnecting] = useState(false);
-  const [transcript, setTranscript] = useState<string>('');
-  const agentRef = useRef<AsyncSamvaadAgent | null>(null);
-
-  const handleText = async (msg: ServerTextChunkMsg) => {
-    setTranscript(prev => prev + msg.text);
-  };
+  const [transcript, setTranscript] = useState('');
+  const agentRef = useRef<ConversationAgent | null>(null);
 
   const startConversation = async () => {
-    if (isConnecting || isConnected) return;
-    
-    setIsConnecting(true);
-    
     try {
-      const config: InteractionConfig = {
-        user_identifier_type: UserIdentifierType.CUSTOM,
-        user_identifier: userId,
-        org_id: orgId,
-        workspace_id: workspaceId,
-        app_id: appId,
-        interaction_type: InteractionType.CALL,
-        sample_rate: 16000,
-      };
-
       const audioInterface = new BrowserAudioInterface();
       
-      const agent = new AsyncSamvaadAgent({
-        apiKey,
-        config,
-        textCallback: handleText,
+      const agent = new ConversationAgent({
+        apiKey: 'your_api_key',
+        platform: 'browser',
+        config: {
+          user_identifier_type: 'custom',
+          user_identifier: 'user123',
+          org_id: 'your_org_id',
+          workspace_id: 'your_workspace_id',
+          app_id: 'your_app_id',
+          interaction_type: InteractionType.CALL,
+          sample_rate: 16000,
+        },
         audioInterface,
+        textCallback: async (msg: ServerTextMsgType) => {
+          setTranscript(prev => prev + msg.text);
+        },
+        startCallback: async () => {
+          setIsConnected(true);
+        },
+        endCallback: async () => {
+          setIsConnected(false);
+        },
       });
 
       agentRef.current = agent;
-      
       await agent.start();
-      const connected = await agent.waitForConnect(5.0);
-      
-      if (connected) {
-        setIsConnected(true);
-        setIsConnecting(false);
-        
-        agent.waitForDisconnect().then(() => {
-          setIsConnected(false);
-        });
-      } else {
-        setIsConnecting(false);
-        alert('Failed to connect. Please check your credentials.');
-      }
+      await agent.waitForConnect(10);
     } catch (error) {
-      setIsConnecting(false);
-      console.error('Error starting conversation:', error);
-      alert(`Error: ${error instanceof Error ? error.message : String(error)}`);
+      console.error('Error:', error);
     }
   };
 
   const stopConversation = async () => {
     if (agentRef.current) {
-      try {
-        await agentRef.current.stop();
-        agentRef.current = null;
-        setIsConnected(false);
-        setTranscript('');
-      } catch (error) {
-        console.error('Error stopping conversation:', error);
-      }
+      await agentRef.current.stop();
+      agentRef.current = null;
     }
   };
 
-  useEffect(() => {
-    return () => {
-      if (agentRef.current) {
-        agentRef.current.stop().catch(console.error);
-      }
-    };
-  }, []);
-
   return (
-    <div style={{ padding: '20px', maxWidth: '600px', margin: '0 auto' }}>
+    <div>
       <h2>Voice Chat</h2>
-      
-      <div style={{ marginBottom: '20px' }}>
-        {!isConnected && !isConnecting && (
-          <button onClick={startConversation}>
-            Start Voice Chat
-          </button>
-        )}
-        
-        {isConnecting && <div>Connecting...</div>}
-        
-        {isConnected && (
-          <button onClick={stopConversation}>
-            Stop Voice Chat
-          </button>
-        )}
-      </div>
-      
-      {isConnected && (
-        <div>
-          <strong>Agent Response:</strong>
-          <div>{transcript || 'Listening...'}</div>
-        </div>
+      {!isConnected ? (
+        <button onClick={startConversation}>Start Voice Chat</button>
+      ) : (
+        <button onClick={stopConversation}>Stop Voice Chat</button>
       )}
+      <div>Transcript: {transcript}</div>
     </div>
   );
-};
+}
+
+export default VoiceChat;
 ```
 
-## Configuration
+### Text-Based Conversation (Node.js)
 
-### AsyncSamvaadAgent Parameters
+```javascript
+const { ConversationAgent, InteractionType } = require('sarvam-conv-ai-sdk');
+
+async function main() {
+  const agent = new ConversationAgent({
+    apiKey: 'your_api_key',
+    config: {
+      org_id: 'your_org_id',
+      workspace_id: 'your_workspace_id',
+      app_id: 'your_app_id',
+      user_identifier: 'user@example.com',
+      user_identifier_type: 'email',
+      interaction_type: InteractionType.TEXT,
+      sample_rate: 16000,
+    },
+    textCallback: async (msg) => {
+      console.log('Agent:', msg.text);
+    },
+    startCallback: async () => {
+      console.log('Conversation started!');
+    },
+  });
+
+  await agent.start();
+  const connected = await agent.waitForConnect(10);
+  
+  if (connected) {
+    await agent.sendText('Hello, how are you?');
+    await agent.waitForDisconnect();
+  }
+}
+
+main().catch(console.error);
+```
+
+## API Reference
+
+### ConversationAgent
+
+The main class for managing conversational AI sessions.
+
+#### Constructor Parameters
 
 | Parameter | Type | Required | Description |
 | --- | --- | --- | --- |
 | apiKey | string | Yes | API key for authentication |
 | config | InteractionConfig | Yes | Interaction configuration |
-| audioInterface | AsyncAudioInterface | No | Audio interface for mic/speaker (required for voice) |
-| textCallback | (msg: ServerTextChunkMsg) => Promise<void> | No | Receives streaming text chunks |
-| eventCallback | (event: ServerEventBase) => Promise<void> | No | Receives events |
-| audioCallback | (msg: ServerAudioChunkMsg) => Promise<void> | No | Receives audio chunks (if not using audioInterface) |
+| platform | 'browser' \| 'node' | No | Platform type (auto-detected) |
+| audioInterface | AsyncAudioInterface | No | Audio interface for voice interactions |
+| textCallback | (msg: ServerTextMsgType) => Promise\<void\> | No | Receives streaming text chunks |
+| audioCallback | (msg: ServerAudioChunkMsg) => Promise\<void\> | No | Receives audio chunks |
+| eventCallback | (event: ServerEventBase) => Promise\<void\> | No | Receives events |
+| startCallback | () => Promise\<void\> | No | Called when conversation starts |
+| endCallback | () => Promise\<void\> | No | Called when conversation ends |
+| baseUrl | string | No | Override base URL |
+| proxy | boolean | No | Enable proxy mode |
+
+#### Methods
+
+- `async start()` - Start the conversation session
+- `async stop()` - Stop the conversation and cleanup
+- `async waitForConnect(timeout?)` - Wait for connection (returns boolean)
+- `async waitForDisconnect()` - Wait until disconnected
+- `isConnected()` - Check connection status
+- `getInteractionId()` - Get current interaction ID
+- `async sendAudio(audioData)` - Send raw audio (voice mode only)
+- `async sendText(text)` - Send text message (text mode only)
+- `getAgentType()` - Get agent type ('voice' or 'text')
 
 ### InteractionConfig
 
-Required fields:
-- `user_identifier_type`: `CUSTOM`, `EMAIL`, `PHONE_NUMBER`, or `UNKNOWN`
-- `user_identifier`: User identifier value
-- `org_id`: Your organization ID
-- `workspace_id`: Your workspace ID
-- `app_id`: Application ID
-- `interaction_type`: `InteractionType.CALL`
-- `sample_rate`: `8000` or `16000`
-
-Optional:
-- `agent_variables`: Key-value pairs for agent context
-- `initial_language_name`: Starting language (e.g., "English", "Hindi")
-- `initial_state_name`: Starting state name
-- `initial_bot_message`: First message from agent
-
-### Methods
-
-- `await agent.start()` — Start and connect
-- `await agent.stop()` — Stop and cleanup
-- `await agent.waitForConnect(timeout?)` — Wait until connected
-- `await agent.waitForDisconnect()` — Wait until disconnected
-- `agent.isConnected()` — Check connection status
-- `agent.getInteractionId()` — Get current interaction ID
+#### Required Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| user_identifier_type | string | One of: 'custom', 'email', 'phone_number', 'unknown' |
+| user_identifier | string | User identifier value |
+| org_id | string | Your organization ID |
+| workspace_id | string | Your workspace ID |
+| app_id | string | The target application ID |
+| interaction_type | InteractionType | InteractionType.CALL or InteractionType.TEXT |
+| sample_rate | number | Audio sample rate: 8000 or 16000 |
+
+#### Optional Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| version | number | App version (uses latest if not provided) |
+| agent_variables | Record\<string, any\> | Key-value pairs for agent context |
+| initial_language_name | SarvamToolLanguageName | Starting language |
+| initial_state_name | string | Starting state name |
+| initial_bot_message | string | First message from agent |
+
+### BrowserAudioInterface
+
+Handles microphone capture and speaker playback in browser environments.
+
+```typescript
+import { BrowserAudioInterface } from 'sarvam-conv-ai-sdk';
+
+const audioInterface = new BrowserAudioInterface();
+```
+
+**Features:**
+- Automatic microphone access and audio capture
+- Real-time audio streaming at 16kHz
+- Automatic speaker playback
+- Handles user interruptions
+
+**Requirements:**
+- HTTPS connection (required for microphone access)
+- Modern browser with WebAudio API support
+- User permission for microphone access
+
+## Event Handling
+
+### Text Callback
+
+Receives streaming text chunks from the agent:
+
+```typescript
+textCallback: async (msg: ServerTextMsgType) => {
+  console.log('Agent says:', msg.text);
+}
+```
+
+### Event Callback
+
+Receives various events during conversation:
+
+```typescript
+eventCallback: async (event: ServerEventBase) => {
+  switch (event.type) {
+    case 'server.action.interaction_connected':
+      console.log('Connected');
+      break;
+    case 'server.event.user_interrupt':
+      console.log('User interrupted');
+      break;
+    case 'server.action.interaction_end':
+      console.log('Conversation ended');
+      break;
+    case 'server.event.user_speech_start':
+      console.log('User started speaking');
+      break;
+    case 'server.event.user_speech_end':
+      console.log('User stopped speaking');
+      break;
+  }
+}
+```
+
+## Supported Languages
+
+The SDK supports 11 Indian languages plus English:
+
+```typescript
+import { SarvamToolLanguageName } from 'sarvam-conv-ai-sdk';
+
+// Available: BENGALI, GUJARATI, KANNADA, MALAYALAM, TAMIL, 
+// TELUGU, PUNJABI, ODIA, MARATHI, HINDI, ENGLISH
+
+const config = {
+  initial_language_name: SarvamToolLanguageName.HINDI,
+};
+```
+
+## Best Practices
+
+**Resource Cleanup:** Always cleanup resources when component unmounts
+
+```typescript
+useEffect(() => {
+  return () => agentRef.current?.stop().catch(console.error);
+}, []);
+```
+
+**Connection Timeout:** Specify timeout when waiting for connection
+
+```typescript
+const connected = await agent.waitForConnect(10); // 10 seconds
+if (!connected) console.error('Connection timeout');
+```
+
+**Error Handling:** Wrap agent operations in try-catch blocks
+
+```typescript
+try {
+  await agent.start();
+  await agent.waitForConnect(10);
+} catch (error) {
+  console.error('Error:', error);
+  await agent.stop();
+}
+```
+
+**Secure API Keys:** Use environment variables or backend proxy
+
+```typescript
+// Use environment variables
+const apiKey = import.meta.env.VITE_SARVAM_API_KEY;
+
+// Or use backend proxy
+const agent = new ConversationAgent({ proxy: true, baseUrl: '/api/proxy/' });
+```
 
 ## Examples
 
-Check out the [`examples/web`](./examples/web) directory for a complete, production-ready React + TypeScript web application demonstrating:
-- Voice-to-voice AI conversation
-- Modern, responsive UI with dark/light mode
-- Real-time transcript display
-- Audio level visualization
-- Comprehensive error handling
+- **Web Example** - See `examples/web` for a complete React + TypeScript application
+- **Node.js Example** - See `examples/nodejs/simple-text-chat.js` for a command-line text chat
+
+## Troubleshooting
+
+**Microphone Not Working:** Ensure HTTPS connection, check browser permissions, verify microphone is not in use by another app
+
+**Connection Timeout:** Check network connectivity, verify API key is valid, ensure app_id exists and has a committed version
 
-See the [example README](./examples/web/README.md) for setup instructions.
+**Audio Quality Issues:** Verify sample rate matches configuration (8000 or 16000), ensure audio format is LINEAR16 (16-bit PCM mono)
 
 ## License
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sarvam-conv-ai-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "TypeScript SDK for Sarvam Conversational AI",
   "main": "index.js",
   "types": "index.d.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sarvam-conv-ai-sdk",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "TypeScript SDK for Sarvam Conversational AI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",