@robota-sdk/agent-provider-openai 3.0.0-beta.63 → 3.0.0-beta.82

package/src/openai/types.ts

@@ -0,0 +1,235 @@
+import type { IPayloadLogger } from './interfaces/payload-logger';
+import type { IExecutor, ILogger, TProviderOptionValueBase } from '@robota-sdk/agent-core';
+import type OpenAI from 'openai';
+
+export type TOpenAIApiSurface = 'responses' | 'chat-completions';
+
+export interface IOpenAIJsonSchemaDefinition {
+  name: string;
+  description?: string;
+  schema?: Record<string, TOpenAIProviderOptionValue>;
+  strict?: boolean;
+}
+
+export interface IOpenAIResponsesReasoningOptions {
+  effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+  summary?: 'auto' | 'concise' | 'detailed';
+}
+
+export interface IOpenAINativeWebToolsOptions {
+  webSearch?: boolean;
+  webFetch?: boolean;
+}
+
+/**
+ * Valid provider option value types
+ */
+export type TOpenAIProviderOptionValue =
+  | string
+  | number
+  | boolean
+  | undefined
+  | null
+  | IOpenAIJsonSchemaDefinition
+  | IOpenAINativeWebToolsOptions
+  | IOpenAIResponsesReasoningOptions
+  | OpenAI
+  | IPayloadLogger
+  | ILogger
+  | IExecutor
+  | TProviderOptionValueBase
+  | TOpenAIProviderOptionValue[]
+  | { [key: string]: TOpenAIProviderOptionValue };
+
+/**
+ * OpenAI provider options
+ */
+export interface IOpenAIProviderOptions {
+  /**
+   * Additional provider-specific options
+   */
+  [key: string]: TOpenAIProviderOptionValue;
+
+  /**
+   * OpenAI API key (required when client is not provided)
+   */
+  apiKey?: string;
+
+  /**
+   * OpenAI organization ID (optional)
+   */
+  organization?: string;
+
+  /**
+   * API request timeout (milliseconds)
+   */
+  timeout?: number;
+
+  /**
+   * Whether to request token usage on streaming turns via
+   * `stream_options: { include_usage: true }` (default `true`). Set `false` for
+   * OpenAI-compatible endpoints that reject `stream_options`; usage is then absent
+   * on streaming turns for this provider.
+   */
+  includeStreamUsage?: boolean;
+
+  /**
+   * API base URL (default: `'https://api.openai.com/v1'`).
+   *
+   * Point this at ANY OpenAI-compatible endpoint — this provider is a protocol
+   * client, not an OpenAI-vendor lock:
+   *
+   * - AI gateways: Vercel AI Gateway, LiteLLM, OpenRouter, …
+   * - Hosted compatibles: Azure OpenAI, Groq, Together, …
+   * - Local/self-hosted: vLLM, Ollama, LM Studio, …
+   *
+   * Setting `baseURL` switches the default {@link apiSurface} to
+   * `'chat-completions'` for broad endpoint compatibility (official OpenAI calls
+   * default to the Responses API). Model slugs are passed through verbatim, so
+   * gateway-namespaced ids like `anthropic/claude-sonnet-4-5` or
+   * `meta-llama/llama-3.1-70b` work as `defaultModel`/`model` values — streaming
+   * and tool calling ride the same chat-completions protocol.
+   *
+   * @example
+   * ```ts
+   * // Vercel AI Gateway with a non-OpenAI model slug
+   * createOpenAIProvider({
+   *   apiKey: process.env.AI_GATEWAY_API_KEY,
+   *   baseURL: 'https://ai-gateway.vercel.sh/v1',
+   *   defaultModel: 'anthropic/claude-sonnet-4-5',
+   * });
+   * ```
+   */
+  baseURL?: string;
+
+  /**
+   * Default model used when chat options do not provide a model.
+   */
+  defaultModel?: string;
+
+  /**
+   * API surface to use for direct OpenAI calls.
+   *
+   * Defaults to Responses for official OpenAI calls. Profiles with baseURL use
+   * Chat Completions by default for OpenAI-compatible endpoint compatibility.
+   */
+  apiSurface?: TOpenAIApiSurface;
+
+  /**
+   * Response format (default: 'text')
+   * - 'text': Plain text response
+   * - 'json_object': JSON object mode (requires system message)
+   * - 'json_schema': Structured Outputs with schema validation
+   */
+  responseFormat?: 'text' | 'json_object' | 'json_schema';
+
+  /**
+   * JSON schema for structured outputs (required when responseFormat is 'json_schema')
+   */
+  jsonSchema?: IOpenAIJsonSchemaDefinition;
+
+  /**
+   * Responses API reasoning controls. Hidden reasoning is never exposed in message
+   * content; only explicit summaries/encrypted items requested here are represented.
+   */
+  reasoning?: IOpenAIResponsesReasoningOptions;
+
+  /**
+   * Whether OpenAI should store Responses API results. Defaults to OpenAI API behavior.
+   */
+  store?: boolean;
+
+  /**
+   * Include encrypted reasoning items for stateless reasoning continuation.
+   */
+  includeEncryptedReasoning?: boolean;
+
+  /**
+   * Opt into strict custom function parameter validation where supported.
+   *
+   * PROV-007: the tool schema is rewritten for strict mode on the way out — every object node,
+   * nested ones included, is closed and given a complete `required` list. That transformation is
+   * lossy, so it runs ONLY when this flag is on; with it off the schema is forwarded exactly as
+   * authored.
+   *
+   * What "lossy" means for a caller: strict mode has no way to say "optional", so a field the
+   * schema marked optional becomes required and gains a `null` branch. The model must then supply
+   * the key explicitly, with `null` standing for "not provided". A tool whose handler distinguishes
+   * an absent key from a null value will see the difference.
+   */
+  strictTools?: boolean;
+
+  /**
+   * Provider-native hosted web tool request from provider profile options.
+   *
+   * OpenAI-compatible Chat Completions endpoints do not support this Robota
+   * native web contract. The provider rejects unsupported configurations before
+   * any model request is sent.
+   */
+  nativeWebTools?: IOpenAINativeWebToolsOptions;
+
+  /**
+   * OpenAI client instance (optional: will be created from apiKey if not provided)
+   */
+  client?: OpenAI;
+
+  /**
+   * Payload logger instance for debugging API requests/responses
+   *
+   * Use different implementations based on your environment:
+   * - FilePayloadLogger: Node.js file-based logging
+   * - ConsolePayloadLogger: Browser console-based logging
+   * - Custom: Implement IPayloadLogger interface
+   *
+   * @example
+   * ```typescript
+   * // Node.js
+   * import { FilePayloadLogger } from '@robota-sdk/agent-provider-openai/loggers';
+   * const provider = new OpenAIProvider({
+   *   client: openaiClient,
+   *   payloadLogger: new FilePayloadLogger({ logDir: './logs/openai' })
+   * });
+   *
+   * // Browser
+   * import { ConsolePayloadLogger } from '@robota-sdk/agent-provider-openai/loggers';
+   * const provider = new OpenAIProvider({
+   *   client: openaiClient,
+   *   payloadLogger: new ConsolePayloadLogger()
+   * });
+   * ```
+   */
+  payloadLogger?: IPayloadLogger;
+
+  /**
+   * 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.
+   *
+   * @example
+   * ```typescript
+   * import { LocalExecutor, RemoteExecutor } from '@robota-sdk/agent-core';
+   *
+   * // Local execution (registers this provider)
+   * const localExecutor = new LocalExecutor();
+   * localExecutor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
+   *
+   * // Remote execution
+   * const remoteExecutor = new RemoteExecutor({
+   *   serverUrl: 'https://api.robota.io',
+   *   userApiKey: 'user-token-123'
+   * });
+   *
+   * const provider = new OpenAIProvider({
+   *   executor: remoteExecutor // No direct API key needed
+   * });
+   * ```
+   */
+  executor?: IExecutor;
+
+  /**
+   * Logger instance for internal OpenAI provider logging
+   * @defaultValue SilentLogger
+   */
+  logger?: ILogger;
+}