praisonai 1.3.5 → 1.4.0

package/dist/ai/agent-loop.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Agent Loop - Manual Agent Loop Control
+ *
+ * Provides utilities for manual control of agent execution loops.
+ */
+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.AgentLoop = void 0;
+exports.createAgentLoop = createAgentLoop;
+exports.stopAfterSteps = stopAfterSteps;
+exports.stopWhenNoToolCalls = stopWhenNoToolCalls;
+exports.stopWhen = stopWhen;
+/**
+ * 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();
+ * ```
+ */
+function createAgentLoop(config) {
+    return new AgentLoop(config);
+}
+class AgentLoop {
+    constructor(config) {
+        this.messages = [];
+        this.steps = [];
+        this.currentStep = 0;
+        this.complete = false;
+        this.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        this.config = {
+            maxSteps: 10,
+            ...config,
+        };
+        // Add system message if provided
+        if (config.system) {
+            this.messages.push({ role: 'system', content: config.system });
+        }
+    }
+    /**
+     * Add a message to the conversation.
+     */
+    addMessage(message) {
+        this.messages.push(message);
+    }
+    /**
+     * Get all messages in the conversation.
+     */
+    getMessages() {
+        return [...this.messages];
+    }
+    /**
+     * Check if the loop is complete.
+     */
+    isComplete() {
+        return this.complete;
+    }
+    /**
+     * Run a single step of the agent loop.
+     */
+    async step() {
+        if (this.complete) {
+            throw new Error('Agent loop is already complete');
+        }
+        this.currentStep++;
+        // Check max steps
+        if (this.currentStep > (this.config.maxSteps || 10)) {
+            this.complete = true;
+            throw new Error(`Maximum steps (${this.config.maxSteps}) reached`);
+        }
+        // Import and call generateText
+        const { generateText } = await Promise.resolve().then(() => __importStar(require('./generate-text')));
+        const result = await generateText({
+            model: this.config.model,
+            messages: this.messages,
+            tools: this.config.tools,
+            maxSteps: 1, // Single step
+        });
+        // Build step result
+        const step = {
+            stepNumber: this.currentStep,
+            text: result.text,
+            toolCalls: result.toolCalls.map(tc => ({
+                toolCallId: tc.toolCallId,
+                toolName: tc.toolName,
+                args: tc.args,
+            })),
+            toolResults: result.toolResults.map(tr => ({
+                toolCallId: tr.toolCallId,
+                toolName: tr.toolName,
+                result: tr.result,
+            })),
+            usage: result.usage,
+            finishReason: result.finishReason,
+        };
+        // Update total usage
+        this.totalUsage.promptTokens += result.usage.promptTokens;
+        this.totalUsage.completionTokens += result.usage.completionTokens;
+        this.totalUsage.totalTokens += result.usage.totalTokens;
+        // Add assistant message
+        if (result.text) {
+            this.messages.push({ role: 'assistant', content: result.text });
+        }
+        // Handle tool calls
+        if (step.toolCalls.length > 0) {
+            // Check for approval if callback provided
+            if (this.config.onToolCall) {
+                for (const toolCall of step.toolCalls) {
+                    const approved = await this.config.onToolCall(toolCall);
+                    if (!approved) {
+                        this.complete = true;
+                        step.finishReason = 'tool_rejected';
+                        break;
+                    }
+                }
+            }
+            // Add tool call message
+            const toolCallParts = step.toolCalls.map(tc => ({
+                type: 'tool-call',
+                toolCallId: tc.toolCallId,
+                toolName: tc.toolName,
+                args: tc.args,
+            }));
+            this.messages.push({ role: 'assistant', content: '', toolCalls: toolCallParts });
+            // Add tool results
+            for (const tr of step.toolResults) {
+                const toolResultPart = {
+                    type: 'tool-result',
+                    toolCallId: tr.toolCallId,
+                    toolName: tr.toolName,
+                    result: tr.result,
+                };
+                this.messages.push({
+                    role: 'tool',
+                    content: [toolResultPart],
+                    toolCallId: tr.toolCallId,
+                });
+            }
+        }
+        // Store step
+        this.steps.push(step);
+        // Call step finish callback
+        if (this.config.onStepFinish) {
+            await this.config.onStepFinish(step);
+        }
+        // Check stop conditions
+        if (this.shouldStop(step)) {
+            this.complete = true;
+        }
+        return step;
+    }
+    /**
+     * Run the full agent loop until completion.
+     */
+    async run(prompt) {
+        // Add user message
+        this.addMessage({ role: 'user', content: prompt });
+        // Run steps until complete
+        while (!this.isComplete()) {
+            try {
+                await this.step();
+            }
+            catch (error) {
+                if (error.message.includes('Maximum steps')) {
+                    break;
+                }
+                throw error;
+            }
+        }
+        return this.getResult();
+    }
+    /**
+     * Get the final result.
+     */
+    getResult() {
+        const lastStep = this.steps[this.steps.length - 1];
+        return {
+            text: lastStep?.text || '',
+            steps: this.steps,
+            totalUsage: this.totalUsage,
+            finishReason: lastStep?.finishReason || 'unknown',
+        };
+    }
+    /**
+     * Check if the loop should stop.
+     */
+    shouldStop(step) {
+        // Check custom stop condition
+        if (this.config.stopWhen) {
+            switch (this.config.stopWhen.type) {
+                case 'stepCount':
+                    return this.currentStep >= this.config.stopWhen.count;
+                case 'noToolCalls':
+                    return step.toolCalls.length === 0;
+                case 'custom':
+                    return this.config.stopWhen.check(step);
+            }
+        }
+        // Default: stop when no tool calls
+        return step.toolCalls.length === 0 && step.finishReason === 'stop';
+    }
+    /**
+     * Reset the agent loop.
+     */
+    reset() {
+        this.messages = [];
+        this.steps = [];
+        this.currentStep = 0;
+        this.complete = false;
+        this.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        if (this.config.system) {
+            this.messages.push({ role: 'system', content: this.config.system });
+        }
+    }
+}
+exports.AgentLoop = AgentLoop;
+/**
+ * Create a stop condition that stops after N steps.
+ */
+function stopAfterSteps(count) {
+    return { type: 'stepCount', count };
+}
+/**
+ * Create a stop condition that stops when no tool calls are made.
+ */
+function stopWhenNoToolCalls() {
+    return { type: 'noToolCalls' };
+}
+/**
+ * Create a custom stop condition.
+ */
+function stopWhen(check) {
+    return { type: 'custom', check };
+}

package/dist/ai/devtools.d.ts

@@ -0,0 +1,74 @@
+/**
+ * DevTools - AI SDK v6 DevTools Integration
+ *
+ * Provides optional DevTools integration for debugging AI SDK calls.
+ * This is an optional dependency that provides visibility into LLM calls.
+ */
+export interface DevToolsConfig {
+    /** Enable DevTools (default: auto-detect from NODE_ENV) */
+    enabled?: boolean;
+    /** DevTools server port (default: 3001) */
+    port?: number;
+    /** DevTools server host (default: localhost) */
+    host?: string;
+    /** Project name for DevTools UI */
+    projectName?: string;
+    /** Custom metadata to include */
+    metadata?: Record<string, unknown>;
+}
+export interface DevToolsState {
+    enabled: boolean;
+    initialized: boolean;
+    port?: number;
+    host?: string;
+}
+/**
+ * Enable AI SDK DevTools for debugging.
+ *
+ * @example
+ * ```typescript
+ * // Enable in development
+ * if (process.env.NODE_ENV === 'development') {
+ *   await enableDevTools();
+ * }
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * await enableDevTools({
+ *   port: 3001,
+ *   projectName: 'My AI App'
+ * });
+ * ```
+ */
+export declare function enableDevTools(config?: DevToolsConfig): Promise<void>;
+/**
+ * Disable DevTools.
+ */
+export declare function disableDevTools(): Promise<void>;
+/**
+ * Check if DevTools is enabled.
+ */
+export declare function isDevToolsEnabled(): boolean;
+/**
+ * Get DevTools state.
+ */
+export declare function getDevToolsState(): DevToolsState;
+/**
+ * Get DevTools URL.
+ */
+export declare function getDevToolsUrl(): string | null;
+/**
+ * Create middleware that logs to DevTools.
+ *
+ * @example
+ * ```typescript
+ * const model = wrapModel(openai('gpt-4o'), createDevToolsMiddleware());
+ * ```
+ */
+export declare function createDevToolsMiddleware(): any;
+/**
+ * Auto-enable DevTools if in development mode.
+ * Call this at app startup.
+ */
+export declare function autoEnableDevTools(): Promise<void>;

package/dist/ai/devtools.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * DevTools - AI SDK v6 DevTools Integration
+ *
+ * Provides optional DevTools integration for debugging AI SDK calls.
+ * This is an optional dependency that provides visibility into LLM calls.
+ */
+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.enableDevTools = enableDevTools;
+exports.disableDevTools = disableDevTools;
+exports.isDevToolsEnabled = isDevToolsEnabled;
+exports.getDevToolsState = getDevToolsState;
+exports.getDevToolsUrl = getDevToolsUrl;
+exports.createDevToolsMiddleware = createDevToolsMiddleware;
+exports.autoEnableDevTools = autoEnableDevTools;
+// ============================================================================
+// Global State
+// ============================================================================
+let devToolsState = {
+    enabled: false,
+    initialized: false,
+};
+let devToolsInstance = null;
+// ============================================================================
+// DevTools Functions
+// ============================================================================
+/**
+ * Enable AI SDK DevTools for debugging.
+ *
+ * @example
+ * ```typescript
+ * // Enable in development
+ * if (process.env.NODE_ENV === 'development') {
+ *   await enableDevTools();
+ * }
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * await enableDevTools({
+ *   port: 3001,
+ *   projectName: 'My AI App'
+ * });
+ * ```
+ */
+async function enableDevTools(config) {
+    if (devToolsState.initialized && devToolsState.enabled) {
+        return; // Already enabled
+    }
+    // Check if we should enable
+    const shouldEnable = config?.enabled ??
+        (process.env.NODE_ENV === 'development' || process.env.PRAISONAI_DEVTOOLS === 'true');
+    if (!shouldEnable) {
+        return;
+    }
+    try {
+        // Try to import @ai-sdk/devtools (optional dependency)
+        // @ts-ignore - Optional dependency
+        const devtools = await Promise.resolve().then(() => __importStar(require('@ai-sdk/devtools')));
+        if ('enableDevTools' in devtools) {
+            await devtools.enableDevTools({
+                port: config?.port,
+                host: config?.host,
+                projectName: config?.projectName,
+                metadata: config?.metadata,
+            });
+            devToolsInstance = devtools;
+            devToolsState = {
+                enabled: true,
+                initialized: true,
+                port: config?.port || 3001,
+                host: config?.host || 'localhost',
+            };
+            console.log(`🔧 AI SDK DevTools enabled at http://${devToolsState.host}:${devToolsState.port}`);
+        }
+    }
+    catch (error) {
+        if (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_FOUND') {
+            console.warn('⚠️  @ai-sdk/devtools not installed. Install with:\n' +
+                '   npm install @ai-sdk/devtools\n' +
+                '   or: pnpm add @ai-sdk/devtools');
+        }
+        else {
+            console.warn('⚠️  Failed to enable DevTools:', error.message);
+        }
+        devToolsState = {
+            enabled: false,
+            initialized: true,
+        };
+    }
+}
+/**
+ * Disable DevTools.
+ */
+async function disableDevTools() {
+    if (!devToolsState.enabled) {
+        return;
+    }
+    try {
+        if (devToolsInstance && typeof devToolsInstance.disableDevTools === 'function') {
+            await devToolsInstance.disableDevTools();
+        }
+    }
+    catch {
+        // Ignore errors during disable
+    }
+    devToolsState = {
+        enabled: false,
+        initialized: true,
+    };
+    devToolsInstance = null;
+}
+/**
+ * Check if DevTools is enabled.
+ */
+function isDevToolsEnabled() {
+    return devToolsState.enabled;
+}
+/**
+ * Get DevTools state.
+ */
+function getDevToolsState() {
+    return { ...devToolsState };
+}
+/**
+ * Get DevTools URL.
+ */
+function getDevToolsUrl() {
+    if (!devToolsState.enabled) {
+        return null;
+    }
+    return `http://${devToolsState.host || 'localhost'}:${devToolsState.port || 3001}`;
+}
+// ============================================================================
+// Middleware for DevTools
+// ============================================================================
+/**
+ * Create middleware that logs to DevTools.
+ *
+ * @example
+ * ```typescript
+ * const model = wrapModel(openai('gpt-4o'), createDevToolsMiddleware());
+ * ```
+ */
+function createDevToolsMiddleware() {
+    return {
+        transformParams: async ({ params }) => {
+            if (!devToolsState.enabled) {
+                return params;
+            }
+            // Add DevTools metadata
+            return {
+                ...params,
+                experimental_telemetry: {
+                    ...params.experimental_telemetry,
+                    isEnabled: true,
+                    metadata: {
+                        ...params.experimental_telemetry?.metadata,
+                        devtools: true,
+                    },
+                },
+            };
+        },
+    };
+}
+// ============================================================================
+// Auto-enable in Development
+// ============================================================================
+/**
+ * Auto-enable DevTools if in development mode.
+ * Call this at app startup.
+ */
+async function autoEnableDevTools() {
+    const isDev = process.env.NODE_ENV === 'development';
+    const isExplicitlyEnabled = process.env.PRAISONAI_DEVTOOLS === 'true';
+    const isExplicitlyDisabled = process.env.PRAISONAI_DEVTOOLS === 'false';
+    if (isExplicitlyDisabled) {
+        return;
+    }
+    if (isDev || isExplicitlyEnabled) {
+        await enableDevTools();
+    }
+}

package/dist/ai/embed.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Embed - AI SDK Wrapper
+ *
+ * Provides embed and embedMany functions for text embeddings.
+ */
+export interface EmbedOptions {
+    /** Model to use (e.g., 'text-embedding-3-small', 'openai/text-embedding-3-large') */
+    model: string;
+    /** Text to embed */
+    value: string;
+    /** Maximum retries */
+    maxRetries?: number;
+    /** Abort signal */
+    abortSignal?: AbortSignal;
+    /** Additional headers */
+    headers?: Record<string, string>;
+}
+export interface EmbedResult {
+    /** Embedding vector */
+    embedding: number[];
+    /** Token usage */
+    usage: {
+        tokens: number;
+    };
+}
+export interface EmbedManyOptions {
+    /** Model to use */
+    model: string;
+    /** Texts to embed */
+    values: string[];
+    /** Maximum retries */
+    maxRetries?: number;
+    /** Abort signal */
+    abortSignal?: AbortSignal;
+    /** Additional headers */
+    headers?: Record<string, string>;
+}
+export interface EmbedManyResult {
+    /** Embedding vectors */
+    embeddings: number[][];
+    /** Token usage */
+    usage: {
+        tokens: number;
+    };
+}
+/**
+ * Embed a single text using an embedding model.
+ *
+ * @example
+ * ```typescript
+ * const result = await embed({
+ *   model: 'text-embedding-3-small',
+ *   value: 'Hello, world!'
+ * });
+ * console.log(result.embedding); // [0.1, 0.2, ...]
+ * ```
+ */
+export declare function embed(options: EmbedOptions): Promise<EmbedResult>;
+/**
+ * Embed multiple texts using an embedding model.
+ *
+ * @example
+ * ```typescript
+ * const result = await embedMany({
+ *   model: 'text-embedding-3-small',
+ *   values: ['Hello', 'World']
+ * });
+ * console.log(result.embeddings); // [[0.1, ...], [0.2, ...]]
+ * ```
+ */
+export declare function embedMany(options: EmbedManyOptions): Promise<EmbedManyResult>;