@voice-ai-workforce/core

> Core voice AI engine with 3-tier interface modes for workforce management applications


✨ New: 3-Tier Interface Mode System

🔧 Developer Mode - Full technical interface with debug information
🏢 Project Mode - Balanced interface for business applications
👤 End-User Mode - Clean, simple interface for employees/customers

📦 Installation

``bash
npm install @voice-ai-workforce/core @voice-ai-workforce/types
`

🚀 Quick Start by Mode

$3

`typescript
import { VoiceAI } from '@voice-ai-workforce/core';

const voiceAI = new VoiceAI({
speechToText: { provider: 'web-speech', language: 'en-US' },
textToSpeech: { provider: 'web-speech', speed: 1.0 },
aiProvider: { provider: 'openai', model: 'gpt-3.5-turbo' },
responseMode: 'both',

// NEW: Developer mode configuration
interfaceMode: 'developer',
visibility: {
showDebugInfo: true,
showProviders: true,
showConfidenceScores: true,
showProcessingTimes: true,
showTechnicalErrors: true
}
});

// Get full debug information
const response = await voiceAI.processTextInput("clock me in");
console.log('Full response with debug data:', response);
// Response includes: provider info, confidence scores, processing times, etc.
`

$3

`typescript
const voiceAI = new VoiceAI({
speechToText: { provider: 'web-speech', language: 'en-US' },
textToSpeech: { provider: 'web-speech', speed: 1.0 },
aiProvider: { provider: 'openai', model: 'gpt-3.5-turbo' },
responseMode: 'both',

// NEW: Project mode configuration
interfaceMode: 'project',
visibility: {
showProviders: true, // Show provider names
showConfidenceScores: true, // Show confidence for quality
showDebugInfo: false, // Hide technical details
showTechnicalErrors: false // User-friendly errors
}
});

// Get business-appropriate information
const response = await voiceAI.processTextInput("assign task to John");
console.log('Business response:', response);
// Response includes: provider status, confidence, but no debug data
`

$3

`typescript
const voiceAI = new VoiceAI({
speechToText: { provider: 'web-speech', language: 'en-US' },
textToSpeech: { provider: 'web-speech', speed: 1.0 },
aiProvider: { provider: 'openai', model: 'gpt-3.5-turbo' },
responseMode: 'both',

// NEW: End-user mode configuration
interfaceMode: 'end-user',
visibility: {
useGenericLabels: true, // "Voice Assistant" not "OpenAI"
showProviders: false, // Hide all provider info
showDebugInfo: false, // No technical details
showConfidenceScores: false, // No confusing numbers
showTechnicalErrors: false, // Friendly error messages
customLabels: {
errors: {
generic: 'Voice assistant is temporarily unavailable',
connection: 'Please check your connection',
permission: 'Microphone permission required'
}
}
}
});

// Get simple, user-friendly response
const response = await voiceAI.processTextInput("help me");
console.log('Simple response:', response);
// Response includes: just the text and basic success flag
`

🎯 Mode Selection Guide

| Use Case | Recommended Mode | Why |
|----------|------------------|-----|
| Package Development | Developer | Need all debug info and technical details |
| Business Admin Panel | Project | Configuration + analytics without overwhelming detail |
| Employee Mobile App | End-User | Clean interface focused on core functionality |
| Customer Support | End-User | Simple "ask for help" without technical jargon |

📖 Updated API Reference

$3

`typescript
new VoiceAI(config: VoiceAIConfig, events?: Partial)
`

#### New Mode-Aware Configuration

`typescript
interface VoiceAIConfig {
// Existing configuration...
speechToText: SpeechToTextConfig;
textToSpeech: TextToSpeechConfig;
aiProvider: AIProviderConfig;

// NEW: Mode system
interfaceMode?: 'developer' | 'project' | 'end-user';
visibility?: VisibilityConfig;
}
`

#### Mode-Filtered Responses

Responses are automatically filtered based on the current mode:

`typescript
// Developer mode - full information
{
text: "You are now clocked in",
success: true,
metadata: {
provider: "openai",
confidence: 0.95,
processingTime: 245,
cached: false
}
}

// Project mode - business-relevant info
{
text: "You are now clocked in",
success: true,
metadata: {
provider: "openai",
confidence: 0.95
// processingTime filtered out
}
}

// End-user mode - minimal info
{
text: "You are now clocked in",
success: true
// metadata filtered out completely
}
`

🏗️ Workforce Mode Presets

Updated workforce utilities with mode awareness:

`typescript
import { createWorkforceVoiceAI, WorkforcePresets } from '@voice-ai-workforce/core';

// Create role-specific instance with appropriate mode
const fieldWorkerAI = createWorkforceVoiceAI({
userRole: 'field_worker',
permissions: ['clock:in', 'clock:out'],
endpoints: { clockIn: '/api/clock-in' }
}, {
// Field workers get end-user mode for simplicity
interfaceMode: 'end-user'
});

const managerAI = createWorkforceVoiceAI({
userRole: 'manager',
permissions: ['assign:tasks', 'view:analytics'],
endpoints: { assignTask: '/api/tasks/assign' }
}, {
// Managers get project mode for configuration
interfaceMode: 'project'
});
`

🔧 Mode-Aware Error Handling

Errors are filtered based on the current mode:

`typescript
// Developer mode - full technical details
{
code: 'OPENAI_API_ERROR',
message: 'OpenAI API request failed: 429 Rate limit exceeded',
details: {
statusCode: 429,
headers: {...},
stack: '...'
},
suggestions: ['Check API key', 'Implement rate limiting']
}

// Project mode - business-friendly technical info
{
code: 'API_ERROR',
message: 'Voice service temporarily unavailable due to rate limits',
suggestions: ['Try again in a moment', 'Check service status']
}

// End-user mode - simple, friendly message
{
code: 'VOICE_ERROR',
message: 'Voice assistant is temporarily unavailable',
suggestions: ['Please try again']
}
`

🎯 Migration from v1.x

$3


`typescript
const voiceAI = new VoiceAI({
speechToText: { provider: 'web-speech' },
aiProvider: { provider: 'openai' }
// Fixed interface for everyone
});
`

$3

`typescript
const voiceAI = new VoiceAI({
speechToText: { provider: 'web-speech' },
aiProvider: { provider: 'openai' },

// NEW: Interface mode selection
interfaceMode: 'end-user', // or 'project' or 'developer'
visibility: {
showProviders: false, // Hide "OpenAI" from end users
useGenericLabels: true, // Show "Voice Assistant"
showDebugInfo: false // No technical details
}
});
``

✨ Key Benefits of Mode System

$3

- Full Debugging: See provider details, confidence scores, processing times
- Complete Error Info: Stack traces and technical details
- Advanced Analytics: All metrics and performance data

$3

- Business Configuration: Provider status and settings without overwhelming detail
- Quality Metrics: Confidence scores for monitoring
- Professional Interface: Technical but user-friendly

$3

- Clean Interface: "Voice Assistant" instead of "OpenAI API"
- Friendly Errors: "Voice unavailable" instead of "HTTP 429 error"
- Focus on Tasks: No technical distractions

🌐 Browser Support

Mode system works across all supported browsers with no additional requirements.

📚 Examples

See updated examples in the API Reference and Examples documentation.

🔗 Related Packages

- @voice-ai-workforce/react - React components with mode support
- @voice-ai-workforce/types - TypeScript definitions for mode system

📄 License

MIT © [Griseld Gerveni, CTO of VenueBoost Inc.]