valenceai 0.5.1 → 1.0.0

package/README.md

@@ -1,250 +1,367 @@
 # Valence SDK for Emotion Detection
 
-**valenceai** is a Node.js SDK for interacting with the [Valence AI](https://getvalenceai.com) Pulse API for emotion detection. It provides a convenient interface to upload audio files -— short or long —- and retrieve detected emotional states.
+**valenceai** is a Node.js SDK for interacting with the [Valence AI](https://getvalenceai.com) Pulse API for emotion detection. It provides a convenient interface to upload audio files, stream real-time audio, and retrieve detected emotional states.
 
 ## Features
 
-- **Discrete audio processing** - Single API call for short audio files
-- **Asynch audio processing** - Multipart streaming for long audio files  
-- **Environment configuration** - Built-in support for `.env` configuration
+- **Discrete audio processing** - Real-time analysis for short audio clips (4-10s)
+- **Async audio processing** - Multipart streaming for long files with timeline data
+- **Streaming API** - Real-time WebSocket streaming for live audio
+- **Rate limiting** - Monitor API usage and limits
+- **Model selection** - Choose between 4emotions and 7emotions models
+- **Timeline analysis** - Get emotion changes over time with timestamps
+- **Environment configuration** - Built-in support for .env files
 - **Enhanced logging** - Configurable log levels with timestamps
 - **Robust error handling** - Comprehensive validation and error recovery
 - **TypeScript ready** - Full JSDoc documentation for all functions
-- **100% tested** - Comprehensive test suite with 95%+ coverage
+- **100% tested** - Comprehensive test suite with high coverage
 - **Security focused** - Input validation and secure error handling
 
 The emotional classification model used in our APIs is optimized for North American English conversational data.
 
-The API includes a baseline model of 4 basic emotions. The emotions included by default are angry, happy, neutral, and sad. Our other model offerings include different subsets of the following emotions: happy, sad, angry, neutral, surprised, disgusted, nervous, irritated, excited, sleepy. 
+## Emotion Models
 
-  _Coming soon_ – The API will include a model choice parameter, allowing users to choose between models of 4, 5, and 7 emotions.
+The SDK supports two emotion detection models:
+
+- **4emotions** (default): angry, happy, neutral, sad
+- **7emotions**: happy, sad, angry, neutral, surprised, disgusted, calm
 
 The number of emotions, emotional buckets, and language support can be customized. If you are interested in a custom model, please [contact us](https://www.getvalenceai.com/contact).
 
-## API Functionality
+## API Overview
 
-While our APIs include the same model offerings in the backend, they are best suited for different purposes.
+| API | Best For | Input | Output | Response Time |
+|-----|----------|-------|--------|---------------|
+| **Discrete** | Real-time analysis | Short audio (4-10s) | Single emotion prediction | 100-500ms |
+| **Async** | Pre-recorded files | Long audio (up to 1GB) | Timeline with emotion changes | Depends on file size |
+| **Streaming** | Live audio streams | Audio chunks via WebSocket | Real-time emotion updates | Near real-time |
 
-|               | DiscreteAPI                                                                                                                                                                     | AsynchAPI                                                                                                                          |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| Inputs        | A short audio file, 4-10s in length.                                                                                                                                            | A long audio file, at least 5s in length. Inputs can be up to 1 GB large.                                                         |
-| Outputs       | A JSON that includes the primary emotion detected in the file, along with its confidence. The confidence scores of all other emotions in the model are also returned. | A time-stamped JSON that includes the classified emotion and its confidence at a rate of 1 classification per 5 seconds of audio. |
-| Response Time | 100-500 ms                                                                                                                                                                      | Dependent upon file size                                                                                                          |
+## Async API Processing Workflow
 
-The **DiscreteAPI** is built for real-time analysis of emotions in audio data. Small snippets of audio are sent to the API to receive feedback in real-time of what emotions are detected based on tone of voice. This API operates on an approximate per-sentence basis, and audio must be cut to the appropriate size.
+The Async API uses a multi-step process to handle long audio files. Understanding this workflow is crucial for proper implementation:
 
-The **AsynchAPI** is built for emotion analysis of pre-recorded audio files. Files of any length, up to 1 GB in size, can be sent to the API to receive a summary of emotions throughout the file. Similar to the DiscreteAPI, this API operates on an approximate per-sentence basis, but the AsyncAPI provides timestamps to show the change in emotions over time.
+### 1. Upload Phase (Client-Side)
 
-  _Coming soon_ –  StreamingAPI via WebSockets for real-time analysis of an audio stream.
+When you call `client.asynch.upload(filePath)`:
 
-## Installation
+- SDK splits your file into parts (5MB chunks by default)
+- Uploads parts to S3 using presigned URLs
+- **Returns a `requestId`** - This is a tracking identifier, NOT a completion signal
+- At this point: File is uploaded to S3, but **NOT processed yet**
 
-```bash
-npm install valenceai
-```
+### 2. Background Processing (Server-Side)
 
-## Configuration
+After upload completes, the server automatically:
 
-Create a `.env` file in your project root:
+- Background processor checks for new uploads every 10 seconds
+- Downloads audio from S3 when detected
+- Splits audio into 5-second segments
+- Extracts audio features (MFCC) from each segment
+- Invokes machine learning model for emotion detection
+- Stores results in database
+- Updates status to `completed`
 
-```env
-VALENCE_API_KEY=your_api_key                    # Required: Your Valence API key
-VALENCE_DISCRETE_URL=https://discrete-api-url   # Optional: Discrete audio endpoint
-VALENCE_ASYNCH_URL=https://asynch-api-url        # Optional: Asynch audio endpoint  
-VALENCE_LOG_LEVEL=info                          # Optional: debug, info, warn, error
-```
+**Processing Time**: Typically 1-2 minutes for a 60-minute audio file. The exact time depends on file length and current server load.
 
-### Configuration Validation
+### 3. Results Retrieval (Client-Side)
 
-```js
-import { validateConfig } from 'valenceai';
+When you call `client.asynch.emotions(requestId)`:
 
-try {
-  validateConfig();
-  console.log('Configuration is valid!');
-} catch (error) {
-  console.error('Configuration error:', error.message);
-}
-```
+- Polls the status endpoint at regular intervals
+- Waits for status progression:
+  - `initiated` → Upload started
+  - `upload_completed` → File uploaded to S3 (processing not started)
+  - `processing` → Background processing in progress
+  - `completed` → Results ready
+- Returns emotion timeline when status is `completed`
 
-## Usage
+### Status Values
 
-### Discrete Audio (Short Files)
+| Status | Meaning | What's Happening |
+|--------|---------|------------------|
+| `initiated` | Upload started | SDK is uploading file parts to S3 |
+| `upload_completed` | Upload finished | File is in S3, waiting for background processor |
+| `processing` | Processing active | Server is analyzing audio with ML model |
+| `completed` | Results ready | Emotion timeline is available |
 
-```js
-import { ValenceClient } from 'valenceai';
+### Important Notes
 
-try {
-  const client = new ValenceClient();
-  const result = await client.discrete.emotions('YOUR_FILE.wav');
-  console.log('Emotion detected:', result);
-} catch (error) {
-  console.error('Error:', error.message);
-}
+- **The `requestId` is NOT a completion indicator** - It's just a tracking ID
+- **`upload()` completing does NOT mean results are ready** - It only means the file is in S3
+- **Background processing takes time** - Plan for 1-2 minutes per hour of audio
+- **You can check status anytime** - The `requestId` remains valid for retrieving results
+
+## Installation
+
+```bash
+npm install valenceai
 ```
 
-### Asynch Audio (Long Files)
+## Quick Start
 
-```js
+```javascript
 import { ValenceClient } from 'valenceai';
 
-try {
-  const client = new ValenceClient();
-  
-  // Upload the audio file
-  const requestId = await client.asynch.upload('YOUR_FILE.wav');
-  console.log('Upload complete. Request ID:', requestId);
-  
-  // Get emotions from uploaded audio
-  const emotions = await client.asynch.emotions(requestId);
-  console.log('Emotions detected:', emotions);
-} catch (error) {
-  console.error('Error:', error.message);
-}
+// Initialize client (uses VALENCE_API_KEY environment variable)
+const client = new ValenceClient({ apiKey: 'your_api_key' });
+
+// Discrete API - Quick emotion detection
+const result = await client.discrete.emotions('short_audio.wav', '4emotions');
+console.log(`Emotion: ${result.dominant_emotion}`);
+
+// Async API - Long audio with timeline
+// Step 1: Upload file to S3 (returns tracking ID, NOT results)
+const requestId = await client.asynch.upload('long_audio.wav');
+// Step 2: Wait for server processing and get results (polls until complete)
+const emotions = await client.asynch.emotions(requestId, 30, 10000);
+// Step 3: Access timeline and dominant emotion from results
+const timeline = await client.asynch.getTimeline(requestId);
+const dominant = await client.asynch.getDominantEmotion(requestId);
+
+// Streaming API - Real-time audio
+const stream = client.streaming.connect('4emotions');
+stream.on('prediction', (data) => console.log(data.main_emotion));
+stream.connect();
+stream.sendAudio(audioBuffer);
+stream.disconnect();
+
+// Rate Limit API - Monitor usage
+const status = await client.rateLimit.getStatus();
+const health = await client.rateLimit.getHealth();
 ```
 
-### Advanced Usage
+## Configuration
 
-```js
-import { ValenceClient } from 'valenceai';
+### Environment Variables
 
-// Custom client configuration
-const client = new ValenceClient(
-  2 * 1024 * 1024,  // 2MB parts
-  5                 // 5 retry attempts
-);
+Create a `.env` file in your project root:
+
+```env
+VALENCE_API_KEY=your_api_key                       # Required
+VALENCE_API_BASE_URL=https://api.getvalenceai.com  # Optional
+VALENCE_WEBSOCKET_URL=wss://api.getvalenceai.com   # Optional
+VALENCE_LOG_LEVEL=info                             # Optional: debug, info, warn, error
+```
 
-// Upload with custom configuration
-const requestId = await client.asynch.upload('huge_file.wav');
+### Client Configuration
 
-// Custom polling with more attempts and shorter intervals
-const emotions = await client.asynch.emotions(
-  requestId,
-  50,    // 50 polling attempts
-  3      // 3 second intervals
-);
+```javascript
+const client = new ValenceClient({
+  apiKey: 'your_api_key',           // API key (required)
+  baseUrl: 'https://custom.api',    // Custom API endpoint (optional)
+  websocketUrl: 'wss://custom.api', // Custom WebSocket endpoint (optional)
+  partSize: 5 * 1024 * 1024,        // Upload chunk size (default: 5MB)
+  maxRetries: 3                     // Max retry attempts (default: 3)
+});
 ```
 
 ## API Reference
 
-### `new ValenceClient(partSize?, maxRetries?)`
+### Discrete API
 
-Creates a new Valence client with nested discrete and asynch clients.
+For short audio files requiring immediate emotion detection.
 
-**Parameters:**
-- `partSize` (number, optional): Size of each part in bytes for asynch uploads (default: 5MB)
-- `maxRetries` (number, optional): Maximum retry attempts for asynch uploads (default: 3)
+```javascript
+// File upload
+const result = await client.discrete.emotions(
+  'audio.wav',
+  '4emotions'  // or '7emotions'
+);
 
-**Returns:** `ValenceClient` instance with `discrete` and `asynch` properties
+// In-memory audio array
+const result = await client.discrete.emotions(
+  [0.1, 0.2, 0.3, ...],
+  '4emotions'
+);
+```
 
-### `client.discrete.emotions(filePath)`
+**Response:**
+```javascript
+{
+  emotions: {
+    happy: 0.78,
+    sad: 0.12,
+    angry: 0.05,
+    neutral: 0.05
+  },
+  dominant_emotion: 'happy'
+}
+```
 
-Predicts emotions for discrete (short) audio files using a single API call.
+### Async API
 
-**Parameters:**
-- `filePath` (string): Path to the audio file
+For long audio files with timeline analysis.
 
-**Returns:** `Promise<Object>` - Emotion prediction results
+**Workflow**: The Async API uses a 3-step process:
 
-**Throws:** Error if file doesn't exist, API key missing, or request fails
+1. **Upload** (`upload()`) - Multipart upload to S3, returns `requestId` (tracking ID)
+2. **Background Processing** (automatic) - Server processes audio in 5-second chunks
+3. **Results Retrieval** (`emotions()`) - Polls status endpoint until processing completes
 
-### `client.asynch.upload(filePath)`
+**Processing Time**: Typically 1-2 minutes per hour of audio.
 
-Uploads asynch (long) audio files using multipart upload for processing.
+**Status Progression**: `initiated` → `upload_completed` → `processing` → `completed`
 
-**Parameters:**
-- `filePath` (string): Path to the audio file
+#### Upload Audio
 
-**Returns:** `Promise<string>` - Request ID for tracking the upload
+```javascript
+// Upload file to S3 (multipart upload)
+const requestId = await client.asynch.upload('long_audio.wav');
+// Returns: requestId (tracking ID, NOT completion signal)
+// File is uploaded to S3 but NOT processed yet
+```
 
-**Throws:** Error if file doesn't exist, API key missing, or upload fails
+#### Get Emotion Results
 
-### `client.asynch.emotions(requestId, maxAttempts?, intervalSeconds?)`
+```javascript
+// Poll for results until processing completes
+const result = await client.asynch.emotions(
+  requestId,
+  20,    // maxTries (default: 20, range: 1-100)
+  5000   // intervalMs (default: 5000, range: 1000-60000)
+);
+// This method waits for server processing to complete
+// Returns when status is 'completed'
+```
 
-Retrieves emotion prediction results for asynch audio processing.
+**Response:**
+```javascript
+{
+  emotions: [
+    {
+      timestamp: 0.5,
+      start_time: 0.0,
+      end_time: 1.0,
+      emotion: 'happy',
+      confidence: 0.9,
+      all_predictions: { happy: 0.9, sad: 0.1, ... }
+    },
+    {
+      timestamp: 1.5,
+      start_time: 1.0,
+      end_time: 2.0,
+      emotion: 'neutral',
+      confidence: 0.85,
+      all_predictions: { neutral: 0.85, happy: 0.15, ... }
+    }
+  ],
+  status: 'completed'
+}
+```
+
+#### Timeline Analysis
 
-**Parameters:**
-- `requestId` (string): Request ID from `client.asynch.upload`
-- `maxAttempts` (number, optional): Maximum polling attempts (default: 20, range: 1-100)
-- `intervalSeconds` (number, optional): Polling interval in seconds (default: 5, range: 1-60)
+```javascript
+// Get full timeline
+const timeline = await client.asynch.getTimeline(requestId);
 
-**Returns:** `Promise<Object>` - Emotion detection results
+// Get emotion at specific time
+const emotion = await client.asynch.getEmotionAtTime(requestId, 5.2);
 
-**Throws:** Error if requestId is invalid or detection times out
+// Get dominant emotion across entire audio
+const dominant = await client.asynch.getDominantEmotion(requestId);
+```
 
-### `validateConfig()`
+### Streaming API
 
-Validates the current SDK configuration.
+For real-time emotion detection on live audio streams.
 
-**Throws:** Error if required configuration is missing or invalid
+```javascript
+// Create streaming connection
+const stream = client.streaming.connect('4emotions');
 
-## Inputs and Outputs
+// Register event handlers
+stream.on('prediction', (data) => {
+  console.log(`Emotion: ${data.main_emotion}`);
+});
 
-### Inputs
-The APIs expect mono audio in the .wav format. An ideal audio file is recorded at 44100 Hz (44.1 kHz), though sampling rates as low as 8 kHz can still be used with high accuracy. For custom use cases, microphone specifications can be customized based on audio environment, including optimizations for mono/stereo audio, single microphone applications, noisy environments, etc. 
+stream.on('error', (error) => {
+  console.error(`Error: ${error.message}`);
+});
 
-For the **DiscreteAPI**, input data is an audio file in the .wav format. 
+stream.on('connected', (info) => {
+  console.log(`Connected: ${info.session_id}`);
+});
 
-For the **AsynchAPI**, input data is an audio file in the .wav format.
+// Connect to WebSocket
+await stream.connect();
 
-### Outputs
+// Send audio chunks (Buffer or ArrayBuffer)
+stream.sendAudio(audioBuffer);
 
-Outputs are returned as JSONs in the following formats: 
+// Check connection status
+if (stream.connected) {
+  console.log('Streaming active');
+}
 
-**DiscreteAPI:**
+// Disconnect
+stream.disconnect();
+```
 
-```json
+**Prediction Event:**
+```javascript
 {
-  "main_emotion": "happy",
-  "confidence": 0.777777777,
-  "all_predictions": {
-    "angry": 0.123456789,
-    "happy": 0.777777777,
-    "neutral": 0.23456789,
-    "sad": 0.098765432
-  }
+  main_emotion: 'happy',
+  confidence: 0.87,
+  all_predictions: {
+    happy: 0.87,
+    sad: 0.05,
+    angry: 0.03,
+    neutral: 0.05
+  },
+  timestamp: 1234567890
 }
 ```
 
-The emotion returned in `main_emotion` is the highest confidence emotion returned from the model. Within `all_predictions`, each emotion is followed by its level of confidence. Some may use the top two highest confidence emotions to generate more nuanced states. We recommend dropping a `main_emotion` with confidence under 0.38, but that is at the user's discretion. 
+### Rate Limit API
+
+Monitor your API usage and limits.
+
+```javascript
+// Get rate limit status
+const status = await client.rateLimit.getStatus();
+console.log(status);
+// {
+//   limits: {
+//     second: { limit: 10, remaining: 8, reset: 1234567890 },
+//     minute: { limit: 100, remaining: 95, reset: 1234567890 },
+//     hour: { limit: 1000, remaining: 950, reset: 1234567890 },
+//     day: { limit: 10000, remaining: 9500, reset: 1234567890 }
+//   },
+//   current_usage: {
+//     second: 2,
+//     minute: 5,
+//     hour: 50,
+//     day: 500
+//   }
+// }
+
+// Check API health
+const health = await client.rateLimit.getHealth();
+console.log(health);
+// { status: 'healthy', timestamp: 1234567890 }
+```
 
-**AsynchAPI:**
+## Audio Input Requirements
 
-```json
-{
-  "request_id": "27a33189-bdd7-47ca-9817-abacfb7bdaf4",
-  "status": "completed",
-  "emotions": [
-    {
-      "t": "00:00",
-      "emotion": "neutral",
-      "confidence": 0.82791723
-    },
-    {
-      "t": "00:05",
-      "emotion": "neutral",
-      "confidence": 0.719817432
-    },
-    {
-      "t": "00:10",
-      "emotion": "happy",
-      "confidence": 0.917309381
-    },
-    {
-      "t": "00:15",
-      "emotion": "neutral",
-      "confidence": 0.414097846
-    }
-	"..."
-  ]
-}
-```
+### Format Specifications
+
+- **Format**: WAV (mono)
+- **Recommended sampling rate**: 44.1 kHz (44100 Hz)
+- **Minimum sampling rate**: 8 kHz
+- **Channel**: Mono (single channel)
+
+### API-Specific Requirements
 
-The emotions returned in `emotions` are the highest confidence emotion returned from the model, alongside the timestamp and confidence. The number of values in `emotions` correlates directly to the length of the input file. We recommend dropping `emotions` with confidence under 0.38, but that is at the user's discretion.
+- **Discrete API**: 4-10 seconds per file
+- **Async API**: Minimum 5 seconds, maximum 1 GB
+- **Streaming API**: Real-time audio chunks (Buffer or ArrayBuffer)
+
+For custom microphone specifications or stereo/multi-channel support, please [contact us](https://www.getvalenceai.com/contact).
 
 ## Examples
 
-Run the included examples:
+Example scripts are available in the [`examples/`](./examples) directory:
 
 ```bash
 # Install dependencies
@@ -253,12 +370,37 @@ npm install
 # Run discrete audio example
 npm run example:discrete
 
-# Run asynch audio example  
+# Run async audio example
 npm run example:asynch
 
+# Run streaming example
+npm run example:streaming
+
 # Or run directly
 node examples/uploadShort.js
 node examples/uploadLong.js
+node examples/streamingAudio.js
+```
+
+## Error Handling
+
+```javascript
+import { ValenceClient } from 'valenceai';
+
+try {
+  const client = new ValenceClient({ apiKey: 'your_key' });
+  const result = await client.discrete.emotions('audio.wav');
+} catch (error) {
+  if (error.message.includes('API key')) {
+    console.error('Authentication error:', error.message);
+  } else if (error.message.includes('File not found')) {
+    console.error('File error:', error.message);
+  } else if (error.message.includes('API error')) {
+    console.error('API error:', error.message);
+  } else {
+    console.error('Unexpected error:', error.message);
+  }
+}
 ```
 
 ## Development
@@ -274,6 +416,9 @@ npm run test:coverage
 
 # Watch mode for development
 npm run test:watch
+
+# Run specific test file
+npm test -- discrete.test.js
 ```
 
 ### Building and Publishing
@@ -287,23 +432,58 @@ npm login
 npm publish --access public
 ```
 
-## What's New in v0.5.0
+## Migration from v0.x
+
+### Key Changes in v1.0.0
+
+1. **Environment Variable**: `VALENCE_API_KEY` is now the standard (consistent naming)
+2. **Unified Client**: Single `ValenceClient` class with nested APIs
+3. **Streaming API**: New WebSocket-based real-time emotion detection
+4. **Rate Limiting**: New API for monitoring usage
+5. **Timeline Data**: Async API now returns detailed timestamp information
+6. **Model Selection**: Explicit model parameter for 4emotions or 7emotions
+
+### Updating Your Code
+
+```javascript
+// Old (v0.x)
+import { predictDiscreteAudioEmotion } from 'valenceai';
+const result = await predictDiscreteAudioEmotion('file.wav');
+
+// New (v1.0.0)
+import { ValenceClient } from 'valenceai';
+const client = new ValenceClient({ apiKey: 'your_key' });
+const result = await client.discrete.emotions('file.wav', '4emotions');
+
+// New streaming capability
+const stream = client.streaming.connect('4emotions');
+stream.on('prediction', callback);
+await stream.connect();
+```
+
+### Breaking Changes
 
-### Major Changes
-- **Unified Client Architecture** - Single `ValenceClient` with nested `discrete` and `asynch` clients
-- **API Restructure**: `predictDiscreteAudioEmotion()` → `client.discrete.emotions()`
-- **API Restructure**: `uploadAsyncAudio()` → `client.asynch.upload()`
-- **API Restructure**: `getEmotions()` → `client.asynch.emotions()`
-- **Single Import**: `import { ValenceClient } from 'valenceai'`
+- `predictDiscreteAudioEmotion()` → `client.discrete.emotions()`
+- `uploadAsyncAudio()` → `client.asynch.upload()`
+- `getEmotions()` → `client.asynch.emotions()`
+- All methods now require creating a `ValenceClient` instance first
+- Model parameter is now required and explicit
 
-### Benefits
-- **API Symmetry** - Identical structure to Python SDK
-- **Intuitive Organization** - Related methods grouped together
-- **Consistent Naming** - Same method names across Python and JavaScript
-- **Enhanced Documentation** - Updated examples and migration guide
-- **Maintained Quality** - All existing functionality preserved
+See [CHANGELOG.md](./CHANGELOG.md) for complete migration guide.
 
-See [CHANGELOG.md](./CHANGELOG.md) for complete details and migration guide.
+## TypeScript Support
+
+The SDK includes comprehensive JSDoc annotations for full TypeScript IntelliSense:
+
+```typescript
+import { ValenceClient } from 'valenceai';
+
+const client: ValenceClient = new ValenceClient({ apiKey: 'your_key' });
+
+// Full type inference and autocomplete
+const result = await client.discrete.emotions('audio.wav', '4emotions');
+// result.dominant_emotion is typed
+```
 
 ## Contributing
 
@@ -317,9 +497,9 @@ We welcome contributions! Please:
 
 ## Support
 
-- **Documentation**: See [API Reference](#api-reference) above
+- **Documentation**: [API Documentation](https://docs.getvalenceai.com)
 - **Issues**: [GitHub Issues](https://github.com/valencevibrations/valence-sdk-js/issues)
-- **Questions**: Contact [Valence AI](https://getvalenceai.com)
+- **Questions**: [Valence AI Support](https://www.getvalenceai.com/contact)
 
 ## License