@providerprotocol/ai 0.0.34 → 0.0.36

package/dist/responses/index.d.ts

@@ -0,0 +1,650 @@
+import { d as Provider } from '../llm-ByUFPcFH.js';
+import '../stream-S7nwQRqM.js';
+
+/**
+ * @fileoverview OpenResponses Provider Type Definitions
+ *
+ * This module contains TypeScript type definitions for the OpenResponses provider,
+ * implementing the open-source OpenResponses specification for multi-provider
+ * interoperable LLM interfaces.
+ *
+ * The OpenResponses spec is based on OpenAI's Responses API but designed to be
+ * provider-agnostic, allowing any compatible server to be used.
+ *
+ * @see {@link https://www.openresponses.org OpenResponses Specification}
+ * @module providers/responses/types
+ */
+/**
+ * Configuration options for creating an OpenResponses model reference.
+ *
+ * The `host` option allows targeting any OpenResponses-compatible server,
+ * making this provider work with OpenAI, self-hosted servers, or any
+ * implementation of the OpenResponses specification.
+ *
+ * @example Using with OpenAI
+ * ```typescript
+ * const model = responses('gpt-5.2', {
+ *   host: 'https://api.openai.com/v1'
+ * });
+ * ```
+ *
+ * @example Using with a self-hosted server
+ * ```typescript
+ * const model = responses('llama-3.3-70b', {
+ *   host: 'http://localhost:8080/v1',
+ *   apiKeyEnv: 'LOCAL_API_KEY'
+ * });
+ * ```
+ */
+interface ResponsesProviderOptions {
+    /**
+     * The base URL for the OpenResponses-compatible API.
+     * The `/responses` endpoint will be appended to this URL.
+     *
+     * @example 'https://api.openai.com/v1'
+     * @example 'https://openrouter.ai/api/v1'
+     * @example 'http://localhost:8080/v1'
+     */
+    host: string;
+    /**
+     * Environment variable name containing the API key.
+     * Defaults to 'OPENRESPONSES_API_KEY'.
+     *
+     * @example 'OPENAI_API_KEY'
+     * @example 'OPENROUTER_API_KEY'
+     */
+    apiKeyEnv?: string;
+}
+/**
+ * Parameters for the OpenResponses API.
+ *
+ * These parameters follow the OpenResponses specification and are passed
+ * directly to the `/responses` endpoint.
+ *
+ * @see {@link https://www.openresponses.org/spec OpenResponses Spec}
+ */
+interface ResponsesParams {
+    /** Maximum output tokens (minimum 16) */
+    max_output_tokens?: number;
+    /** Temperature for randomness (0.0 - 2.0) */
+    temperature?: number;
+    /** Top-p (nucleus) sampling (0.0 - 1.0) */
+    top_p?: number;
+    /** Presence penalty for new tokens */
+    presence_penalty?: number;
+    /** Frequency penalty for new tokens */
+    frequency_penalty?: number;
+    /** Number of top logprobs to return (0-20) */
+    top_logprobs?: number;
+    /** Whether to enable parallel tool calls */
+    parallel_tool_calls?: boolean;
+    /**
+     * Reasoning configuration (for reasoning models).
+     * Supported on gpt-5 and o-series models.
+     */
+    reasoning?: {
+        /** Reasoning effort level */
+        effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+        /** Include summary of reasoning */
+        summary?: 'auto' | 'concise' | 'detailed';
+    };
+    /** Service tier */
+    service_tier?: 'auto' | 'default' | 'flex' | 'priority';
+    /** Truncation strategy */
+    truncation?: 'auto' | 'disabled';
+    /**
+     * Fields to include in output.
+     * @example ['reasoning.encrypted_content', 'message.output_text.logprobs']
+     */
+    include?: string[];
+    /** Background processing - run response asynchronously */
+    background?: boolean;
+    /** Continue from a previous response */
+    previous_response_id?: string;
+    /** Store response for continuation */
+    store?: boolean;
+    /** Metadata key-value pairs (max 16, keys max 64 chars, values max 512 chars) */
+    metadata?: Record<string, string>;
+    /** Maximum total calls to built-in tools */
+    max_tool_calls?: number;
+    /** Stable identifier for caching similar requests (max 64 chars) */
+    prompt_cache_key?: string;
+    /** Stable identifier for abuse detection (max 64 chars) */
+    safety_identifier?: string;
+    /**
+     * Text format configuration.
+     * Controls output format (text, json_object, json_schema) and verbosity.
+     */
+    text?: ResponsesTextConfig;
+    /**
+     * Built-in tools from the OpenResponses specification.
+     * Currently supports function tools; provider-specific built-in tools
+     * may be added via the tools array.
+     */
+    tools?: ResponsesBuiltInTool[];
+}
+/**
+ * Text output configuration for structured output.
+ */
+interface ResponsesTextConfig {
+    /** Text output format */
+    format?: {
+        type: 'text';
+    } | {
+        type: 'json_object';
+    } | {
+        type: 'json_schema';
+        name: string;
+        description?: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+    /** Verbosity level for responses */
+    verbosity?: 'low' | 'medium' | 'high';
+}
+/**
+ * Request body for the OpenResponses API.
+ */
+interface ResponsesRequest {
+    model: string;
+    input: string | ResponsesInputItem[];
+    instructions?: string;
+    max_output_tokens?: number;
+    temperature?: number;
+    top_p?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    top_logprobs?: number;
+    stream?: boolean;
+    tools?: ResponsesToolUnion[];
+    tool_choice?: ResponsesToolChoice;
+    parallel_tool_calls?: boolean;
+    text?: ResponsesTextConfig;
+    truncation?: 'auto' | 'disabled';
+    store?: boolean;
+    metadata?: Record<string, string>;
+    reasoning?: {
+        effort?: 'none' | 'low' | 'medium' | 'high' | 'xhigh';
+        summary?: 'auto' | 'concise' | 'detailed';
+    };
+    service_tier?: string;
+    include?: string[];
+    background?: boolean;
+    previous_response_id?: string;
+    max_tool_calls?: number;
+    prompt_cache_key?: string;
+    safety_identifier?: string;
+}
+/**
+ * Union type for all input item types.
+ */
+type ResponsesInputItem = ResponsesSystemItem | ResponsesUserItem | ResponsesAssistantItem | ResponsesFunctionCallInputItem | ResponsesToolResultItem | ResponsesReasoningInputItem | ResponsesItemReference;
+/**
+ * Reference to a previous item by ID.
+ */
+interface ResponsesItemReference {
+    type: 'item_reference';
+    id: string;
+}
+/**
+ * Reasoning input item for multi-turn context preservation.
+ */
+interface ResponsesReasoningInputItem {
+    type: 'reasoning';
+    id: string;
+    summary: Array<{
+        type: 'summary_text';
+        text: string;
+    }>;
+    encrypted_content?: string;
+}
+/** System message input item */
+interface ResponsesSystemItem {
+    type: 'message';
+    role: 'system' | 'developer';
+    content: string | ResponsesContentPart[];
+}
+/** User message input item */
+interface ResponsesUserItem {
+    type: 'message';
+    role: 'user';
+    content: string | ResponsesContentPart[];
+}
+/** Assistant message input item */
+interface ResponsesAssistantItem {
+    type: 'message';
+    role: 'assistant';
+    content: string | ResponsesContentPart[];
+}
+/** Function call input item */
+interface ResponsesFunctionCallInputItem {
+    type: 'function_call';
+    id: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+/** Function call output (tool result) input item */
+interface ResponsesToolResultItem {
+    type: 'function_call_output';
+    call_id: string;
+    output: string;
+}
+/**
+ * Union type for content parts.
+ */
+type ResponsesContentPart = ResponsesTextPart | ResponsesImagePart | ResponsesFilePart | ResponsesVideoPart | ResponsesOutputTextPart | ResponsesFunctionCallPart;
+/** Text input content part */
+interface ResponsesTextPart {
+    type: 'input_text';
+    text: string;
+}
+/** Text output content part */
+interface ResponsesOutputTextPart {
+    type: 'output_text';
+    text: string;
+}
+/** Image content part */
+interface ResponsesImagePart {
+    type: 'input_image';
+    /** Image URL or base64 data URL */
+    image_url?: string;
+    /** Base64 image data (alternative to image_url) */
+    image?: string;
+    /** Detail level for image processing */
+    detail?: 'auto' | 'low' | 'high';
+}
+/** File content part (PDFs, documents) */
+interface ResponsesFilePart {
+    type: 'input_file';
+    filename?: string;
+    /** Base64 data URL */
+    file_data?: string;
+    /** URL to fetch the file from */
+    file_url?: string;
+    /** Pre-uploaded file ID */
+    file_id?: string;
+}
+/** Video content part */
+interface ResponsesVideoPart {
+    type: 'input_video';
+    /** Base64 video data */
+    video?: string;
+    /** URL to fetch the video from */
+    video_url?: string;
+}
+/** Function call content part */
+interface ResponsesFunctionCallPart {
+    type: 'function_call';
+    id: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+}
+/**
+ * Function tool definition.
+ */
+interface ResponsesFunctionTool {
+    type: 'function';
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+    strict?: boolean;
+}
+/**
+ * Built-in tool placeholder for provider-specific tools.
+ * Providers implementing OpenResponses may add their own built-in tools.
+ */
+interface ResponsesBuiltInTool {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Combined tool type (function or built-in).
+ */
+type ResponsesToolUnion = ResponsesFunctionTool | ResponsesBuiltInTool;
+/**
+ * Tool choice options.
+ */
+type ResponsesToolChoice = 'none' | 'auto' | 'required' | {
+    type: 'function';
+    name: string;
+};
+/**
+ * Response from the OpenResponses API.
+ */
+interface ResponsesResponse {
+    id: string;
+    object: 'response';
+    created_at: number;
+    completed_at?: number;
+    model: string;
+    output: ResponsesOutputItem[];
+    usage: ResponsesUsage;
+    status: 'completed' | 'failed' | 'incomplete' | 'in_progress' | 'queued';
+    error?: {
+        code: string;
+        message: string;
+        param?: string;
+    };
+    incomplete_details?: {
+        reason: string;
+    };
+}
+/**
+ * Union type for all output item types.
+ */
+type ResponsesOutputItem = ResponsesMessageOutput | ResponsesFunctionCallOutput | ResponsesReasoningOutput;
+/** Assistant message output item */
+interface ResponsesMessageOutput {
+    type: 'message';
+    id: string;
+    role: 'assistant';
+    content: ResponsesOutputContent[];
+    status: 'completed' | 'in_progress';
+}
+/** Function call output item */
+interface ResponsesFunctionCallOutput {
+    type: 'function_call';
+    id: string;
+    call_id: string;
+    name: string;
+    arguments: string;
+    status: 'completed' | 'in_progress';
+}
+/** Reasoning output item */
+interface ResponsesReasoningOutput {
+    type: 'reasoning';
+    id: string;
+    summary: Array<{
+        type: 'summary_text';
+        text: string;
+    }>;
+    status: 'completed' | 'in_progress' | null;
+    encrypted_content?: string;
+}
+/** Output content types */
+type ResponsesOutputContent = {
+    type: 'output_text';
+    text: string;
+    annotations?: unknown[];
+} | {
+    type: 'refusal';
+    refusal: string;
+} | {
+    type: 'reasoning_text';
+    text: string;
+} | {
+    type: 'summary_text';
+    text: string;
+};
+/** Token usage statistics */
+interface ResponsesUsage {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    input_tokens_details?: {
+        cached_tokens?: number;
+        text_tokens?: number;
+        image_tokens?: number;
+        audio_tokens?: number;
+    };
+    output_tokens_details?: {
+        text_tokens?: number;
+        reasoning_tokens?: number;
+    };
+}
+/**
+ * Union type for all streaming events.
+ */
+type ResponsesStreamEvent = ResponsesCreatedEvent | ResponsesQueuedEvent | ResponsesInProgressEvent | ResponsesCompletedEvent | ResponsesFailedEvent | ResponsesIncompleteEvent | ResponsesOutputItemAddedEvent | ResponsesOutputItemDoneEvent | ResponsesContentPartAddedEvent | ResponsesContentPartDoneEvent | ResponsesTextDeltaEvent | ResponsesTextDoneEvent | ResponsesRefusalDeltaEvent | ResponsesRefusalDoneEvent | ResponsesFunctionCallArgumentsDeltaEvent | ResponsesFunctionCallArgumentsDoneEvent | ResponsesReasoningDeltaEvent | ResponsesReasoningDoneEvent | ResponsesReasoningSummaryTextDeltaEvent | ResponsesReasoningSummaryTextDoneEvent | ResponsesReasoningSummaryPartAddedEvent | ResponsesReasoningSummaryPartDoneEvent | ResponsesAnnotationAddedEvent | ResponsesErrorEvent;
+interface ResponsesCreatedEvent {
+    type: 'response.created';
+    response: ResponsesResponse;
+    sequence_number?: number;
+}
+interface ResponsesQueuedEvent {
+    type: 'response.queued';
+    response: ResponsesResponse;
+    sequence_number?: number;
+}
+interface ResponsesInProgressEvent {
+    type: 'response.in_progress';
+    response: ResponsesResponse;
+    sequence_number?: number;
+}
+interface ResponsesCompletedEvent {
+    type: 'response.completed';
+    response: ResponsesResponse;
+    sequence_number?: number;
+}
+interface ResponsesFailedEvent {
+    type: 'response.failed';
+    response: ResponsesResponse;
+    sequence_number?: number;
+}
+interface ResponsesIncompleteEvent {
+    type: 'response.incomplete';
+    response: ResponsesResponse;
+    sequence_number?: number;
+}
+interface ResponsesOutputItemAddedEvent {
+    type: 'response.output_item.added';
+    output_index: number;
+    item: ResponsesOutputItem;
+    sequence_number?: number;
+}
+interface ResponsesOutputItemDoneEvent {
+    type: 'response.output_item.done';
+    output_index: number;
+    item: ResponsesOutputItem;
+    sequence_number?: number;
+}
+interface ResponsesContentPartAddedEvent {
+    type: 'response.content_part.added';
+    output_index: number;
+    content_index: number;
+    part: ResponsesOutputContent;
+    sequence_number?: number;
+}
+interface ResponsesContentPartDoneEvent {
+    type: 'response.content_part.done';
+    output_index: number;
+    content_index: number;
+    part: ResponsesOutputContent;
+    sequence_number?: number;
+}
+interface ResponsesTextDeltaEvent {
+    type: 'response.output_text.delta';
+    output_index: number;
+    content_index: number;
+    delta: string;
+    sequence_number?: number;
+}
+interface ResponsesTextDoneEvent {
+    type: 'response.output_text.done';
+    output_index: number;
+    content_index: number;
+    text: string;
+    sequence_number?: number;
+}
+interface ResponsesRefusalDeltaEvent {
+    type: 'response.refusal.delta';
+    output_index: number;
+    content_index: number;
+    delta: string;
+    sequence_number?: number;
+}
+interface ResponsesRefusalDoneEvent {
+    type: 'response.refusal.done';
+    output_index: number;
+    content_index: number;
+    refusal: string;
+    sequence_number?: number;
+}
+interface ResponsesFunctionCallArgumentsDeltaEvent {
+    type: 'response.function_call_arguments.delta';
+    output_index: number;
+    item_id: string;
+    delta: string;
+    call_id?: string;
+    sequence_number?: number;
+}
+interface ResponsesFunctionCallArgumentsDoneEvent {
+    type: 'response.function_call_arguments.done';
+    output_index: number;
+    item_id: string;
+    name: string;
+    arguments: string;
+    call_id?: string;
+    sequence_number?: number;
+}
+interface ResponsesReasoningDeltaEvent {
+    type: 'response.reasoning.delta';
+    output_index: number;
+    delta: string;
+    sequence_number?: number;
+}
+interface ResponsesReasoningDoneEvent {
+    type: 'response.reasoning.done';
+    output_index: number;
+    text: string;
+    sequence_number?: number;
+}
+interface ResponsesReasoningSummaryTextDeltaEvent {
+    type: 'response.reasoning_summary_text.delta';
+    item_id: string;
+    output_index: number;
+    summary_index: number;
+    delta: string;
+    sequence_number?: number;
+}
+interface ResponsesReasoningSummaryTextDoneEvent {
+    type: 'response.reasoning_summary_text.done';
+    item_id: string;
+    output_index: number;
+    summary_index: number;
+    text: string;
+    sequence_number?: number;
+}
+interface ResponsesReasoningSummaryPartAddedEvent {
+    type: 'response.reasoning_summary_part.added';
+    output_index: number;
+    summary_index: number;
+    part: {
+        type: 'summary_text';
+        text: string;
+    };
+    sequence_number?: number;
+}
+interface ResponsesReasoningSummaryPartDoneEvent {
+    type: 'response.reasoning_summary_part.done';
+    output_index: number;
+    summary_index: number;
+    part: {
+        type: 'summary_text';
+        text: string;
+    };
+    sequence_number?: number;
+}
+interface ResponsesAnnotationAddedEvent {
+    type: 'response.output_text.annotation.added';
+    output_index: number;
+    content_index: number;
+    annotation_index: number;
+    annotation: unknown;
+    sequence_number?: number;
+}
+interface ResponsesErrorEvent {
+    type: 'error';
+    error: {
+        type: string;
+        code?: string;
+        message: string;
+        param?: string;
+    };
+    sequence_number?: number;
+}
+/**
+ * Custom HTTP headers for OpenResponses requests.
+ */
+interface ResponsesHeaders {
+    [key: string]: string | undefined;
+}
+
+/**
+ * @fileoverview OpenResponses Provider
+ *
+ * Implements support for the OpenResponses specification - an open-source,
+ * multi-provider standard for interoperable LLM interfaces.
+ *
+ * The OpenResponses provider allows connecting to any server implementing
+ * the OpenResponses API specification, including OpenAI, OpenRouter,
+ * and self-hosted implementations.
+ *
+ * @see {@link https://www.openresponses.org OpenResponses Specification}
+ * @module providers/responses
+ */
+
+/**
+ * Type alias for the OpenResponses provider with its options.
+ */
+type ResponsesProvider = Provider<ResponsesProviderOptions>;
+/**
+ * OpenResponses provider singleton.
+ *
+ * Implements the OpenResponses specification for multi-provider, interoperable
+ * LLM interfaces. This provider works with any server implementing the
+ * OpenResponses API, including:
+ *
+ * - OpenAI (`https://api.openai.com/v1`)
+ * - OpenRouter (`https://openrouter.ai/api/v1`)
+ * - Self-hosted servers
+ * - Any OpenResponses-compatible endpoint
+ *
+ * @example Using with OpenAI
+ * ```typescript
+ * import { responses } from './providers/responses';
+ * import { llm } from './core/llm';
+ *
+ * const model = llm({
+ *   model: responses('gpt-5.2', { host: 'https://api.openai.com/v1' }),
+ *   params: { max_output_tokens: 1000 }
+ * });
+ *
+ * const turn = await model.generate('Hello!');
+ * console.log(turn.response.text);
+ * ```
+ *
+ * @example Using with OpenRouter
+ * ```typescript
+ * const model = llm({
+ *   model: responses('openai/gpt-4o', {
+ *     host: 'https://openrouter.ai/api/v1',
+ *     apiKeyEnv: 'OPENROUTER_API_KEY'
+ *   }),
+ *   params: { max_output_tokens: 1000 }
+ * });
+ * ```
+ *
+ * @example Using with a self-hosted server
+ * ```typescript
+ * const model = llm({
+ *   model: responses('llama-3.3-70b', {
+ *     host: 'http://localhost:8080/v1',
+ *     apiKeyEnv: 'LOCAL_API_KEY'
+ *   }),
+ *   params: { max_output_tokens: 1000 }
+ * });
+ * ```
+ *
+ * @see {@link https://www.openresponses.org OpenResponses Specification}
+ */
+declare const responses: ResponsesProvider;
+
+export { type ResponsesBuiltInTool, type ResponsesContentPart, type ResponsesFunctionTool, type ResponsesHeaders, type ResponsesInputItem, type ResponsesOutputItem, type ResponsesParams, type ResponsesProviderOptions, type ResponsesRequest, type ResponsesResponse, type ResponsesStreamEvent, type ResponsesToolUnion, type ResponsesUsage, responses };