praisonai 1.3.6 → 1.5.0

package/dist/agent/audio.d.ts

@@ -0,0 +1,190 @@
+/**
+ * AudioAgent - Speech synthesis and transcription agent
+ *
+ * Wraps AI SDK's generateSpeech and transcribe functions for
+ * text-to-speech and speech-to-text capabilities.
+ *
+ * Requires AI SDK: npm install ai @ai-sdk/openai
+ *
+ * @example Text-to-Speech
+ * ```typescript
+ * import { AudioAgent } from 'praisonai';
+ *
+ * const agent = new AudioAgent({
+ *   provider: 'openai',
+ *   voice: 'alloy'
+ * });
+ *
+ * const audio = await agent.speak('Hello, world!');
+ * // Returns audio buffer
+ * ```
+ *
+ * @example Speech-to-Text
+ * ```typescript
+ * const agent = new AudioAgent({ provider: 'openai' });
+ *
+ * const text = await agent.transcribe('./audio.mp3');
+ * console.log(text); // "Hello, world!"
+ * ```
+ */
+/**
+ * Supported audio providers
+ */
+export type AudioProvider = 'openai' | 'elevenlabs' | 'google' | 'deepgram' | 'groq';
+/**
+ * Voice options by provider
+ */
+export type OpenAIVoice = 'alloy' | 'echo' | 'fable' | 'onyx' | 'nova' | 'shimmer';
+export type ElevenLabsVoice = string;
+/**
+ * Audio format options
+ */
+export type AudioFormat = 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm';
+/**
+ * Configuration for AudioAgent
+ */
+export interface AudioAgentConfig {
+    /** Name of the agent */
+    name?: string;
+    /** Audio provider (default: 'openai') */
+    provider?: AudioProvider;
+    /** Voice to use for TTS */
+    voice?: string;
+    /** TTS model to use (provider-specific) */
+    model?: string;
+    /** Audio output format */
+    format?: AudioFormat;
+    /** Speed multiplier for TTS (0.25 to 4.0) */
+    speed?: number;
+    /** Language for transcription */
+    language?: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Options for speak method
+ */
+export interface SpeakOptions {
+    /** Override voice for this call */
+    voice?: string;
+    /** Override model for this call */
+    model?: string;
+    /** Override format for this call */
+    format?: AudioFormat;
+    /** Override speed for this call */
+    speed?: number;
+}
+/**
+ * Options for transcribe method
+ */
+export interface TranscribeOptions {
+    /** Language hint for transcription */
+    language?: string;
+    /** Include word-level timestamps */
+    timestamps?: boolean;
+    /** Return detailed segments */
+    segments?: boolean;
+}
+/**
+ * Result from speak method
+ */
+export interface SpeakResult {
+    /** Audio data as Buffer or ArrayBuffer */
+    audio: Buffer | ArrayBuffer;
+    /** Duration in seconds (if available) */
+    duration?: number;
+    /** Audio format */
+    format: string;
+}
+/**
+ * Result from transcribe method
+ */
+export interface TranscribeResult {
+    /** Transcribed text */
+    text: string;
+    /** Detected language */
+    language?: string;
+    /** Duration in seconds */
+    duration?: number;
+    /** Word-level timestamps (if requested) */
+    words?: Array<{
+        word: string;
+        start: number;
+        end: number;
+    }>;
+    /** Segments (if requested) */
+    segments?: Array<{
+        text: string;
+        start: number;
+        end: number;
+    }>;
+}
+/**
+ * AudioAgent - Speech synthesis and transcription
+ */
+export declare class AudioAgent {
+    readonly id: string;
+    readonly name: string;
+    private config;
+    constructor(config?: AudioAgentConfig);
+    /**
+     * Get default TTS model for provider
+     */
+    private getDefaultModel;
+    /**
+     * Generate speech from text (Text-to-Speech)
+     *
+     * @param text - Text to convert to speech
+     * @param options - Override options for this call
+     * @returns Audio data with metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.speak('Hello, world!');
+     * fs.writeFileSync('output.mp3', result.audio);
+     * ```
+     */
+    speak(text: string, options?: SpeakOptions): Promise<SpeakResult>;
+    /**
+     * Get provider-specific speech model
+     */
+    private getSpeechModel;
+    /**
+     * Transcribe audio to text (Speech-to-Text)
+     *
+     * @param audioInput - Audio file path, URL, or Buffer
+     * @param options - Transcription options
+     * @returns Transcribed text with metadata
+     *
+     * @example From file
+     * ```typescript
+     * const result = await agent.transcribe('./audio.mp3');
+     * console.log(result.text);
+     * ```
+     *
+     * @example From Buffer
+     * ```typescript
+     * const audioBuffer = fs.readFileSync('./audio.mp3');
+     * const result = await agent.transcribe(audioBuffer);
+     * ```
+     */
+    transcribe(audioInput: string | Buffer | ArrayBuffer, options?: TranscribeOptions): Promise<TranscribeResult>;
+    /**
+     * Prepare audio input for transcription
+     */
+    private prepareAudioInput;
+    /**
+     * Get provider-specific transcription model
+     */
+    private getTranscriptionModel;
+    /**
+     * Chat method for agent-like interface
+     * Determines whether to speak or transcribe based on input
+     */
+    chat(input: string): Promise<string>;
+}
+/**
+ * Factory function to create AudioAgent
+ */
+export declare function createAudioAgent(config?: AudioAgentConfig): AudioAgent;
+export default AudioAgent;

package/dist/agent/audio.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * AudioAgent - Speech synthesis and transcription agent
+ *
+ * Wraps AI SDK's generateSpeech and transcribe functions for
+ * text-to-speech and speech-to-text capabilities.
+ *
+ * Requires AI SDK: npm install ai @ai-sdk/openai
+ *
+ * @example Text-to-Speech
+ * ```typescript
+ * import { AudioAgent } from 'praisonai';
+ *
+ * const agent = new AudioAgent({
+ *   provider: 'openai',
+ *   voice: 'alloy'
+ * });
+ *
+ * const audio = await agent.speak('Hello, world!');
+ * // Returns audio buffer
+ * ```
+ *
+ * @example Speech-to-Text
+ * ```typescript
+ * const agent = new AudioAgent({ provider: 'openai' });
+ *
+ * const text = await agent.transcribe('./audio.mp3');
+ * console.log(text); // "Hello, world!"
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioAgent = void 0;
+exports.createAudioAgent = createAudioAgent;
+const crypto_1 = require("crypto");
+/**
+ * AudioAgent - Speech synthesis and transcription
+ */
+class AudioAgent {
+    constructor(config = {}) {
+        this.id = (0, crypto_1.randomUUID)();
+        this.name = config.name ?? `AudioAgent_${(0, crypto_1.randomUUID)().slice(0, 8)}`;
+        this.config = {
+            provider: config.provider ?? 'openai',
+            voice: config.voice ?? 'alloy',
+            model: config.model ?? this.getDefaultModel(config.provider ?? 'openai'),
+            format: config.format ?? 'mp3',
+            speed: config.speed ?? 1.0,
+            language: config.language ?? 'en',
+            verbose: config.verbose ?? false,
+        };
+    }
+    /**
+     * Get default TTS model for provider
+     */
+    getDefaultModel(provider) {
+        switch (provider) {
+            case 'openai':
+                return 'tts-1';
+            case 'elevenlabs':
+                return 'eleven_multilingual_v2';
+            case 'google':
+                return 'text-to-speech';
+            case 'deepgram':
+                return 'aura-asteria-en';
+            case 'groq':
+                return 'whisper-large-v3';
+            default:
+                return 'tts-1';
+        }
+    }
+    /**
+     * Generate speech from text (Text-to-Speech)
+     *
+     * @param text - Text to convert to speech
+     * @param options - Override options for this call
+     * @returns Audio data with metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.speak('Hello, world!');
+     * fs.writeFileSync('output.mp3', result.audio);
+     * ```
+     */
+    async speak(text, options) {
+        const voice = options?.voice ?? this.config.voice;
+        const model = options?.model ?? this.config.model;
+        const speed = options?.speed ?? this.config.speed;
+        if (this.config.verbose) {
+            console.log(`[AudioAgent] Speaking with ${this.config.provider}/${model}, voice: ${voice}`);
+        }
+        try {
+            // Lazy import AI SDK
+            const { experimental_generateSpeech: generateSpeech } = await Promise.resolve().then(() => __importStar(require('ai')));
+            // Get provider-specific speech model
+            const speechModel = await this.getSpeechModel(model, voice);
+            const result = await generateSpeech({
+                model: speechModel,
+                text,
+                voice,
+                // Note: speed is provider-specific, may not be supported by all
+            });
+            // Handle both Buffer and audio file object types
+            const audioData = result.audio instanceof Buffer
+                ? result.audio
+                : (result.audio.arrayBuffer
+                    ? await result.audio.arrayBuffer()
+                    : result.audio);
+            return {
+                audio: audioData,
+                format: this.config.format,
+                duration: result.duration, // If available
+            };
+        }
+        catch (error) {
+            // Check for common issues
+            if (error.message?.includes('Cannot find module')) {
+                throw new Error(`AI SDK not installed. Run: npm install ai @ai-sdk/${this.config.provider}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Get provider-specific speech model
+     */
+    async getSpeechModel(model, voice) {
+        switch (this.config.provider) {
+            case 'openai': {
+                const { openai } = await Promise.resolve().then(() => __importStar(require('@ai-sdk/openai')));
+                return openai.speech(model);
+            }
+            case 'elevenlabs': {
+                // @ts-ignore - optional dependency
+                const elevenlabsModule = await Promise.resolve().then(() => __importStar(require('@ai-sdk/elevenlabs'))).catch(() => null);
+                if (!elevenlabsModule)
+                    throw new Error('Install @ai-sdk/elevenlabs for ElevenLabs support');
+                return elevenlabsModule.elevenlabs.speech(model);
+            }
+            case 'google': {
+                const { google } = await Promise.resolve().then(() => __importStar(require('@ai-sdk/google')));
+                return google.speech?.(model) ?? google(model);
+            }
+            default:
+                throw new Error(`Provider ${this.config.provider} not supported for TTS`);
+        }
+    }
+    /**
+     * Transcribe audio to text (Speech-to-Text)
+     *
+     * @param audioInput - Audio file path, URL, or Buffer
+     * @param options - Transcription options
+     * @returns Transcribed text with metadata
+     *
+     * @example From file
+     * ```typescript
+     * const result = await agent.transcribe('./audio.mp3');
+     * console.log(result.text);
+     * ```
+     *
+     * @example From Buffer
+     * ```typescript
+     * const audioBuffer = fs.readFileSync('./audio.mp3');
+     * const result = await agent.transcribe(audioBuffer);
+     * ```
+     */
+    async transcribe(audioInput, options) {
+        const language = options?.language ?? this.config.language;
+        if (this.config.verbose) {
+            console.log(`[AudioAgent] Transcribing with ${this.config.provider}`);
+        }
+        try {
+            // Lazy import AI SDK
+            const { experimental_transcribe: transcribe } = await Promise.resolve().then(() => __importStar(require('ai')));
+            // Convert input to appropriate format
+            const audio = await this.prepareAudioInput(audioInput);
+            // Get provider-specific transcription model
+            const transcriptionModel = await this.getTranscriptionModel();
+            const result = await transcribe({
+                model: transcriptionModel,
+                audio,
+                // language, // If supported by provider
+            });
+            return {
+                text: result.text,
+                language: result.language,
+                duration: result.duration,
+                words: options?.timestamps ? result.words : undefined,
+                segments: options?.segments ? result.segments : undefined,
+            };
+        }
+        catch (error) {
+            if (error.message?.includes('Cannot find module')) {
+                throw new Error(`AI SDK not installed. Run: npm install ai @ai-sdk/${this.config.provider}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Prepare audio input for transcription
+     */
+    async prepareAudioInput(input) {
+        if (typeof input === 'string') {
+            // Check if it's a URL
+            if (input.startsWith('http://') || input.startsWith('https://')) {
+                return { type: 'url', url: input };
+            }
+            // Assume it's a file path - load with fs
+            const fs = await Promise.resolve().then(() => __importStar(require('fs'))).catch(() => null);
+            if (!fs) {
+                throw new Error('File loading requires Node.js fs module');
+            }
+            const buffer = fs.readFileSync(input);
+            return { type: 'buffer', data: buffer };
+        }
+        // Already a buffer
+        return { type: 'buffer', data: input };
+    }
+    /**
+     * Get provider-specific transcription model
+     */
+    async getTranscriptionModel() {
+        switch (this.config.provider) {
+            case 'openai': {
+                const { openai } = await Promise.resolve().then(() => __importStar(require('@ai-sdk/openai')));
+                return openai.transcription('whisper-1');
+            }
+            case 'groq': {
+                // @ts-ignore - optional dependency
+                const groqModule = await Promise.resolve().then(() => __importStar(require('@ai-sdk/groq'))).catch(() => null);
+                if (!groqModule)
+                    throw new Error('Install @ai-sdk/groq for Groq support');
+                return groqModule.groq.transcription?.('whisper-large-v3') ?? groqModule.groq('whisper-large-v3');
+            }
+            case 'deepgram': {
+                // @ts-ignore - optional dependency
+                const deepgramModule = await Promise.resolve().then(() => __importStar(require('@ai-sdk/deepgram'))).catch(() => null);
+                if (!deepgramModule)
+                    throw new Error('Install @ai-sdk/deepgram for Deepgram support');
+                return deepgramModule.deepgram.transcription?.('nova-2') ?? deepgramModule.deepgram('nova-2');
+            }
+            default:
+                throw new Error(`Provider ${this.config.provider} not supported for transcription`);
+        }
+    }
+    /**
+     * Chat method for agent-like interface
+     * Determines whether to speak or transcribe based on input
+     */
+    async chat(input) {
+        // If input looks like a file path, transcribe it
+        if (input.endsWith('.mp3') || input.endsWith('.wav') ||
+            input.endsWith('.m4a') || input.endsWith('.ogg') ||
+            input.startsWith('http')) {
+            const result = await this.transcribe(input);
+            return result.text;
+        }
+        // Otherwise, speak the text and return info
+        const result = await this.speak(input);
+        return `[Audio generated: ${result.format}, ${result.audio.byteLength} bytes]`;
+    }
+}
+exports.AudioAgent = AudioAgent;
+/**
+ * Factory function to create AudioAgent
+ */
+function createAudioAgent(config) {
+    return new AudioAgent(config);
+}
+// Default export
+exports.default = AudioAgent;

package/dist/agent/index.d.ts

@@ -9,6 +9,8 @@
  */
 export { Agent, PraisonAIAgents, Agents } from './simple';
 export type { SimpleAgentConfig, PraisonAIAgentsConfig } from './simple';
+export { AudioAgent, createAudioAgent } from './audio';
+export type { AudioAgentConfig, SpeakOptions, TranscribeOptions, SpeakResult, TranscribeResult, AudioProvider } from './audio';
 export { Router, RouterAgent, createRouter, routeConditions } from './router';
 export type { RouterConfig, RouteConfig, RouteContext, SimpleRouterConfig, SimpleRouteConfig } from './router';
 export { Task } from './types';

package/dist/agent/index.js

@@ -9,13 +9,17 @@
  * - Workflow: Step-based workflow execution (from workflows module)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Task = exports.routeConditions = exports.createRouter = exports.RouterAgent = exports.Router = exports.Agents = exports.PraisonAIAgents = exports.Agent = void 0;
+exports.Task = exports.routeConditions = exports.createRouter = exports.RouterAgent = exports.Router = exports.createAudioAgent = exports.AudioAgent = exports.Agents = exports.PraisonAIAgents = exports.Agent = void 0;
 exports.setTaskMode = setTaskMode;
 // Core exports - the main API surface
 var simple_1 = require("./simple");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return simple_1.Agent; } });
 Object.defineProperty(exports, "PraisonAIAgents", { enumerable: true, get: function () { return simple_1.PraisonAIAgents; } });
 Object.defineProperty(exports, "Agents", { enumerable: true, get: function () { return simple_1.Agents; } });
+// AudioAgent - Speech synthesis and transcription
+var audio_1 = require("./audio");
+Object.defineProperty(exports, "AudioAgent", { enumerable: true, get: function () { return audio_1.AudioAgent; } });
+Object.defineProperty(exports, "createAudioAgent", { enumerable: true, get: function () { return audio_1.createAudioAgent; } });
 // Router exports
 var router_1 = require("./router");
 Object.defineProperty(exports, "Router", { enumerable: true, get: function () { return router_1.Router; } });

package/dist/ai/agent-loop.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Agent Loop - Manual Agent Loop Control
+ *
+ * Provides utilities for manual control of agent execution loops.
+ */
+import type { Message } from './types';
+export interface AgentLoopConfig {
+    /** Model to use */
+    model: string;
+    /** System prompt */
+    system?: string;
+    /** Available tools */
+    tools?: Record<string, AgentTool>;
+    /** Maximum steps (default: 10) */
+    maxSteps?: number;
+    /** Stop condition */
+    stopWhen?: StopCondition;
+    /** On step finish callback */
+    onStepFinish?: (step: AgentStep) => void | Promise<void>;
+    /** On tool call callback (for approval) */
+    onToolCall?: (toolCall: ToolCallInfo) => Promise<boolean>;
+}
+export interface AgentTool {
+    description: string;
+    parameters: any;
+    execute: (args: any) => Promise<any>;
+}
+export interface AgentStep {
+    stepNumber: number;
+    text: string;
+    toolCalls: ToolCallInfo[];
+    toolResults: ToolResultInfo[];
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string;
+}
+export interface ToolCallInfo {
+    toolCallId: string;
+    toolName: string;
+    args: any;
+}
+export interface ToolResultInfo {
+    toolCallId: string;
+    toolName: string;
+    result: any;
+    isError?: boolean;
+}
+export type StopCondition = {
+    type: 'stepCount';
+    count: number;
+} | {
+    type: 'noToolCalls';
+} | {
+    type: 'custom';
+    check: (step: AgentStep) => boolean;
+};
+export interface AgentLoopResult {
+    text: string;
+    steps: AgentStep[];
+    totalUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string;
+}
+/**
+ * Create a manual agent loop for fine-grained control.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const loop = createAgentLoop({
+ *   model: 'gpt-4o',
+ *   system: 'You are a helpful assistant',
+ *   tools: {
+ *     search: {
+ *       description: 'Search the web',
+ *       parameters: z.object({ query: z.string() }),
+ *       execute: async ({ query }) => searchWeb(query)
+ *     }
+ *   },
+ *   maxSteps: 5
+ * });
+ *
+ * const result = await loop.run('Find information about AI');
+ * ```
+ *
+ * @example With approval
+ * ```typescript
+ * const loop = createAgentLoop({
+ *   model: 'gpt-4o',
+ *   tools: { ... },
+ *   onToolCall: async (toolCall) => {
+ *     const approved = await askUserForApproval(toolCall);
+ *     return approved;
+ *   }
+ * });
+ * ```
+ *
+ * @example Step-by-step control
+ * ```typescript
+ * const loop = createAgentLoop({ model: 'gpt-4o', tools: { ... } });
+ *
+ * // Initialize with a prompt
+ * loop.addMessage({ role: 'user', content: 'Hello' });
+ *
+ * // Run one step at a time
+ * while (!loop.isComplete()) {
+ *   const step = await loop.step();
+ *   console.log('Step:', step);
+ *
+ *   // Optionally modify messages or tools between steps
+ *   if (needsMoreContext) {
+ *     loop.addMessage({ role: 'user', content: 'Additional context...' });
+ *   }
+ * }
+ *
+ * const result = loop.getResult();
+ * ```
+ */
+export declare function createAgentLoop(config: AgentLoopConfig): AgentLoop;
+export declare class AgentLoop {
+    private config;
+    private messages;
+    private steps;
+    private currentStep;
+    private complete;
+    private totalUsage;
+    constructor(config: AgentLoopConfig);
+    /**
+     * Add a message to the conversation.
+     */
+    addMessage(message: Message): void;
+    /**
+     * Get all messages in the conversation.
+     */
+    getMessages(): Message[];
+    /**
+     * Check if the loop is complete.
+     */
+    isComplete(): boolean;
+    /**
+     * Run a single step of the agent loop.
+     */
+    step(): Promise<AgentStep>;
+    /**
+     * Run the full agent loop until completion.
+     */
+    run(prompt: string): Promise<AgentLoopResult>;
+    /**
+     * Get the final result.
+     */
+    getResult(): AgentLoopResult;
+    /**
+     * Check if the loop should stop.
+     */
+    private shouldStop;
+    /**
+     * Reset the agent loop.
+     */
+    reset(): void;
+}
+/**
+ * Create a stop condition that stops after N steps.
+ */
+export declare function stopAfterSteps(count: number): StopCondition;
+/**
+ * Create a stop condition that stops when no tool calls are made.
+ */
+export declare function stopWhenNoToolCalls(): StopCondition;
+/**
+ * Create a custom stop condition.
+ */
+export declare function stopWhen(check: (step: AgentStep) => boolean): StopCondition;