@robota-sdk/agent-core 3.0.0-beta.1

package/dist/abstracts/abstract-ai-provider.d.ts

@@ -0,0 +1,187 @@
+/**
+ * @fileoverview Abstract AI Provider Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT DEPEND ON CONCRETE IMPLEMENTATIONS
+ *
+ * Defines the shared contract and helper utilities for all AI provider implementations.
+ * Concrete providers should extend this class and inject their own dependencies.
+ */
+import type { IAIProvider, IToolSchema, IChatOptions, IProviderRequest, IRawProviderResponse } from '../interfaces/provider';
+import type { IExecutor } from '../interfaces/executor';
+import type { TUniversalMessage } from '../interfaces/messages';
+import type { ILogger } from '../utils/logger';
+/**
+ * Provider logging data type
+ * Used for storing logging information in provider operations
+ */
+export type TProviderLoggingData = Record<string, string | number | boolean | Date | string[]>;
+/**
+ * Provider configuration base interface
+ */
+export interface IProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Enhanced provider configuration that supports executor injection
+ */
+export interface IExecutorAwareProviderConfig {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+    /**
+     * Optional executor for handling AI requests
+     * When provided, the provider will delegate all chat operations to this executor
+     * instead of making direct API calls. This enables remote execution capabilities.
+     */
+    executor?: IExecutor;
+    [key: string]: string | number | boolean | IExecutor | undefined;
+}
+/**
+ * Base AI provider implementation with proper type constraints
+ * All AI providers should extend this class
+ *
+ * ========================================
+ * CRITICAL IMPLEMENTATION GUIDELINES
+ * ========================================
+ *
+ * ALL AI PROVIDER IMPLEMENTATIONS (OpenAI, Anthropic, Google, etc.) MUST:
+ *
+ * 1. EXTEND THIS CLASS:
+ *    ```typescript
+ *    export class OpenAIProvider extends AbstractAIProvider {
+ *        override readonly name = 'openai';
+ *        override readonly version = '1.0.0';
+ *    ```
+ *
+ * 2. USE IMPORTS FROM @robota-sdk/agents:
+ *    ```typescript
+ *    import { AbstractAIProvider } from '@robota-sdk/agents';
+ *    import type {
+ *        TUniversalMessage,
+ *        ChatOptions,
+ *        IToolCall,
+ *        ToolSchema,
+ *        AssistantMessage
+ *    } from '@robota-sdk/agents';
+ *    ```
+ *
+ * 3. USE OVERRIDE KEYWORD FOR ALL INHERITED METHODS:
+ *    - override async chat(...)
+ *    - override async *chatStream(...)
+ *    - override supportsTools()
+ *    - override validateConfig()
+ *    - override async dispose()
+ *
+ * 4. DO NOT REDEFINE TYPES THAT EXIST IN @robota-sdk/agents:
+ *    - TUniversalMessage
+ *    - ChatOptions
+ *    - IToolCall
+ *    - ToolSchema
+ *    - AssistantMessage
+ *    - SystemMessage
+ *    - UserMessage
+ *    - ToolMessage
+ *
+ * 5. HANDLE MESSAGE CONTENT PROPERLY:
+ *    - For tool calls: content should be null (not empty string)
+ *    - For regular messages: content can be string or null
+ *    - Always preserve null values from API responses
+ *
+ * 6. CALL SUPER() IN CONSTRUCTOR:
+ *    ```typescript
+ *    constructor(options: IProviderOptions) {
+ *        super();
+ *        // provider-specific initialization
+ *    }
+ *    ```
+ *
+ * This ensures ExecutionService can properly identify providers
+ * and prevents type conflicts across the codebase.
+ *
+ * ========================================
+ *
+ * @template TConfig - Provider configuration type (defaults to IProviderConfig for type safety)
+ * @template TUniversalMessage - Message type (defaults to TUniversalMessage for backward compatibility)
+ * @template TResponse - Response type (defaults to TUniversalMessage for backward compatibility)
+ */
+export declare abstract class AbstractAIProvider<TConfig = IProviderConfig> implements IAIProvider {
+    abstract readonly name: string;
+    abstract readonly version: string;
+    protected config?: TConfig;
+    protected executor?: IExecutor;
+    protected readonly logger: ILogger;
+    constructor(logger?: ILogger);
+    /**
+ * Configure the provider with type-safe configuration
+ */
+    configure(config: TConfig): Promise<void>;
+    /**
+     * Each provider must implement chat using their own native SDK types internally
+     * @param messages - Array of messages from conversation history
+     * @param options - Chat options including tools, model settings, etc.
+     * @returns Promise resolving to a response
+     */
+    abstract chat(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+    /**
+     * Each provider must implement streaming chat using their own native SDK types internally
+     * @param messages - Array of messages from conversation history
+     * @param options - Chat options including tools, model settings, etc.
+     * @returns AsyncIterable of response chunks
+     */
+    abstract chatStream?(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
+    /**
+     * Provider-agnostic raw response API.
+     *
+     * This is the canonical "raw payload" entrypoint required by the AIProvider contract.
+     * The default implementation delegates to `chat()` and adapts the result into a
+     * RawProviderResponse shape.
+     */
+    generateResponse(payload: IProviderRequest): Promise<IRawProviderResponse>;
+    /**
+     * Provider-agnostic raw streaming API.
+     *
+     * If a provider does not implement chatStream, it does not support streaming.
+     */
+    generateStreamingResponse(payload: IProviderRequest): AsyncIterable<IRawProviderResponse>;
+    /**
+     * Default implementation - most modern providers support tools
+     * @returns true if tool calling is supported
+     */
+    supportsTools(): boolean;
+    /**
+     * Default implementation - providers can override for specific validation
+     * @returns true if configuration is valid
+     */
+    validateConfig(): boolean;
+    /**
+     * Utility method for validating TUniversalMessage array
+     * @param messages - Messages to validate
+     */
+    protected validateMessages(messages: TUniversalMessage[]): void;
+    /**
+     * Utility method for validating tool schemas
+     * @param tools - Tool schemas to validate
+     */
+    protected validateTools(tools?: IToolSchema[]): void;
+    /**
+     * Execute chat via executor.
+     *
+     * Subclasses should call this only when an executor is configured.
+     */
+    protected executeViaExecutorOrDirect(messages: TUniversalMessage[], options?: IChatOptions): Promise<TUniversalMessage>;
+    /**
+     * Execute streaming chat via executor.
+     *
+     * Subclasses should call this only when an executor is configured.
+     */
+    protected executeStreamViaExecutorOrDirect(messages: TUniversalMessage[], options?: IChatOptions): AsyncIterable<TUniversalMessage>;
+    /**
+     * Clean up resources when provider is no longer needed
+     * Override this method in subclasses for additional cleanup
+     */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=abstract-ai-provider.d.ts.map

package/dist/abstracts/abstract-ai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-ai-provider.d.ts","sourceRoot":"","sources":["../../src/abstracts/abstract-ai-provider.ts"],"names":[],"mappings":"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"}

package/dist/abstracts/abstract-ai-provider.js

@@ -0,0 +1,252 @@
+import { isAssistantMessage } from '../interfaces/messages';
+import { SilentLogger } from '../utils/logger';
+/**
+ * Base AI provider implementation with proper type constraints
+ * All AI providers should extend this class
+ *
+ * ========================================
+ * CRITICAL IMPLEMENTATION GUIDELINES
+ * ========================================
+ *
+ * ALL AI PROVIDER IMPLEMENTATIONS (OpenAI, Anthropic, Google, etc.) MUST:
+ *
+ * 1. EXTEND THIS CLASS:
+ *    ```typescript
+ *    export class OpenAIProvider extends AbstractAIProvider {
+ *        override readonly name = 'openai';
+ *        override readonly version = '1.0.0';
+ *    ```
+ *
+ * 2. USE IMPORTS FROM @robota-sdk/agents:
+ *    ```typescript
+ *    import { AbstractAIProvider } from '@robota-sdk/agents';
+ *    import type {
+ *        TUniversalMessage,
+ *        ChatOptions,
+ *        IToolCall,
+ *        ToolSchema,
+ *        AssistantMessage
+ *    } from '@robota-sdk/agents';
+ *    ```
+ *
+ * 3. USE OVERRIDE KEYWORD FOR ALL INHERITED METHODS:
+ *    - override async chat(...)
+ *    - override async *chatStream(...)
+ *    - override supportsTools()
+ *    - override validateConfig()
+ *    - override async dispose()
+ *
+ * 4. DO NOT REDEFINE TYPES THAT EXIST IN @robota-sdk/agents:
+ *    - TUniversalMessage
+ *    - ChatOptions
+ *    - IToolCall
+ *    - ToolSchema
+ *    - AssistantMessage
+ *    - SystemMessage
+ *    - UserMessage
+ *    - ToolMessage
+ *
+ * 5. HANDLE MESSAGE CONTENT PROPERLY:
+ *    - For tool calls: content should be null (not empty string)
+ *    - For regular messages: content can be string or null
+ *    - Always preserve null values from API responses
+ *
+ * 6. CALL SUPER() IN CONSTRUCTOR:
+ *    ```typescript
+ *    constructor(options: IProviderOptions) {
+ *        super();
+ *        // provider-specific initialization
+ *    }
+ *    ```
+ *
+ * This ensures ExecutionService can properly identify providers
+ * and prevents type conflicts across the codebase.
+ *
+ * ========================================
+ *
+ * @template TConfig - Provider configuration type (defaults to IProviderConfig for type safety)
+ * @template TUniversalMessage - Message type (defaults to TUniversalMessage for backward compatibility)
+ * @template TResponse - Response type (defaults to TUniversalMessage for backward compatibility)
+ */
+export class AbstractAIProvider {
+    config;
+    executor;
+    logger;
+    constructor(logger = SilentLogger) {
+        this.logger = logger;
+    }
+    /**
+ * Configure the provider with type-safe configuration
+ */
+    async configure(config) {
+        this.config = config;
+        // Check if config includes executor and set it
+        if (config && typeof config === 'object' && 'executor' in config && config.executor) {
+            this.executor = config.executor;
+        }
+        // Subclasses can override for additional setup
+    }
+    /**
+     * Provider-agnostic raw response API.
+     *
+     * This is the canonical "raw payload" entrypoint required by the AIProvider contract.
+     * The default implementation delegates to `chat()` and adapts the result into a
+     * RawProviderResponse shape.
+     */
+    async generateResponse(payload) {
+        const response = await this.chat(payload.messages, {
+            ...(payload.model !== undefined && { model: payload.model }),
+            ...(payload.temperature !== undefined && { temperature: payload.temperature }),
+            ...(payload.maxTokens !== undefined && { maxTokens: payload.maxTokens }),
+            ...(payload.tools !== undefined && { tools: payload.tools })
+        });
+        return {
+            content: response.content ?? null,
+            toolCalls: isAssistantMessage(response) ? response.toolCalls : undefined,
+            model: payload.model,
+            metadata: payload.metadata
+        };
+    }
+    /**
+     * Provider-agnostic raw streaming API.
+     *
+     * If a provider does not implement chatStream, it does not support streaming.
+     */
+    async *generateStreamingResponse(payload) {
+        if (!this.chatStream) {
+            throw new Error(`[AI-PROVIDER] Streaming is not supported by provider "${this.name}"`);
+        }
+        for await (const chunk of this.chatStream(payload.messages, {
+            ...(payload.model !== undefined && { model: payload.model }),
+            ...(payload.temperature !== undefined && { temperature: payload.temperature }),
+            ...(payload.maxTokens !== undefined && { maxTokens: payload.maxTokens }),
+            ...(payload.tools !== undefined && { tools: payload.tools })
+        })) {
+            yield {
+                content: chunk.content ?? null,
+                toolCalls: isAssistantMessage(chunk) ? chunk.toolCalls : undefined,
+                model: payload.model,
+                metadata: payload.metadata
+            };
+        }
+    }
+    /**
+     * Default implementation - most modern providers support tools
+     * @returns true if tool calling is supported
+     */
+    supportsTools() {
+        return true;
+    }
+    /**
+     * Default implementation - providers can override for specific validation
+     * @returns true if configuration is valid
+     */
+    validateConfig() {
+        return true;
+    }
+    /**
+     * Utility method for validating TUniversalMessage array
+     * @param messages - Messages to validate
+     */
+    validateMessages(messages) {
+        if (!Array.isArray(messages)) {
+            throw new Error('Messages must be an array');
+        }
+        if (messages.length === 0) {
+            throw new Error('Messages array cannot be empty');
+        }
+        for (const message of messages) {
+            if (!message.role || !['user', 'assistant', 'system', 'tool'].includes(message.role)) {
+                throw new Error(`Invalid message role: ${message.role}`);
+            }
+        }
+    }
+    /**
+     * Utility method for validating tool schemas
+     * @param tools - Tool schemas to validate
+     */
+    validateTools(tools) {
+        if (!tools)
+            return;
+        if (!Array.isArray(tools)) {
+            throw new Error('Tools must be an array');
+        }
+        for (const tool of tools) {
+            if (!tool.name || typeof tool.name !== 'string') {
+                throw new Error('Tool must have a valid name');
+            }
+            if (!tool.description || typeof tool.description !== 'string') {
+                throw new Error('Tool must have a valid description');
+            }
+            if (!tool.parameters || typeof tool.parameters !== 'object' || tool.parameters === null || Array.isArray(tool.parameters)) {
+                throw new Error('Tool must have valid parameters');
+            }
+        }
+    }
+    /**
+     * Execute chat via executor.
+     *
+     * Subclasses should call this only when an executor is configured.
+     */
+    async executeViaExecutorOrDirect(messages, options) {
+        if (!this.executor) {
+            throw new Error(`Executor is required for ${this.name} provider. Configure an executor or use direct execution path.`);
+        }
+        if (!options?.model) {
+            throw new Error(`Model is required for executor execution in ${this.name} provider.`);
+        }
+        const result = await this.executor.executeChat({
+            messages,
+            options,
+            provider: this.name,
+            model: options.model,
+            ...(options.tools && { tools: options.tools })
+        });
+        return result;
+    }
+    /**
+     * Execute streaming chat via executor.
+     *
+     * Subclasses should call this only when an executor is configured.
+     */
+    async *executeStreamViaExecutorOrDirect(messages, options) {
+        if (!this.executor || !this.executor.executeChatStream) {
+            throw new Error(`Streaming executor is required for ${this.name} provider.`);
+        }
+        if (!options?.model) {
+            throw new Error(`Model is required for executor streaming in ${this.name} provider.`);
+        }
+        // 🔍 [TOOL-FLOW] AbstractAIProvider.executeStreamViaExecutorOrDirect() - Preparing executor request
+        this.logger.debug?.('🔍 [TOOL-FLOW] AbstractAIProvider.executeStreamViaExecutorOrDirect() - Executor request', {
+            provider: this.name,
+            model: options.model,
+            hasTools: !!options.tools,
+            toolsCount: options.tools?.length || 0,
+            toolNames: options.tools?.map((t) => t.name) || []
+        });
+        const stream = this.executor.executeChatStream({
+            messages,
+            options,
+            provider: this.name,
+            model: options.model,
+            stream: true,
+            ...(options.tools && { tools: options.tools })
+        });
+        for await (const chunk of stream) {
+            yield chunk;
+        }
+        return;
+    }
+    /**
+     * Clean up resources when provider is no longer needed
+     * Override this method in subclasses for additional cleanup
+     */
+    async dispose() {
+        // Clean up executor if present
+        if (this.executor?.dispose) {
+            await this.executor.dispose();
+        }
+        // Subclasses can override for additional cleanup
+    }
+}
+//# sourceMappingURL=abstract-ai-provider.js.map

package/dist/abstracts/abstract-ai-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-ai-provider.js","sourceRoot":"","sources":["../../src/abstracts/abstract-ai-provider.ts"],"names":[],"mappings":"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"}

package/dist/abstracts/abstract-executor.d.ts

@@ -0,0 +1,110 @@
+import type { IExecutor, IChatExecutionRequest, IStreamExecutionRequest } from '../interfaces/executor';
+import type { TUniversalMessage, IAssistantMessage } from '../interfaces/messages';
+import type { TLoggerData } from '../interfaces/types';
+import type { ILogger } from '../utils/logger';
+/**
+ * @fileoverview Abstract Executor Base Class
+ *
+ * 🎯 ABSTRACT CLASS - DO NOT DEPEND ON CONCRETE IMPLEMENTATIONS
+ *
+ * Provides shared execution helpers (retry, timeout, validation, logging) for all
+ * executor implementations. Concrete executors should extend this class and inject
+ * their own logger implementation if they need custom logging behavior.
+ *
+ * @example
+ * ```typescript
+ * export class MyCustomExecutor extends AbstractExecutor {
+ *   async executeChat(request: IChatExecutionRequest): Promise<AssistantMessage> {
+ *     return this.withRetry(() => this.performChat(request));
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class AbstractExecutor implements IExecutor {
+    /**
+     * Logger injected via constructor (defaults to abstract logger)
+     */
+    protected readonly logger: ILogger;
+    constructor(logger?: ILogger);
+    abstract readonly name: string;
+    abstract readonly version: string;
+    /**
+     * Execute a chat completion request
+     * Must be implemented by concrete executor classes
+     */
+    abstract executeChat(request: IChatExecutionRequest): Promise<IAssistantMessage>;
+    /**
+     * Execute a streaming chat completion request
+     * Optional - can be implemented by concrete executor classes
+     */
+    abstract executeChatStream?(request: IStreamExecutionRequest): AsyncIterable<TUniversalMessage>;
+    /**
+     * Check if the executor supports tool calling
+     * Default implementation returns false, can be overridden
+     */
+    supportsTools(): boolean;
+    /**
+     * Validate executor configuration
+     * Default implementation returns true, can be overridden
+     */
+    validateConfig(): boolean;
+    /**
+     * Clean up resources when executor is no longer needed
+     * Default implementation does nothing, can be overridden
+     */
+    dispose?(): Promise<void>;
+    /**
+     * Execute function with retry logic
+     *
+     * @param fn - Function to execute with retries
+     * @param maxRetries - Maximum number of retry attempts (default: 3)
+     * @param retryDelay - Delay between retries in milliseconds (default: 1000)
+     * @returns Promise resolving to function result
+     */
+    protected withRetry<T>(fn: () => Promise<T>, maxRetries?: number, retryDelay?: number): Promise<T>;
+    /**
+     * Execute function with timeout
+     *
+     * @param promise - Promise to execute with timeout
+     * @param timeoutMs - Timeout in milliseconds
+     * @returns Promise resolving to function result
+     */
+    protected withTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T>;
+    /**
+     * Delay execution for specified milliseconds
+     *
+     * @param ms - Milliseconds to delay
+     * @returns Promise that resolves after the delay
+     */
+    protected delay(ms: number): Promise<void>;
+    /**
+     * Log debug information (only if logging is enabled)
+     *
+     * @param message - Log message
+     * @param data - Optional data to log
+     */
+    protected logDebug(message: string, data?: TLoggerData): void;
+    /**
+     * Log error information
+     *
+     * @param message - Log message
+     * @param error - Error object
+     * @param data - Optional additional data
+     */
+    protected logError(message: string, error: Error, data?: TLoggerData): void;
+    /**
+     * Validate that request has required fields
+     *
+     * @param request - Chat execution request to validate
+     * @throws Error if validation fails
+     */
+    protected validateRequest(request: IChatExecutionRequest): void;
+    /**
+     * Validate that response is properly formatted
+     *
+     * @param response - Response to validate
+     * @throws Error if validation fails
+     */
+    protected validateResponse(response: TUniversalMessage): void;
+}
+//# sourceMappingURL=abstract-executor.d.ts.map

package/dist/abstracts/abstract-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-executor.d.ts","sourceRoot":"","sources":["../../src/abstracts/abstract-executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,SAAS,EACT,qBAAqB,EACrB,uBAAuB,EAC1B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C;;;;;;;;;;;;;;;;;GAiBG;AACH,8BAAsB,gBAAiB,YAAW,SAAS;IACvD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAEvB,MAAM,GAAE,OAAsB;IAI1C,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAEhF;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE,uBAAuB,GAAG,aAAa,CAAC,iBAAiB,CAAC;IAE/F;;;OAGG;IACH,aAAa,IAAI,OAAO;IAIxB;;;OAGG;IACH,cAAc,IAAI,OAAO;IAIzB;;;OAGG;IACG,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;;;;;;OAOG;cACa,SAAS,CAAC,CAAC,EACvB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,UAAU,GAAE,MAAU,EACtB,UAAU,GAAE,MAAa,GAC1B,OAAO,CAAC,CAAC,CAAC;IAuBb;;;;;;OAMG;cACa,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAUlF;;;;;OAKG;IACH,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI;IAI7D;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI;IAQ3E;;;;;OAKG;IACH,SAAS,CAAC,eAAe,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAc/D;;;;;OAKG;IACH,SAAS,CAAC,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI;CAShE"}