@marktoflow/integrations 2.0.2 → 2.0.4-alpha.1

package/dist/adapters/openai-types.d.ts

@@ -0,0 +1,713 @@
+/**
+ * Type definitions for OpenAI SDK integration with marktoflow
+ *
+ * These types enable integration with OpenAI-compatible APIs including
+ * OpenAI, VLLM, llama.cpp, and other local/remote endpoints.
+ * Includes full tool calling and structured output support.
+ */
+import { z } from 'zod';
+/**
+ * Configuration for OpenAI client
+ */
+export interface OpenAIClientConfig {
+    /** Base URL for the API (default: https://api.openai.com/v1) */
+    baseUrl?: string;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Default model to use */
+    model?: string;
+    /** Organization ID */
+    organization?: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+/**
+ * Function definition for tool calling
+ */
+export interface OpenAIToolFunction {
+    /** The name of the function */
+    name: string;
+    /** A description of what the function does */
+    description?: string;
+    /** JSON Schema for the function parameters */
+    parameters?: Record<string, unknown>;
+    /** Whether to enforce strict schema validation */
+    strict?: boolean;
+}
+/**
+ * Tool definition
+ */
+export interface OpenAITool {
+    /** The type of tool (currently only 'function') */
+    type: 'function';
+    /** The function definition */
+    function: OpenAIToolFunction;
+}
+/**
+ * A tool call requested by the model
+ */
+export interface OpenAIToolCall {
+    /** Unique identifier for this tool call */
+    id: string;
+    /** The type of tool call */
+    type: 'function';
+    /** The function to call */
+    function: {
+        /** The name of the function to call */
+        name: string;
+        /** JSON-encoded arguments for the function */
+        arguments: string;
+    };
+}
+/**
+ * Tool choice configuration
+ */
+export type OpenAIToolChoice = 'auto' | 'none' | 'required' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+/**
+ * Response format configuration
+ */
+export type OpenAIResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    json_schema: {
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+};
+/**
+ * Chat message format — supports all message roles including tool messages
+ */
+export type OpenAIChatMessage = {
+    role: 'system';
+    content: string;
+    name?: string;
+} | {
+    role: 'user';
+    content: string | OpenAIContentPart[];
+    name?: string;
+} | {
+    role: 'assistant';
+    content: string | null;
+    name?: string;
+    tool_calls?: OpenAIToolCall[];
+} | {
+    role: 'tool';
+    content: string;
+    tool_call_id: string;
+};
+/**
+ * Content part for multimodal messages
+ */
+export type OpenAIContentPart = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+};
+/**
+ * Options for chat completion
+ */
+export interface OpenAIChatOptions {
+    /** Model to use */
+    model?: string;
+    /** Messages for the conversation */
+    messages: OpenAIChatMessage[];
+    /** Sampling temperature (0-2) */
+    temperature?: number;
+    /** Max tokens to generate */
+    max_tokens?: number;
+    /** Top-p sampling */
+    top_p?: number;
+    /** Number of completions to generate */
+    n?: number;
+    /** Stop sequences */
+    stop?: string | string[];
+    /** Frequency penalty (-2 to 2) */
+    frequency_penalty?: number;
+    /** Presence penalty (-2 to 2) */
+    presence_penalty?: number;
+    /** Tools available for the model to call */
+    tools?: OpenAITool[];
+    /** Controls which tool the model calls */
+    tool_choice?: OpenAIToolChoice;
+    /** Response format (text, json_object, or json_schema) */
+    response_format?: OpenAIResponseFormat;
+}
+/**
+ * Chat completion result
+ */
+export interface OpenAIChatResult {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: OpenAIChatChoice[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * A single choice in a chat completion result
+ */
+export interface OpenAIChatChoice {
+    index: number;
+    message: {
+        role: string;
+        content: string | null;
+        tool_calls?: OpenAIToolCall[];
+    };
+    finish_reason: string;
+}
+/**
+ * Options for embeddings
+ */
+export interface OpenAIEmbeddingOptions {
+    /** Model to use for embeddings */
+    model?: string;
+    /** Input text(s) to embed */
+    input: string | string[];
+}
+/**
+ * Embedding result
+ */
+export interface OpenAIEmbeddingResult {
+    object: string;
+    data: Array<{
+        object: string;
+        embedding: number[];
+        index: number;
+    }>;
+    model: string;
+    usage: {
+        prompt_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Tool executor function type — called when the model requests a tool call
+ */
+export type OpenAIToolExecutor = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Options for the agentic tool calling loop
+ */
+export interface OpenAIToolLoopOptions extends OpenAIChatOptions {
+    /** Tools are required for the tool loop */
+    tools: OpenAITool[];
+    /** Maximum number of tool-calling turns before stopping */
+    maxTurns?: number;
+    /** Called when a tool call is about to be executed */
+    onToolCall?: (toolCall: OpenAIToolCall) => void;
+    /** Called when a tool call returns a result */
+    onToolResult?: (toolCall: OpenAIToolCall, result: unknown) => void;
+}
+export declare const OpenAIClientConfigSchema: z.ZodObject<{
+    baseUrl: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    organization: z.ZodOptional<z.ZodString>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeout?: number | undefined;
+    apiKey?: string | undefined;
+    baseUrl?: string | undefined;
+    model?: string | undefined;
+    organization?: string | undefined;
+}, {
+    timeout?: number | undefined;
+    apiKey?: string | undefined;
+    baseUrl?: string | undefined;
+    model?: string | undefined;
+    organization?: string | undefined;
+}>;
+export declare const OpenAIToolFunctionSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    strict: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+    strict?: boolean | undefined;
+}, {
+    name: string;
+    description?: string | undefined;
+    parameters?: Record<string, unknown> | undefined;
+    strict?: boolean | undefined;
+}>;
+export declare const OpenAIToolSchema: z.ZodObject<{
+    type: z.ZodLiteral<"function">;
+    function: z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        strict: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+        strict?: boolean | undefined;
+    }, {
+        name: string;
+        description?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+        strict?: boolean | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    function: {
+        name: string;
+        description?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+        strict?: boolean | undefined;
+    };
+    type: "function";
+}, {
+    function: {
+        name: string;
+        description?: string | undefined;
+        parameters?: Record<string, unknown> | undefined;
+        strict?: boolean | undefined;
+    };
+    type: "function";
+}>;
+export declare const OpenAIChatMessageSchema: z.ZodDiscriminatedUnion<"role", [z.ZodObject<{
+    role: z.ZodLiteral<"system">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    role: "system";
+    name?: string | undefined;
+}, {
+    content: string;
+    role: "system";
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"user">;
+    content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnknown, "many">]>;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    content: string | unknown[];
+    role: "user";
+    name?: string | undefined;
+}, {
+    content: string | unknown[];
+    role: "user";
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"assistant">;
+    content: z.ZodNullable<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            arguments: string;
+        }, {
+            name: string;
+            arguments: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }, {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    content: string | null;
+    role: "assistant";
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}, {
+    content: string | null;
+    role: "assistant";
+    name?: string | undefined;
+    tool_calls?: {
+        function: {
+            name: string;
+            arguments: string;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"tool">;
+    content: z.ZodString;
+    tool_call_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    role: "tool";
+    tool_call_id: string;
+}, {
+    content: string;
+    role: "tool";
+    tool_call_id: string;
+}>]>;
+export declare const OpenAIChatOptionsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    messages: z.ZodArray<z.ZodDiscriminatedUnion<"role", [z.ZodObject<{
+        role: z.ZodLiteral<"system">;
+        content: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        role: "system";
+        name?: string | undefined;
+    }, {
+        content: string;
+        role: "system";
+        name?: string | undefined;
+    }>, z.ZodObject<{
+        role: z.ZodLiteral<"user">;
+        content: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodUnknown, "many">]>;
+        name: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        content: string | unknown[];
+        role: "user";
+        name?: string | undefined;
+    }, {
+        content: string | unknown[];
+        role: "user";
+        name?: string | undefined;
+    }>, z.ZodObject<{
+        role: z.ZodLiteral<"assistant">;
+        content: z.ZodNullable<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        tool_calls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodLiteral<"function">;
+            function: z.ZodObject<{
+                name: z.ZodString;
+                arguments: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                name: string;
+                arguments: string;
+            }, {
+                name: string;
+                arguments: string;
+            }>;
+        }, "strip", z.ZodTypeAny, {
+            function: {
+                name: string;
+                arguments: string;
+            };
+            type: "function";
+            id: string;
+        }, {
+            function: {
+                name: string;
+                arguments: string;
+            };
+            type: "function";
+            id: string;
+        }>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        content: string | null;
+        role: "assistant";
+        name?: string | undefined;
+        tool_calls?: {
+            function: {
+                name: string;
+                arguments: string;
+            };
+            type: "function";
+            id: string;
+        }[] | undefined;
+    }, {
+        content: string | null;
+        role: "assistant";
+        name?: string | undefined;
+        tool_calls?: {
+            function: {
+                name: string;
+                arguments: string;
+            };
+            type: "function";
+            id: string;
+        }[] | undefined;
+    }>, z.ZodObject<{
+        role: z.ZodLiteral<"tool">;
+        content: z.ZodString;
+        tool_call_id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        role: "tool";
+        tool_call_id: string;
+    }, {
+        content: string;
+        role: "tool";
+        tool_call_id: string;
+    }>]>, "many">;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    top_p: z.ZodOptional<z.ZodNumber>;
+    n: z.ZodOptional<z.ZodNumber>;
+    stop: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
+    frequency_penalty: z.ZodOptional<z.ZodNumber>;
+    presence_penalty: z.ZodOptional<z.ZodNumber>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            strict: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            description?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+            strict?: boolean | undefined;
+        }, {
+            name: string;
+            description?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+            strict?: boolean | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            description?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+            strict?: boolean | undefined;
+        };
+        type: "function";
+    }, {
+        function: {
+            name: string;
+            description?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+            strict?: boolean | undefined;
+        };
+        type: "function";
+    }>, "many">>;
+    tool_choice: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["auto", "none", "required"]>, z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+        }, {
+            name: string;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+        };
+        type: "function";
+    }, {
+        function: {
+            name: string;
+        };
+        type: "function";
+    }>]>>;
+    response_format: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+    }, "strip", z.ZodTypeAny, {
+        type: "text";
+    }, {
+        type: "text";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"json_object">;
+    }, "strip", z.ZodTypeAny, {
+        type: "json_object";
+    }, {
+        type: "json_object";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"json_schema">;
+        json_schema: z.ZodObject<{
+            name: z.ZodString;
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            strict: z.ZodOptional<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean | undefined;
+        }, {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        type: "json_schema";
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean | undefined;
+        };
+    }, {
+        type: "json_schema";
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean | undefined;
+        };
+    }>]>>;
+}, "strip", z.ZodTypeAny, {
+    messages: ({
+        content: string;
+        role: "system";
+        name?: string | undefined;
+    } | {
+        content: string | unknown[];
+        role: "user";
+        name?: string | undefined;
+    } | {
+        content: string | null;
+        role: "assistant";
+        name?: string | undefined;
+        tool_calls?: {
+            function: {
+                name: string;
+                arguments: string;
+            };
+            type: "function";
+            id: string;
+        }[] | undefined;
+    } | {
+        content: string;
+        role: "tool";
+        tool_call_id: string;
+    })[];
+    model?: string | undefined;
+    tools?: {
+        function: {
+            name: string;
+            description?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+            strict?: boolean | undefined;
+        };
+        type: "function";
+    }[] | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    top_p?: number | undefined;
+    n?: number | undefined;
+    stop?: string | string[] | undefined;
+    frequency_penalty?: number | undefined;
+    presence_penalty?: number | undefined;
+    tool_choice?: "auto" | "required" | "none" | {
+        function: {
+            name: string;
+        };
+        type: "function";
+    } | undefined;
+    response_format?: {
+        type: "text";
+    } | {
+        type: "json_object";
+    } | {
+        type: "json_schema";
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean | undefined;
+        };
+    } | undefined;
+}, {
+    messages: ({
+        content: string;
+        role: "system";
+        name?: string | undefined;
+    } | {
+        content: string | unknown[];
+        role: "user";
+        name?: string | undefined;
+    } | {
+        content: string | null;
+        role: "assistant";
+        name?: string | undefined;
+        tool_calls?: {
+            function: {
+                name: string;
+                arguments: string;
+            };
+            type: "function";
+            id: string;
+        }[] | undefined;
+    } | {
+        content: string;
+        role: "tool";
+        tool_call_id: string;
+    })[];
+    model?: string | undefined;
+    tools?: {
+        function: {
+            name: string;
+            description?: string | undefined;
+            parameters?: Record<string, unknown> | undefined;
+            strict?: boolean | undefined;
+        };
+        type: "function";
+    }[] | undefined;
+    temperature?: number | undefined;
+    max_tokens?: number | undefined;
+    top_p?: number | undefined;
+    n?: number | undefined;
+    stop?: string | string[] | undefined;
+    frequency_penalty?: number | undefined;
+    presence_penalty?: number | undefined;
+    tool_choice?: "auto" | "required" | "none" | {
+        function: {
+            name: string;
+        };
+        type: "function";
+    } | undefined;
+    response_format?: {
+        type: "text";
+    } | {
+        type: "json_object";
+    } | {
+        type: "json_schema";
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean | undefined;
+        };
+    } | undefined;
+}>;
+export declare const OpenAIEmbeddingOptionsSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodString>;
+    input: z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>;
+}, "strip", z.ZodTypeAny, {
+    input: string | string[];
+    model?: string | undefined;
+}, {
+    input: string | string[];
+    model?: string | undefined;
+}>;
+//# sourceMappingURL=openai-types.d.ts.map