valenceai 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2025-06-23
+
+### Added
+- **Enhanced API Compatibility**: JavaScript SDK now matches Python SDK's v0.5.0 feature set
+- **Improved Upload Robustness**: Enhanced error handling and retry logic for async uploads
+- **Sequential Upload Strategy**: Maintains reliable upload performance with proper error recovery
+
+### Changed
+- **Version Alignment**: Updated to v0.5.0 to maintain feature parity with Python SDK
+- **Consistent Documentation**: Updated examples and usage patterns to match Python SDK
+- **Unified User Experience**: Ensures identical functionality across both language implementations
+
+### Technical Improvements
+- **Cross-Platform Consistency**: JavaScript SDK maintains same API patterns as Python SDK
+- **Reliable Upload Process**: Sequential part uploads with comprehensive error handling
+- **Maintained Performance**: Optimized upload strategy for JavaScript environment
+
+### Documentation
+- **Updated Examples**: Aligned with Python SDK documentation patterns
+- **Consistent Naming**: Maintained unified terminology across both SDKs
+- **Enhanced Guides**: Improved usage examples for better developer experience
+
+### Notes
+- **No Breaking Changes**: All existing functionality preserved
+- **Feature Parity**: JavaScript SDK maintains equivalent capabilities to Python SDK
+- **Semantic Versioning**: Version bump reflects alignment with Python SDK capabilities
+
+## [0.4.1] - 2025-06-18
+
+### Changed
+- **BREAKING**: Environment variable renamed: `VALENCE_ASYNC_URL` → `VALENCE_ASYNCH_URL` for consistency with `asynch` client naming
+
+### Technical Improvements
+- **Consistent naming standard** across client API and environment variables
+- **All test suites updated** to use new environment variable name
+- **Documentation updated** across all README and configuration files
+- **User-Agent string updated** to use `valenceai/0.4.1` branding
+
+### Migration Guide
+```javascript
+// Environment variable change
+// Old: VALENCE_ASYNC_URL=https://...
+// New: VALENCE_ASYNCH_URL=https://...
+
+// All other functionality remains identical
+import { ValenceClient } from 'valenceai';
+const client = new ValenceClient();
+const requestId = await client.asynch.upload('audio.wav');  // Uses VALENCE_ASYNCH_URL
+```
+
 ## [0.4.0] - 2025-06-18
 
 ### Changed
@@ -12,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **BREAKING**: Installation command: `npm install valenceai` (was `npm install valence-sdk`)
 - **BREAKING**: Import statement: `import { ValenceClient } from 'valenceai'` (was `'valence-sdk'`)
 - **Package description updated** to reflect new unified naming
-- **User-Agent string updated** to use `valenceai/0.4.0` branding
+- **User-Agent string updated** to use `valenceai` branding
 - **Updated example files** to use new package import syntax
 
 ### Technical Improvements
@@ -59,7 +109,7 @@ const result = await client.discrete.emotions('audio.wav', '7emotions');
 - **BREAKING**: `getEmotions()` → `client.asynch.emotions()`
 - **BREAKING**: Environment variable names updated for consistency:
   - `VALENCE_SHORT_URL` → `VALENCE_DISCRETE_URL` 
-  - `VALENCE_LONG_URL` → `VALENCE_ASYNC_URL`
+  - `VALENCE_LONG_URL` → `VALENCE_ASYNCH_URL`
 - **Import pattern**: `import { ValenceClient } from 'valenceai'` (single import)
 - **Parameter naming**: `maxTries` → `maxAttempts`, `intervalMs` → `intervalSeconds`
 - **Examples updated** to use new unified client structure

package/README.md

@@ -1,33 +1,56 @@
-# 🎧 Valence SDK for Emotion Detection (JavaScript)
+# Valence SDK for Emotion Detection (JavaScript)
 
 **valenceai** is a Node.js SDK for interacting with the [Valence Vibrations](https://valencevibrations.com) Emotion Detection API. It provides full support for uploading discrete and async audio files to retrieve their emotional signatures.
 
-## ✨ Features
+## Features
 
-- 🎯 **Discrete audio processing** - Single API call for short audio files
-- 🔄 **Async audio processing** - Multipart streaming for long audio files  
-- 🎭 **Emotion models** - Choose between 4-emotion or 7-emotion detection models
-- ⚙️ **Environment configuration** - Built-in support for `.env` configuration
-- 📊 **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
-- 🔒 **Security focused** - Input validation and secure error handling
+- **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
+- **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
+- **Security focused** - Input validation and secure error handling
 
-## 📦 Installation
+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. 
+
+  _Coming soon_ – The API will include a model choice parameter, allowing users to choose between models of 4, 5, and 7 emotions.
+
+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
+
+While our APIs include the same model offerings in the backend, they are best suited for different purposes.
+
+|               | 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. Optionally, the confidence scores of all other emotions in the model can be 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                                                                                                          |
+
+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 **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.
+
+  _Coming soon_ –  StreamingAPI via WebSockets for real-time analysis of an audio stream.
+
+## Installation
 
 ```bash
 npm install valenceai
 ```
 
-## 🔧 Configuration
+## Configuration
 
 Create a `.env` file in your project root:
 
 ```env
 VALENCE_API_KEY=your_api_key                    # Required: Your Valence API key
 VALENCE_DISCRETE_URL=https://discrete-api-url   # Optional: Discrete audio endpoint
-VALENCE_ASYNC_URL=https://async-api-url         # Optional: Async audio endpoint  
+VALENCE_ASYNCH_URL=https://async-api-url        # Optional: Asynch audio endpoint  
 VALENCE_LOG_LEVEL=info                          # Optional: debug, info, warn, error
 ```
 
@@ -44,7 +67,7 @@ try {
 }
 ```
 
-## 🚀 Usage
+## Usage
 
 ### Discrete Audio (Short Files)
 
@@ -53,14 +76,14 @@ import { ValenceClient } from 'valenceai';
 
 try {
   const client = new ValenceClient();
-  const result = await client.discrete.emotions('audio.wav', '7emotions');
-  console.log('Emotions detected:', result);
+  const result = await client.discrete.emotions('YOUR_FILE.wav');
+  console.log('Emotion detected:', result);
 } catch (error) {
   console.error('Error:', error.message);
 }
 ```
 
-### Async Audio (Long Files)
+### Asynch Audio (Long Files)
 
 ```js
 import { ValenceClient } from 'valenceai';
@@ -69,7 +92,7 @@ try {
   const client = new ValenceClient();
   
   // Upload the audio file
-  const requestId = await client.asynch.upload('long_audio.wav');
+  const requestId = await client.asynch.upload('YOUR_FILE.wav');
   console.log('Upload complete. Request ID:', requestId);
   
   // Get emotions from uploaded audio
@@ -102,25 +125,24 @@ const emotions = await client.asynch.emotions(
 );
 ```
 
-## 🎛️ API Reference
+## API Reference
 
 ### `new ValenceClient(partSize?, maxRetries?)`
 
 Creates a new Valence client with nested discrete and asynch clients.
 
 **Parameters:**
-- `partSize` (number, optional): Size of each part in bytes for async uploads (default: 5MB)
-- `maxRetries` (number, optional): Maximum retry attempts for async uploads (default: 3)
+- `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)
 
 **Returns:** `ValenceClient` instance with `discrete` and `asynch` properties
 
-### `client.discrete.emotions(filePath, model?)`
+### `client.discrete.emotions(filePath)`
 
 Predicts emotions for discrete (short) audio files using a single API call.
 
 **Parameters:**
 - `filePath` (string): Path to the audio file
-- `model` (string, optional): `"4emotions"` or `"7emotions"` (default: `"4emotions"`)
 
 **Returns:** `Promise<Object>` - Emotion prediction results
 
@@ -128,7 +150,7 @@ Predicts emotions for discrete (short) audio files using a single API call.
 
 ### `client.asynch.upload(filePath)`
 
-Uploads async (long) audio files using multipart upload for processing.
+Uploads asynch (long) audio files using multipart upload for processing.
 
 **Parameters:**
 - `filePath` (string): Path to the audio file
@@ -146,9 +168,9 @@ Retrieves emotion prediction results for async audio processing.
 - `maxAttempts` (number, optional): Maximum polling attempts (default: 20, range: 1-100)
 - `intervalSeconds` (number, optional): Polling interval in seconds (default: 5, range: 1-60)
 
-**Returns:** `Promise<Object>` - Emotion prediction results
+**Returns:** `Promise<Object>` - Emotion detection results
 
-**Throws:** Error if requestId is invalid or prediction times out
+**Throws:** Error if requestId is invalid or detection times out
 
 ### `validateConfig()`
 
@@ -156,7 +178,71 @@ Validates the current SDK configuration.
 
 **Throws:** Error if required configuration is missing or invalid
 
-## 🧪 Examples
+## Inputs and Outputs
+
+### 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. 
+
+For the **DiscreteAPI**, input data is an audio file in the .wav format. 
+
+For the **AsynchAPI**, input data is an audio file, in the .wav format.
+
+### Outputs
+
+Outputs are returned as JSONs in the following formats: 
+
+**DiscreteAPI:**
+
+```json
+{
+  "main_emotion": "happy",
+  "confidence": 0.777777777,
+  "all_predictions": {
+    "angry": 0.123456789,
+    "happy": 0.777777777,
+    "neutral": 0.23456789,
+    "sad": 0.098765432
+  }
+}
+```
+
+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. 
+
+**AsynchAPI:**
+
+```json
+{
+  "request_id": "27a33189-bdd7-47ca-9817-abacfb7bdaf3",
+  "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
+    }
+	"..."
+  ]
+}
+```
+
+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.
+
+## Examples
 
 Run the included examples:
 
@@ -167,15 +253,15 @@ npm install
 # Run discrete audio example
 npm run example:discrete
 
-# Run async audio example  
-npm run example:async
+# Run asynch audio example  
+npm run example:asynch
 
 # Or run directly
 node examples/uploadShort.js
 node examples/uploadLong.js
 ```
 
-## 🛠 Development
+## Development
 
 ### Testing
 
@@ -201,25 +287,25 @@ npm login
 npm publish --access public
 ```
 
-## 🚀 What's New in v0.3.0
+## What's New in v0.3.0
 
 ### 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'`
+- **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'`
 
 ### Benefits
-- ✅ **Perfect 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
+- **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 details and migration guide.
 
-## 🤝 Contributing
+## Contributing
 
 We welcome contributions! Please:
 
@@ -229,12 +315,12 @@ We welcome contributions! Please:
 4. Ensure all tests pass: `npm test`
 5. Submit a pull request
 
-## 🆘 Support
+## Support
 
-- 📖 **Documentation**: See [API Reference](#🎛️-api-reference) above
-- 🐛 **Issues**: [GitHub Issues](https://github.com/valencevibrations/valence-sdk-js/issues)
-- 💬 **Questions**: Contact [Valence Vibrations](https://valencevibrations.com)
+- **Documentation**: See [API Reference](#api-reference) above
+- **Issues**: [GitHub Issues](https://github.com/valencevibrations/valence-sdk-js/issues)
+- **Questions**: Contact [Valence AI](https://getvalenceai.com)
 
-## 📜 License
+## License
 
-ISC License © 2025 [Valence Vibrations](https://valencevibrations.com)
+Private License © 2025 [Valence Vibrations, Inc](https://getvalenceai.com), a Delaware public benefit corporation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "valenceai",
-    "version": "0.4.0",
+    "version": "0.5.0",
     "type": "module",
     "main": "src/index.js",
     "scripts": {

package/src/client.js

@@ -13,6 +13,6 @@ export const getHeaders = () => {
   
   return {
     'x-api-key': config.apiKey,
-    'User-Agent': 'valenceai/0.4.0'
+    'User-Agent': 'valenceai/0.4.1'
   };
 };

package/src/config.js

@@ -8,7 +8,7 @@ dotenv.config();
 export const config = {
   apiKey: process.env.VALENCE_API_KEY,
   discreteAudioUrl: process.env.VALENCE_DISCRETE_URL || 'https://xc8n2bo4f0.execute-api.us-west-2.amazonaws.com/emotionprediction',
-  asyncAudioUrl: process.env.VALENCE_ASYNC_URL || 'https://wsgol61783.execute-api.us-west-2.amazonaws.com/prod',
+  asyncAudioUrl: process.env.VALENCE_ASYNCH_URL || 'https://wsgol61783.execute-api.us-west-2.amazonaws.com/prod',
   logLevel: process.env.VALENCE_LOG_LEVEL || 'info',
 };
 
@@ -26,7 +26,7 @@ export function validateConfig() {
   }
   
   if (!config.asyncAudioUrl || !config.asyncAudioUrl.startsWith('https://')) {
-    throw new Error('VALENCE_ASYNC_URL must be a valid HTTPS URL');
+    throw new Error('VALENCE_ASYNCH_URL must be a valid HTTPS URL');
   }
   
   const validLogLevels = ['debug', 'info', 'warn', 'error'];

package/tests/asyncAudio.test.js

@@ -10,7 +10,7 @@ describe('AsyncAudio', () => {
   beforeEach(() => {
     process.env = { ...originalEnv };
     process.env.VALENCE_API_KEY = 'test-api-key';
-    process.env.VALENCE_ASYNC_URL = 'https://test-api.com';
+    process.env.VALENCE_ASYNCH_URL = 'https://test-api.com';
     
     fsMock = jest.spyOn(fs, 'existsSync');
     statMock = jest.spyOn(fs, 'statSync');
@@ -318,7 +318,7 @@ describe('AsyncAudio', () => {
       const scope = nock('https://test-api.com')
         .get('/prediction')
         .matchHeader('x-api-key', 'test-api-key')
-        .matchHeader('User-Agent', 'valenceai/0.4.0')
+        .matchHeader('User-Agent', 'valenceai/0.4.1')
         .query({ request_id: 'req-123' })
         .reply(200, { emotions: {} });
 

package/tests/client.test.js

@@ -23,7 +23,7 @@ describe('Client', () => {
       
       expect(headers).toEqual({
         'x-api-key': 'test-api-key',
-        'User-Agent': 'valenceai/0.4.0'
+        'User-Agent': 'valenceai/0.4.1'
       });
     });
 

package/tests/config.test.js

@@ -16,7 +16,7 @@ describe('Config', () => {
     test('should load from environment variables', async () => {
       process.env.VALENCE_API_KEY = 'test-key';
       process.env.VALENCE_DISCRETE_URL = 'https://test-short.com';
-      process.env.VALENCE_ASYNC_URL = 'https://test-long.com';
+      process.env.VALENCE_ASYNCH_URL = 'https://test-long.com';
       process.env.VALENCE_LOG_LEVEL = 'debug';
 
       // Re-import to get fresh config
@@ -31,7 +31,7 @@ describe('Config', () => {
     test('should use default URLs when not provided', async () => {
       process.env.VALENCE_API_KEY = 'test-key';
       delete process.env.VALENCE_DISCRETE_URL;
-      delete process.env.VALENCE_ASYNC_URL;
+      delete process.env.VALENCE_ASYNCH_URL;
 
       // Re-import to get fresh config
       const { config: freshConfig } = await import('../src/config.js?' + Math.random());
@@ -54,7 +54,7 @@ describe('Config', () => {
     test('should pass with valid configuration', () => {
       process.env.VALENCE_API_KEY = 'test-key';
       process.env.VALENCE_DISCRETE_URL = 'https://test-short.com';
-      process.env.VALENCE_ASYNC_URL = 'https://test-long.com';
+      process.env.VALENCE_ASYNCH_URL = 'https://test-long.com';
       process.env.VALENCE_LOG_LEVEL = 'info';
 
       expect(() => validateConfig()).not.toThrow();
@@ -75,9 +75,9 @@ describe('Config', () => {
 
     test('should throw when long URL is not HTTPS', async () => {
       process.env.VALENCE_API_KEY = 'test-key';
-      process.env.VALENCE_ASYNC_URL = 'http://test-long.com';
+      process.env.VALENCE_ASYNCH_URL = 'http://test-long.com';
       const { validateConfig: freshValidateConfig } = await import('../src/config.js?' + Math.random());
-      expect(() => freshValidateConfig()).toThrow('VALENCE_ASYNC_URL must be a valid HTTPS URL');
+      expect(() => freshValidateConfig()).toThrow('VALENCE_ASYNCH_URL must be a valid HTTPS URL');
     });
 
     test('should throw with invalid log level', async () => {

package/tests/discreteAudio.test.js

@@ -156,7 +156,7 @@ describe('DiscreteAudio', () => {
       const scope = nock('https://test-api.com')
         .post('/predict?model=4emotions')
         .matchHeader('x-api-key', 'test-api-key')
-        .matchHeader('User-Agent', 'valenceai/0.4.0')
+        .matchHeader('User-Agent', 'valenceai/0.4.1')
         .reply(200, { emotions: {} });
 
       const client = new ValenceClient();

package/tests/setup.js

@@ -1,5 +1,5 @@
 // Test setup file to configure environment
 process.env.VALENCE_API_KEY = 'test-api-key-12345';
 process.env.VALENCE_DISCRETE_URL = 'https://test-short.com';
-process.env.VALENCE_ASYNC_URL = 'https://test-long.com';
+process.env.VALENCE_ASYNCH_URL = 'https://test-long.com';
 process.env.VALENCE_LOG_LEVEL = 'debug';