@lokutor/sdk 1.1.17 → 1.1.19

package/src/index.ts

@@ -0,0 +1,25 @@
+export * from './types';
+export * from './client';
+export * from './audio-utils';
+export * from './browser-audio';
+export { VoiceAgentClient, TTSClient, simpleConversation, simpleTTS } from './client';
+export { BrowserAudioManager } from './browser-audio';
+export {
+  pcm16ToFloat32,
+  float32ToPcm16,
+  resample,
+  resampleWithAntiAliasing,
+  calculateRMS,
+  normalizeAudio,
+  StreamResampler,
+} from './audio-utils';
+export type {
+  VoiceAgentOptions,
+  Viseme,
+  VoiceInfo,
+  LanguageInfo,
+  ModelInfo,
+  ServerConfig,
+  ServerStatus,
+  HealthStatus,
+} from './types';

package/src/node-audio.ts

@@ -0,0 +1,115 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+
+import { AudioManager } from './client';
+import { AUDIO_CONFIG } from './types';
+
+/**
+ * Node.js-specific AudioManager implementation.
+ * Note: These require 'speaker' and 'node-record-lpcm16' to be installed by the user.
+ */
+export class NodeAudioManager implements AudioManager {
+  private speaker: any = null;
+  private recorder: any = null;
+  private recordingStream: any = null;
+  private isMuted: boolean = false;
+  private isListening: boolean = false;
+
+  constructor() {}
+
+  async init(): Promise<void> {
+    try {
+      // Dynamic imports to avoid crashing if dependencies are missing at build time
+      // The user must install these manually for managed Node.js audio
+      const Speaker = await import('speaker').catch(() => null);
+      if (!Speaker) {
+        console.warn('⚠️  Package "speaker" is missing. Hardware output will be disabled.');
+        console.warn('👉 Run: npm install speaker');
+      }
+    } catch (e) {
+      console.error('Error initializing Node audio:', e);
+    }
+  }
+
+  async startMicrophone(onAudioInput: (pcm16Data: Uint8Array) => void): Promise<void> {
+    if (this.isListening) return;
+
+    try {
+      const recorder = await import('node-record-lpcm16').catch(() => null);
+      if (!recorder) {
+        throw new Error('Package "node-record-lpcm16" is missing. Microphone input failed.\n👉 Run: npm install node-record-lpcm16');
+      }
+
+      console.log('🎤 Starting microphone (Node.js)...');
+      
+      this.recordingStream = recorder.record({
+        sampleRate: AUDIO_CONFIG.SAMPLE_RATE,
+        threshold: 0,
+        verbose: false,
+        recordProgram: 'sox', // default
+      });
+
+      this.recordingStream.stream().on('data', (chunk: Buffer) => {
+        if (!this.isMuted && onAudioInput) {
+          onAudioInput(new Uint8Array(chunk));
+        }
+      });
+
+      this.isListening = true;
+    } catch (e: any) {
+      console.error('Failed to start microphone:', e.message);
+      throw e;
+    }
+  }
+
+  stopMicrophone(): void {
+    if (this.recordingStream) {
+      this.recordingStream.stop();
+      this.recordingStream = null;
+    }
+    this.isListening = false;
+  }
+
+  async playAudio(pcm16Data: Uint8Array): Promise<void> {
+    try {
+      if (!this.speaker) {
+        const Speaker = (await import('speaker')).default;
+        this.speaker = new Speaker({
+          channels: AUDIO_CONFIG.CHANNELS,
+          bitDepth: 16,
+          sampleRate: AUDIO_CONFIG.SPEAKER_SAMPLE_RATE,
+        });
+      }
+
+      // Node.js 'speaker' accepts Buffers
+      this.speaker.write(Buffer.from(pcm16Data));
+    } catch (e) {
+      console.error('NodeAudioManager: speaker playback failed:', e);
+    }
+  }
+
+  stopPlayback(): void {
+    if (this.speaker) {
+      this.speaker.end();
+      this.speaker = null;
+    }
+  }
+
+  cleanup(): void {
+    this.stopMicrophone();
+    this.stopPlayback();
+  }
+
+  isMicMuted(): boolean {
+    return this.isMuted;
+  }
+
+  setMuted(muted: boolean): void {
+    this.isMuted = muted;
+  }
+
+  getAmplitude(): number {
+    // Amplitude tracking implementation for Node.js would require extra processing
+    // leaving as stub for now
+    return 0;
+  }
+}

package/src/types.ts

@@ -0,0 +1,270 @@
+/**
+ * Available voice styles for the Lokutor AI Agent
+ */
+export enum VoiceStyle {
+  // Female voices
+  F1 = "F1",
+  F2 = "F2",
+  F3 = "F3",
+  F4 = "F4",
+  F5 = "F5",
+
+  // Male voices
+  M1 = "M1",
+  M2 = "M2",
+  M3 = "M3",
+  M4 = "M4",
+  M5 = "M5",
+}
+
+/**
+ * Supported languages for speech and text
+ */
+export enum Language {
+  ENGLISH = "en",
+  SPANISH = "es",
+  FRENCH = "fr",
+  PORTUGUESE = "pt",
+  KOREAN = "ko",
+}
+
+/**
+ * Audio configuration constants
+ */
+export const AUDIO_CONFIG = {
+  SAMPLE_RATE: 16000,
+  SAMPLE_RATE_INPUT: 16000,
+  SPEAKER_SAMPLE_RATE: 44100,
+  SAMPLE_RATE_OUTPUT: 44100,
+  CHANNELS: 1,
+  CHUNK_DURATION_MS: 20,
+  get CHUNK_SIZE() {
+    return Math.floor((this.SAMPLE_RATE * this.CHUNK_DURATION_MS) / 1000);
+  }
+};
+
+/**
+ * Default WebSocket URLs
+ */
+export const DEFAULT_URLS = {
+  VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
+  TTS: "wss://api.lokutor.com/ws/tts",
+};
+
+/**
+ * SDK Configuration interface
+ */
+export interface LokutorConfig {
+  apiKey: string;
+  onTranscription?: (text: string) => void;
+  onResponse?: (text: string) => void;
+  onAudio?: (data: Uint8Array) => void;
+  onStatus?: (status: string) => void;
+  onError?: (error: any) => void;
+}
+
+/**
+ * Text-to-Speech synthesis request options
+ */
+export interface SynthesizeOptions {
+  text: string;
+  voice?: VoiceStyle;
+  language?: Language;
+  speed?: number;
+  steps?: number;
+  visemes?: boolean;
+}
+
+/**
+ * Browser audio configuration options
+ */
+export interface BrowserAudioOptions {
+  inputSampleRate?: number;
+  outputSampleRate?: number;
+  autoGainControl?: boolean;
+  echoCancellation?: boolean;
+  noiseSuppression?: boolean;
+  analyserEnabled?: boolean;
+  onInputError?: (error: Error) => void;
+}
+
+/**
+ * Voice agent conversation options
+ */
+export interface VoiceAgentOptions {
+  prompt?: string;
+  voice?: VoiceStyle;
+  language?: Language;
+  serverUrl?: string;
+  visemes?: boolean;
+  onTranscription?: (text: string) => void;
+  onVisemes?: (visemes: Viseme[]) => void;
+  onStatusChange?: (status: string) => void;
+  onError?: (err: LokutorError) => void;
+}
+
+/**
+ * REST API response types for discovery endpoints.
+ */
+
+export interface VoiceInfo {
+  id: string;
+  gender?: string;
+  languages?: string[];
+}
+
+export interface LanguageInfo {
+  code: string;
+  name: string;
+}
+
+export interface ModelInfo {
+  name: string;
+  description?: string;
+  default?: boolean;
+}
+
+export interface ServerConfig {
+  max_text_length: number;
+  min_speed: number;
+  max_speed: number;
+  min_steps: number;
+  max_steps: number;
+  sample_rate: number;
+  channels: number;
+}
+
+export interface ServerStatus {
+  status: string;
+  timestamp: string;
+  version: string;
+  runtime: string;
+  inference: string;
+  uptime_seconds: number;
+  goroutines: number;
+  mem_alloc_bytes: number;
+  active_connections: number;
+  failed_requests: number;
+  ready: boolean;
+}
+
+export interface HealthStatus {
+  status: string;
+  timestamp: string;
+  version: string;
+  runtime: string;
+  inference: string;
+  load: number;
+}
+
+/**
+ * Viseme data for lip-sync animation
+ * Format: {"v": index, "c": character, "t": timestamp}
+ */
+export interface Viseme {
+  /** Text-position index (which input character the model is attending to), not a stable viseme ID */
+  v: number;
+  /** Character/phoneme being spoken (reduced set: a,e,i,o,u,m,p,b,f,v,t,d,s,z,l,n,r,k,g,sil) */
+  c: string;
+  /** Offset in seconds from the start of the audio stream */
+  t: number;
+}
+
+/**
+ * Tool definition for LLM function calling (OpenAI format)
+ */
+export interface ToolDefinition {
+  type: 'function';
+  function: {
+    name: string;
+    description: string;
+    parameters: {
+      type: 'object';
+      properties: Record<string, any>;
+      required?: string[];
+    };
+  };
+}
+
+/**
+ * Event data for tool execution
+ */
+export interface ToolCall {
+  name: string;
+  arguments: string;
+}
+
+/**
+ * Error code enum matching the backend API error catalog
+ */
+export type ErrorCode =
+  | 'auth.missing_key'
+  | 'auth.invalid_key'
+  | 'auth.rate_limited'
+  | 'auth.time_limited'
+  | 'validation.invalid_voice'
+  | 'validation.invalid_language'
+  | 'validation.text_too_long'
+  | 'validation.speed_out_of_range'
+  | 'validation.steps_out_of_range'
+  | 'validation.invalid_request_format'
+  | 'tts.synthesis_failed'
+  | 'tts.voice_unavailable'
+  | 'tts.model_not_found'
+  | 'tts.session_limit_reached'
+  | 'stt.not_configured'
+  | 'stt.stream_create_failed'
+  | 'stt.language_not_supported'
+  | 'agent.session_failed'
+  | 'agent.provider_error'
+  | 'internal.error'
+  | 'internal.timeout'
+  | 'internal.cancelled'
+  | 'ws.close';
+
+/**
+ * Typed error class for all Lokutor SDK errors.
+ * Includes the backend error code, human-readable message,
+ * optional detail, and whether the operation is retryable.
+ */
+export class LokutorError extends Error {
+  public readonly code: ErrorCode;
+  public readonly detail?: string;
+  public readonly retryable: boolean;
+  public readonly original?: unknown;
+
+  constructor(code: ErrorCode, message: string, opts?: { detail?: string; retryable?: boolean; original?: unknown }) {
+    super(message);
+    this.name = 'LokutorError';
+    this.code = code;
+    this.detail = opts?.detail;
+    this.retryable = opts?.retryable ?? isRetryableCode(code);
+    this.original = opts?.original;
+  }
+}
+
+function isRetryableCode(code: ErrorCode): boolean {
+  const fatal: ErrorCode[] = [
+    'auth.missing_key',
+    'auth.invalid_key',
+    'auth.time_limited',
+    'validation.invalid_voice',
+    'validation.invalid_language',
+    'validation.text_too_long',
+    'validation.speed_out_of_range',
+    'validation.steps_out_of_range',
+    'validation.invalid_request_format',
+    'internal.cancelled',
+  ];
+  return !fatal.includes(code);
+}
+
+/**
+ * Returns true if the given error is a retryable LokutorError.
+ */
+export function isRetryable(error: unknown): boolean {
+  if (error instanceof LokutorError) {
+    return error.retryable;
+  }
+  return false;
+}

package/dist/chunk-UI24THO7.mjs

@@ -1,44 +0,0 @@
-// src/types.ts
-var VoiceStyle = /* @__PURE__ */ ((VoiceStyle2) => {
-  VoiceStyle2["F1"] = "F1";
-  VoiceStyle2["F2"] = "F2";
-  VoiceStyle2["F3"] = "F3";
-  VoiceStyle2["F4"] = "F4";
-  VoiceStyle2["F5"] = "F5";
-  VoiceStyle2["M1"] = "M1";
-  VoiceStyle2["M2"] = "M2";
-  VoiceStyle2["M3"] = "M3";
-  VoiceStyle2["M4"] = "M4";
-  VoiceStyle2["M5"] = "M5";
-  return VoiceStyle2;
-})(VoiceStyle || {});
-var Language = /* @__PURE__ */ ((Language2) => {
-  Language2["ENGLISH"] = "en";
-  Language2["SPANISH"] = "es";
-  Language2["FRENCH"] = "fr";
-  Language2["PORTUGUESE"] = "pt";
-  Language2["KOREAN"] = "ko";
-  return Language2;
-})(Language || {});
-var AUDIO_CONFIG = {
-  SAMPLE_RATE: 16e3,
-  SAMPLE_RATE_INPUT: 16e3,
-  SPEAKER_SAMPLE_RATE: 44100,
-  SAMPLE_RATE_OUTPUT: 44100,
-  CHANNELS: 1,
-  CHUNK_DURATION_MS: 20,
-  get CHUNK_SIZE() {
-    return Math.floor(this.SAMPLE_RATE * this.CHUNK_DURATION_MS / 1e3);
-  }
-};
-var DEFAULT_URLS = {
-  VOICE_AGENT: "wss://api.lokutor.com/ws/agent",
-  TTS: "wss://api.lokutor.com/ws/tts"
-};
-
-export {
-  VoiceStyle,
-  Language,
-  AUDIO_CONFIG,
-  DEFAULT_URLS
-};

package/dist/node-audio-5HOWE6MC.mjs

@@ -1,94 +0,0 @@
-import {
-  AUDIO_CONFIG
-} from "./chunk-UI24THO7.mjs";
-
-// src/node-audio.ts
-var NodeAudioManager = class {
-  speaker = null;
-  recorder = null;
-  recordingStream = null;
-  isMuted = false;
-  isListening = false;
-  constructor() {
-  }
-  async init() {
-    try {
-      const Speaker = await import("speaker").catch(() => null);
-      if (!Speaker) {
-        console.warn('\u26A0\uFE0F  Package "speaker" is missing. Hardware output will be disabled.');
-        console.warn("\u{1F449} Run: npm install speaker");
-      }
-    } catch (e) {
-      console.error("Error initializing Node audio:", e);
-    }
-  }
-  async startMicrophone(onAudioInput) {
-    if (this.isListening) return;
-    try {
-      const recorder = await import("node-record-lpcm16").catch(() => null);
-      if (!recorder) {
-        throw new Error('Package "node-record-lpcm16" is missing. Microphone input failed.\n\u{1F449} Run: npm install node-record-lpcm16');
-      }
-      console.log("\u{1F3A4} Starting microphone (Node.js)...");
-      this.recordingStream = recorder.record({
-        sampleRate: AUDIO_CONFIG.SAMPLE_RATE,
-        threshold: 0,
-        verbose: false,
-        recordProgram: "sox"
-        // default
-      });
-      this.recordingStream.stream().on("data", (chunk) => {
-        if (!this.isMuted && onAudioInput) {
-          onAudioInput(new Uint8Array(chunk));
-        }
-      });
-      this.isListening = true;
-    } catch (e) {
-      console.error("Failed to start microphone:", e.message);
-      throw e;
-    }
-  }
-  stopMicrophone() {
-    if (this.recordingStream) {
-      this.recordingStream.stop();
-      this.recordingStream = null;
-    }
-    this.isListening = false;
-  }
-  async playAudio(pcm16Data) {
-    try {
-      if (!this.speaker) {
-        const Speaker = (await import("speaker")).default;
-        this.speaker = new Speaker({
-          channels: AUDIO_CONFIG.CHANNELS,
-          bitDepth: 16,
-          sampleRate: AUDIO_CONFIG.SPEAKER_SAMPLE_RATE
-        });
-      }
-      this.speaker.write(Buffer.from(pcm16Data));
-    } catch (e) {
-    }
-  }
-  stopPlayback() {
-    if (this.speaker) {
-      this.speaker.end();
-      this.speaker = null;
-    }
-  }
-  cleanup() {
-    this.stopMicrophone();
-    this.stopPlayback();
-  }
-  isMicMuted() {
-    return this.isMuted;
-  }
-  setMuted(muted) {
-    this.isMuted = muted;
-  }
-  getAmplitude() {
-    return 0;
-  }
-};
-export {
-  NodeAudioManager
-};