Back to site
ProsodyAI Docs
TypeScript SDK

Type Reference

Complete TypeScript type definitions

Type Reference

Complete TypeScript type definitions for the ProsodyAI SDK.

Core Types

Emotion

type Emotion =
  | 'neutral'
  | 'happy'
  | 'sad'
  | 'angry'
  | 'fearful'
  | 'disgusted'
  | 'surprised'
  | 'contempt'
  | 'anxious'
  | 'confused'
  | 'excited'
  | 'amused'
  | 'content';

Vertical

type Vertical =
  | 'contact_center'
  | 'healthcare'
  | 'sales'
  | 'education'
  | 'hr_interviews'
  | 'media_entertainment'
  | 'finance'
  | 'legal';

VADScore

interface VADScore {
  valence: number;    // -1 (negative) to 1 (positive)
  arousal: number;    // 0 (calm) to 1 (excited)
  dominance: number;  // 0 (submissive) to 1 (dominant)
}

Client Types

ProsodyOptions

interface ProsodyOptions {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
  retries?: number;
  vertical?: Vertical;
  streaming?: StreamingOptions;
}

interface StreamingOptions {
  reconnect?: boolean;
  reconnectDelay?: number;
  maxReconnectAttempts?: number;
  bufferSize?: number;
  sampleRate?: number;
}

Analysis Types

AnalyzeRequest

interface AnalyzeRequest {
  audio?: Buffer | Blob | ArrayBuffer;
  audioBase64?: string;
  audioUrl?: string;
  vertical?: Vertical;
  features?: Feature[];
  transcript?: string;
  speakerId?: string;
  sessionId?: string;
  metadata?: Record<string, unknown>;
}

type Feature = 
  | 'emotion' 
  | 'prosody' 
  | 'vad' 
  | 'vertical' 
  | 'prediction';

AnalyzeResponse

interface AnalyzeResponse {
  // Primary emotion
  emotion: Emotion;
  confidence: number;
  emotionProbabilities: Record<Emotion, number>;
  
  // VAD scores
  valence: number;
  arousal: number;
  dominance: number;
  
  // Prosodic features
  prosody?: ProsodyFeatures;
  
  // Vertical-specific
  state?: string;
  metrics?: VerticalMetrics;
  
  // Metadata
  duration: number;
  processedAt: string;
  requestId: string;
}

ProsodyFeatures

interface ProsodyFeatures {
  pitch: {
    mean: number;
    std: number;
    min: number;
    max: number;
    range: number;
    contour: number[];
  };
  energy: {
    mean: number;
    std: number;
    contour: number[];
  };
  rhythm: {
    speechRate: number;      // syllables/sec
    pauseRate: number;       // pauses/sec
    averagePauseDuration: number;
  };
  voiceQuality: {
    jitter: number;
    shimmer: number;
    hnr: number;             // harmonics-to-noise ratio
  };
}

Streaming Types

StreamOptions

interface StreamOptions {
  vertical: Vertical;
  sessionId?: string;
  speakerId?: string;
  sampleRate?: number;
  channels?: number;
  onEmotion?: (data: EmotionEvent) => void;
  onPrediction?: (data: PredictionEvent) => void;
  onState?: (data: StateEvent) => void;
  onError?: (error: Error) => void;
  onClose?: () => void;
}

EmotionEvent

interface EmotionEvent {
  emotion: Emotion;
  confidence: number;
  valence: number;
  arousal: number;
  dominance: number;
  timestamp: number;
  utteranceId: string;
}

PredictionEvent

interface PredictionEvent {
  escalationRisk: number;
  churnRisk: number;
  resolutionProbability: number;
  dealCloseProbability: number;
  interventionNeeded: number;
  predictedCsat: number;
  sentimentForecast: number;
  recommendedTone: RecommendedTone;
  confidence: number;
  timestamp: number;
}

type RecommendedTone =
  | 'empathetic'
  | 'calm'
  | 'enthusiastic'
  | 'professional'
  | 'reassuring'
  | 'apologetic';

StateEvent

interface StateEvent {
  state: string;
  previous: string | null;
  metrics: VerticalMetrics;
  timestamp: number;
}

Session Types

SessionOptions

interface SessionOptions {
  vertical: Vertical;
  sessionId?: string;
  metadata?: Record<string, unknown>;
}

ConversationSession

interface ConversationSession {
  sessionId: string;
  vertical: Vertical;
  
  addUtterance(options: UtteranceOptions): Promise<AnalyzeResponse>;
  getPredictions(): ConversationPrediction;
  getHistory(): UtteranceHistory[];
  end(): Promise<SessionSummary>;
}

interface UtteranceOptions {
  audio: Buffer | Blob;
  speakerId?: string;
  transcript?: string;
}

ConversationPrediction

interface ConversationPrediction {
  escalationRisk: number;
  churnRisk: number;
  resolutionProbability: number;
  dealCloseProbability: number;
  interventionNeeded: number;
  predictedCsat: number;
  sentimentForecast: number;
  recommendedTone: RecommendedTone;
  confidence: number;
}

Vertical Metrics Types

ContactCenterMetrics

interface ContactCenterMetrics {
  csatPredicted: number;
  sentimentTrajectory: 'improving' | 'stable' | 'declining';
  escalationRisk: 'low' | 'medium' | 'high' | 'critical';
  firstCallResolutionLikely: boolean;
  churnRisk: number;
}

HealthcareMetrics

interface HealthcareMetrics {
  depressionMarkers: number;
  anxietyMarkers: number;
  distressLevel: 'none' | 'mild' | 'moderate' | 'severe';
  clinicalAttention: 'routine' | 'monitor' | 'urgent' | 'immediate';
  mentalHealthScreeningRecommended: boolean;
}

SalesMetrics

interface SalesMetrics {
  engagementScore: number;
  buyingIntent: number;
  objectionsDetected: number;
  recommendedAction: string;
  dealCloseProbability: number;
}

Error Types

ProsodyError

class ProsodyError extends Error {
  code: string;
  status: number;
  requestId?: string;
}

Specific Errors

class ValidationError extends ProsodyError {
  details: Record<string, string[]>;
}

class AuthenticationError extends ProsodyError {}

class RateLimitError extends ProsodyError {
  retryAfter: number;
}

class AudioFormatError extends ProsodyError {
  format: string;
  supportedFormats: string[];
}

Fine-Tuning Types

FineTuneJob

interface FineTuneJob {
  id: string;
  name: string;
  description?: string;
  status: FineTuneStatus;
  baseModel: string;
  outputModel?: string;
  vertical: Vertical;
  config: FineTuneConfig;
  metrics?: TrainingMetrics;
  createdAt: string;
  updatedAt: string;
  completedAt?: string;
}

type FineTuneStatus =
  | 'pending'
  | 'uploading'
  | 'queued'
  | 'running'
  | 'completed'
  | 'failed'
  | 'cancelled';

FineTuneConfig

interface FineTuneConfig {
  epochs?: number;
  learningRate?: number;
  batchSize?: number;
  warmupSteps?: number;
  validationSplit?: number;
  shuffleSeed?: number;
  dropout?: number;
  weightDecay?: number;
  earlyStoppingPatience?: number;
  earlyStoppingMetric?: string;
  freezeLayers?: string[];
  customLossWeights?: {
    emotion?: number;
    vad?: number;
    outcome?: number;
  };
}

TrainingMetrics

interface TrainingMetrics {
  loss: number;
  accuracy: number;
  valLoss: number;
  valAccuracy: number;
  f1Score: number;
  epoch: number;
  step: number;
}