// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as ResponsesAPI from './responses';
import * as Shared from '../shared';
import * as FilesAPI from './files';
import { FileContentParams, Files } from './files';
import { APIPromise } from '../../core/api-promise';
import { Stream } from '../../core/streaming';
import { RequestOptions } from '../../internal/request-options';
import { addOutputText } from '../../lib/add-output-text';
import { path } from '../../internal/utils/path';

export class Responses extends APIResource {
  files: FilesAPI.Files = new FilesAPI.Files(this._client);

  /**
   * Generate a response for the provided input with optional web search and
   * reasoning.
   */
  create(
    body: ResponseCreateParamsNonStreaming,
    options?: RequestOptions,
  ): APIPromise<ResponseCreateResponse>;
  create(
    body: ResponseCreateParamsStreaming,
    options?: RequestOptions,
  ): APIPromise<Stream<ResponseStreamChunk>>;
  create(
    body: ResponseCreateParamsBase,
    options?: RequestOptions,
  ): APIPromise<Stream<ResponseStreamChunk> | ResponseCreateResponse>;
  create(
    body: ResponseCreateParams,
    options?: RequestOptions,
  ): APIPromise<ResponseCreateResponse> | APIPromise<Stream<ResponseStreamChunk>> {
    const promise = this._client.post('/v1/responses', { body, ...options, stream: body.stream ?? false });

    // For non-streaming responses, automatically add output_text property
    if (!body.stream) {
      return (promise as APIPromise<ResponseCreateResponse>)._thenUnwrap((rsp) => {
        if ('object' in rsp && rsp.object === 'response') {
          addOutputText(rsp as ResponseCreateResponse);
        }
        return rsp;
      }) as APIPromise<ResponseCreateResponse>;
    }

    return promise as APIPromise<Stream<ResponseStreamChunk>>;
  }

  /**
   * Retrieve a response by its ID. Use this to poll the status of background tasks.
   */
  retrieve(responseID: string, options?: RequestOptions): APIPromise<ResponseRetrieveResponse> {
    return this._client.get(path`/v1/responses/${responseID}`, options);
  }
}

/**
 * Text annotation (e.g., URL citation)
 */
export interface Annotation {
  end_index?: number;

  start_index?: number;

  title?: string;

  type?: string;

  url?: string;
}

export interface ContentPart {
  text: string;

  /**
   * Type of a content part
   */
  type: 'output_text';

  annotations?: Array<Annotation>;
}

export interface ErrorInfo {
  message: string;

  code?: string;

  type?: string;
}

export interface FunctionCallOutputItem {
  id: string;

  /**
   * JSON string of arguments
   */
  arguments: string;

  /**
   * Correlates with function_call_output input
   */
  call_id: string;

  name: string;

  /**
   * Status of a response or output item
   */
  status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

  type: 'function_call';

  /**
   * Base64-encoded opaque signature for thinking models
   */
  thought_signature?: string;
}

export interface FunctionTool {
  /**
   * The name of the function
   */
  name: string;

  type: 'function';

  /**
   * A description of what the function does
   */
  description?: string;

  /**
   * JSON Schema defining the function's parameters
   */
  parameters?: { [key: string]: unknown };

  /**
   * Whether to enable strict schema validation
   */
  strict?: boolean;
}

export type InputItem =
  | InputItem.InputMessage
  | InputItem.FunctionCallOutputInput
  | InputItem.FunctionCallInput;

export namespace InputItem {
  export interface InputMessage {
    /**
     * Message content - either a string or array of content parts
     */
    content: string | Array<InputMessage.ContentPartArray>;

    role: 'user' | 'assistant' | 'system' | 'developer';

    type: 'message';
  }

  export namespace InputMessage {
    export interface ContentPartArray {
      type: 'input_text' | 'input_image';

      image_url?: string;

      text?: string;
    }
  }

  export interface FunctionCallOutputInput {
    /**
     * The call_id from function_call output
     */
    call_id: string;

    /**
     * Function result (JSON string)
     */
    output: string;

    type: 'function_call_output';

    /**
     * Function name (required by some providers)
     */
    name?: string;

    /**
     * Base64-encoded signature from function_call
     */
    thought_signature?: string;
  }

  export interface FunctionCallInput {
    /**
     * Function arguments (JSON string)
     */
    arguments: string;

    /**
     * The call_id that correlates with function_call_output
     */
    call_id: string;

    /**
     * The function name
     */
    name: string;

    type: 'function_call';

    /**
     * Base64-encoded signature for thinking models
     */
    thought_signature?: string;
  }
}

/**
 * One item in the response output: an assistant message, retrieved tool results,
 * or a record of a tool call.
 */
export type OutputItem =
  | OutputItem.MessageOutputItem
  | OutputItem.SearchResultsOutputItem
  | OutputItem.FetchURLResultsOutputItem
  | FunctionCallOutputItem
  | OutputItem.McpListToolsOutputItem
  | OutputItem.McpCallOutputItem;

export namespace OutputItem {
  export interface MessageOutputItem {
    id: string;

    content: Array<ResponsesAPI.ContentPart>;

    /**
     * Role in a message
     */
    role: 'assistant';

    /**
     * Status of a response or output item
     */
    status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

    type: 'message';
  }

  export interface SearchResultsOutputItem {
    results: Array<Shared.SearchResult>;

    type: 'search_results';

    queries?: Array<string>;
  }

  export interface FetchURLResultsOutputItem {
    contents: Array<FetchURLResultsOutputItem.Content>;

    type: 'fetch_url_results';
  }

  export namespace FetchURLResultsOutputItem {
    /**
     * Content fetched from a URL
     */
    export interface Content {
      /**
       * The fetched content snippet
       */
      snippet: string;

      /**
       * The title of the page
       */
      title: string;

      /**
       * The URL from which content was fetched
       */
      url: string;
    }
  }

  /**
   * Tools discovered on one external MCP server at boot. Matches OpenAI's
   * mcp_list_tools item.
   */
  export interface McpListToolsOutputItem {
    id: string;

    server_label: string;

    tools: Array<McpListToolsOutputItem.Tool>;

    type: 'mcp_list_tools';

    error?: string;
  }

  export namespace McpListToolsOutputItem {
    /**
     * One tool discovered on a remote MCP server.
     */
    export interface Tool {
      /**
       * The server's JSON Schema for the tool, passed through unmodified.
       */
      input_schema: { [key: string]: unknown };

      name: string;

      description?: string;
    }
  }

  /**
   * One tool call executed against an external MCP server, modeled on OpenAI's
   * mcp_call item.
   */
  export interface McpCallOutputItem {
    id: string;

    /**
     * JSON-encoded arguments the model passed.
     */
    arguments: string;

    name: string;

    server_label: string;

    type: 'mcp_call';

    /**
     * The failure string when the call failed (also returned to the model in-band);
     * null on success, matching OpenAI's mcp_call.
     */
    error?: string | null;

    /**
     * Tool output text; empty when the call failed.
     */
    output?: string;
  }
}

/**
 * Metadata for a file shared from a response sandbox via the share_file tool.
 */
export interface ResponseFile {
  /**
   * File identifier, scoped to the parent response.
   */
  id: string;

  /**
   * Size of the file in bytes.
   */
  bytes: number;

  /**
   * Unix timestamp (seconds) when the file was produced.
   */
  created_at: number;

  /**
   * Original filename set by the share_file tool call.
   */
  filename: string;

  /**
   * Object type. Always `file`.
   */
  object: 'file';
}

export interface ResponseFileList {
  data: Array<ResponseFile>;

  /**
   * Object type. Always `list`.
   */
  object: 'list';
}

/**
 * SSE stream event. Discriminate by the `type` field:
 *
 * - `response.created`: Initial response object
 * - `response.in_progress`: Response processing started
 * - `response.completed`: Final response with output
 * - `response.failed`: Error occurred
 * - `response.output_item.added`: New output item started
 * - `response.output_item.done`: Output item completed
 * - `response.output_text.delta`: Streaming text delta
 * - `response.output_text.done`: Final text content
 * - `response.reasoning.started`: Reasoning phase started
 * - `response.reasoning.search_queries`: Search queries issued
 * - `response.reasoning.search_results`: Search results received
 * - `response.reasoning.fetch_url_queries`: URL fetch queries issued
 * - `response.reasoning.fetch_url_results`: URL fetch results received
 * - `response.reasoning.stopped`: Reasoning phase complete
 */
export type ResponseStreamChunk =
  | ResponseStreamChunk.ResponseCreatedEvent
  | ResponseStreamChunk.ResponseInProgressEvent
  | ResponseStreamChunk.ResponseCompletedEvent
  | ResponseStreamChunk.ResponseFailedEvent
  | ResponseStreamChunk.OutputItemAddedEvent
  | ResponseStreamChunk.OutputItemDoneEvent
  | ResponseStreamChunk.TextDeltaEvent
  | ResponseStreamChunk.TextDoneEvent
  | ResponseStreamChunk.ReasoningStartedEvent
  | ResponseStreamChunk.SearchQueriesEvent
  | ResponseStreamChunk.SearchResultsEvent
  | ResponseStreamChunk.FetchURLQueriesEvent
  | ResponseStreamChunk.FetchURLResultsEvent
  | ResponseStreamChunk.ReasoningStoppedEvent;

export namespace ResponseStreamChunk {
  /**
   * Response created event (type: "response.created"). Contains the initial response
   * object.
   */
  export interface ResponseCreatedEvent {
    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.created")
     */
    type: 'response.created';

    /**
     * Non-streaming response returned when stream is false
     */
    response?: ResponseCreatedEvent.Response;
  }

  export namespace ResponseCreatedEvent {
    /**
     * Non-streaming response returned when stream is false
     */
    export interface Response {
      id: string;

      created_at: number;

      model: string;

      /**
       * Object type in API responses
       */
      object: 'response';

      output: Array<ResponsesAPI.OutputItem>;

      /**
       * Status of a response or output item
       */
      status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

      /**
       * Whether the response was created in background mode.
       */
      background?: boolean;

      error?: ResponsesAPI.ErrorInfo;

      usage?: ResponsesAPI.ResponsesUsage;
    }
  }

  /**
   * Response in progress event (type: "response.in_progress"). Emitted when response
   * processing has started.
   */
  export interface ResponseInProgressEvent {
    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.in_progress")
     */
    type: 'response.in_progress';

    /**
     * Non-streaming response returned when stream is false
     */
    response?: ResponseInProgressEvent.Response;
  }

  export namespace ResponseInProgressEvent {
    /**
     * Non-streaming response returned when stream is false
     */
    export interface Response {
      id: string;

      created_at: number;

      model: string;

      /**
       * Object type in API responses
       */
      object: 'response';

      output: Array<ResponsesAPI.OutputItem>;

      /**
       * Status of a response or output item
       */
      status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

      /**
       * Whether the response was created in background mode.
       */
      background?: boolean;

      error?: ResponsesAPI.ErrorInfo;

      usage?: ResponsesAPI.ResponsesUsage;
    }
  }

  /**
   * Response event Contains the full or partial response object.
   */
  export interface ResponseCompletedEvent {
    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.completed")
     */
    type: 'response.completed';

    /**
     * Non-streaming response returned when stream is false
     */
    response?: ResponseCompletedEvent.Response;
  }

  export namespace ResponseCompletedEvent {
    /**
     * Non-streaming response returned when stream is false
     */
    export interface Response {
      id: string;

      created_at: number;

      model: string;

      /**
       * Object type in API responses
       */
      object: 'response';

      output: Array<ResponsesAPI.OutputItem>;

      /**
       * Status of a response or output item
       */
      status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

      /**
       * Whether the response was created in background mode.
       */
      background?: boolean;

      error?: ResponsesAPI.ErrorInfo;

      usage?: ResponsesAPI.ResponsesUsage;
    }
  }

  /**
   * Response failed event (type: "response.failed"). Contains error details when
   * streaming fails.
   */
  export interface ResponseFailedEvent {
    error: ResponsesAPI.ErrorInfo;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.failed")
     */
    type: 'response.failed';
  }

  /**
   * Output item added event (type: "response.output_item.added"). Emitted when a new
   * output item (message or tool call) starts.
   */
  export interface OutputItemAddedEvent {
    /**
     * One item in the response output: an assistant message, retrieved tool results,
     * or a record of a tool call.
     */
    item: ResponsesAPI.OutputItem;

    output_index: number;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.output_item.added")
     */
    type: 'response.output_item.added';
  }

  /**
   * Output item done event (type: "response.output_item.done"). Emitted when an
   * output item (message or tool call) completes.
   */
  export interface OutputItemDoneEvent {
    /**
     * One item in the response output: an assistant message, retrieved tool results,
     * or a record of a tool call.
     */
    item: ResponsesAPI.OutputItem;

    output_index: number;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.output_item.done")
     */
    type: 'response.output_item.done';
  }

  /**
   * Text delta event (type: "response.output_text.delta"). Contains incremental text
   * content.
   */
  export interface TextDeltaEvent {
    content_index: number;

    delta: string;

    item_id: string;

    output_index: number;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.output_text.delta")
     */
    type: 'response.output_text.delta';
  }

  /**
   * Text done event (type: "response.output_text.done"). Contains the final text
   * content.
   */
  export interface TextDoneEvent {
    content_index: number;

    item_id: string;

    output_index: number;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    text: string;

    /**
     * SSE event type discriminator (always "response.output_text.done")
     */
    type: 'response.output_text.done';
  }

  /**
   * Reasoning started event (type: "response.reasoning.started"). Signals the model
   * has started reasoning/searching.
   */
  export interface ReasoningStartedEvent {
    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.reasoning.started")
     */
    type: 'response.reasoning.started';

    thought?: string;
  }

  /**
   * Search queries event (type: "response.reasoning.search_queries"). Contains
   * search queries being executed.
   */
  export interface SearchQueriesEvent {
    queries: Array<string>;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.reasoning.search_queries")
     */
    type: 'response.reasoning.search_queries';

    thought?: string;
  }

  /**
   * Search results event (type: "response.reasoning.search_results"). Contains
   * search results returned.
   */
  export interface SearchResultsEvent {
    results: Array<Shared.SearchResult>;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.reasoning.search_results")
     */
    type: 'response.reasoning.search_results';

    thought?: string;

    usage?: ResponsesAPI.ResponsesUsage;
  }

  /**
   * URL fetch queries event (type: "response.reasoning.fetch_url_queries"). Contains
   * URLs being fetched.
   */
  export interface FetchURLQueriesEvent {
    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.reasoning.fetch_url_queries")
     */
    type: 'response.reasoning.fetch_url_queries';

    urls: Array<string>;

    thought?: string;
  }

  /**
   * URL fetch results event (type: "response.reasoning.fetch_url_results"). Contains
   * fetched URL contents.
   */
  export interface FetchURLResultsEvent {
    contents: Array<FetchURLResultsEvent.Content>;

    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.reasoning.fetch_url_results")
     */
    type: 'response.reasoning.fetch_url_results';

    thought?: string;
  }

  export namespace FetchURLResultsEvent {
    /**
     * Content fetched from a URL
     */
    export interface Content {
      /**
       * The fetched content snippet
       */
      snippet: string;

      /**
       * The title of the page
       */
      title: string;

      /**
       * The URL from which content was fetched
       */
      url: string;
    }
  }

  /**
   * Reasoning stopped event (type: "response.reasoning.stopped"). Signals the model
   * has finished reasoning/searching.
   */
  export interface ReasoningStoppedEvent {
    /**
     * Monotonically increasing sequence number for event ordering
     */
    sequence_number: number;

    /**
     * SSE event type discriminator (always "response.reasoning.stopped")
     */
    type: 'response.reasoning.stopped';

    thought?: string;
  }
}

export interface ResponsesCreateParams {
  /**
   * Input content - either a string or array of input items
   */
  input: string | Array<InputItem>;

  /**
   * Run the response asynchronously. When true, the request is queued and the
   * response object's `status` will be `queued` or `in_progress`. Poll GET
   * /v1/responses/{response_id} to retrieve the final result.
   */
  background?: boolean | null;

  /**
   * System instructions for the model
   */
  instructions?: string;

  /**
   * ISO 639-1 language code for response language
   */
  language_preference?: string;

  /**
   * Maximum tokens to generate
   */
  max_output_tokens?: number;

  /**
   * Maximum number of research loop steps. If provided, overrides the preset's
   * max_steps value. Must be >= 1 if specified. Maximum allowed is 10.
   */
  max_steps?: number;

  /**
   * Model ID in provider/model format (e.g., "xai/grok-4-1", "openai/gpt-4o"). If
   * models is also provided, models takes precedence. Required if neither models nor
   * preset is provided.
   */
  model?: string;

  /**
   * Model fallback chain. Each model is in provider/model format. Models are tried
   * in order until one succeeds. Max 5 models allowed. If set, takes precedence over
   * single model field. The response.model will reflect the model that actually
   * succeeded.
   */
  models?: Array<string>;

  /**
   * Preset configuration name (e.g., "sonar-pro", "sonar-reasoning"). Pre-configured
   * model with system prompt and search parameters. Required if model is not
   * provided.
   */
  preset?: string;

  reasoning?: ResponsesCreateParams.Reasoning;

  /**
   * Specifies the desired output format for the model response
   */
  response_format?: Shared.ResponseFormat;

  /**
   * If true, returns SSE stream instead of JSON
   */
  stream?: boolean;

  /**
   * Tools available to the model
   */
  tools?: Array<
    | ResponsesCreateParams.WebSearchTool
    | ResponsesCreateParams.FetchURLTool
    | ResponsesCreateParams.PeopleSearchTool
    | FunctionTool
    | ResponsesCreateParams.FinanceSearchTool
    | ResponsesCreateParams.SandboxTool
    | ResponsesCreateParams.McpTool
  >;
}

export namespace ResponsesCreateParams {
  export interface Reasoning {
    /**
     * How much effort the model should spend on reasoning
     */
    effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
  }

  export interface WebSearchTool {
    type: 'web_search';

    filters?: WebSearchTool.Filters;

    max_tokens?: number;

    max_tokens_per_page?: number;

    /**
     * Search context size (low, medium, high). Omit when supplying explicit max_tokens
     * / max_tokens_per_page.
     */
    search_context_size?: 'low' | 'medium' | 'high';

    /**
     * User's geographic location for search personalization
     */
    user_location?: WebSearchTool.UserLocation;
  }

  export namespace WebSearchTool {
    export interface Filters {
      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      last_updated_after_filter?: string;

      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      last_updated_before_filter?: string;

      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      search_after_date_filter?: string;

      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      search_before_date_filter?: string;

      search_domain_filter?: Array<string>;

      search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year';
    }

    /**
     * User's geographic location for search personalization
     */
    export interface UserLocation {
      city?: string;

      /**
       * ISO 3166-1 alpha-2 country code
       */
      country?: string;

      latitude?: number;

      longitude?: number;

      region?: string;
    }
  }

  export interface FetchURLTool {
    type: 'fetch_url';

    /**
     * Maximum number of URLs to fetch per tool call
     */
    max_urls?: number;
  }

  export interface PeopleSearchTool {
    /**
     * Enables the `people_search` tool.
     */
    type: 'people_search';
  }

  export interface FinanceSearchTool {
    /**
     * Enables the `finance_search` tool. The model can request structured financial
     * data (quotes, financials, segments, earnings transcripts, etc.) via
     * category-based fan-out to FMP, Finchat, and Quartr.
     */
    type: 'finance_search';
  }

  export interface SandboxTool {
    /**
     * Enables the `sandbox` tool. The model can execute code in an isolated container
     * during the request and use the result in its final answer.
     */
    type: 'sandbox';
  }

  /**
   * Connects a user-supplied remote MCP server. The worker discovers the server's
   * tools at boot and calls them like native tools. Matches OpenAI's mcp tool.
   * `require_approval`, `connector_id`, and `defer_loading` are not supported in v1
   * and are ignored if sent: every call auto-runs, and only bring-your-own
   * `server_url` is honored.
   */
  export interface McpTool {
    /**
     * Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools.
     */
    server_label: string;

    /**
     * HTTPS URL of the remote MCP server.
     */
    server_url: string;

    type: 'mcp';

    /**
     * Optional allowlist of tool names. Empty exposes all discovered tools.
     */
    allowed_tools?: Array<string>;

    /**
     * An OAuth access token that can be used with a remote MCP server, with a custom
     * MCP server URL. Never logged or echoed.
     */
    authorization?: string;

    /**
     * Extra request headers. Never logged or echoed.
     */
    headers?: { [key: string]: string };
  }
}

export interface ResponsesUsage {
  input_tokens: number;

  output_tokens: number;

  total_tokens: number;

  cost?: ResponsesUsage.Cost;

  input_tokens_details?: ResponsesUsage.InputTokensDetails;

  tool_calls_details?: { [key: string]: ResponsesUsage.ToolCallsDetails };
}

export namespace ResponsesUsage {
  export interface Cost {
    /**
     * Currency code for cost values
     */
    currency: 'USD';

    input_cost: number;

    output_cost: number;

    total_cost: number;

    cache_creation_cost?: number;

    cache_read_cost?: number;

    tool_calls_cost?: number;
  }

  export interface InputTokensDetails {
    cache_creation_input_tokens?: number;

    cache_read_input_tokens?: number;
  }

  export interface ToolCallsDetails {
    /**
     * Number of times this tool was invoked
     */
    invocation?: number;
  }
}

/**
 * Non-streaming response returned when stream is false
 */
export interface ResponseCreateResponse {
  id: string;

  created_at: number;

  model: string;

  /**
   * Object type in API responses
   */
  object: 'response';

  output: Array<OutputItem>;

  /**
   * Status of a response or output item
   */
  status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

  /**
   * Whether the response was created in background mode.
   */
  background?: boolean;

  error?: ErrorInfo;

  usage?: ResponsesUsage;

  /**
   * Convenience property that aggregates all `output_text` items from the `output` list.
   * If no `output_text` content blocks exist, then an empty string is returned.
   */
  output_text?: string;
}

/**
 * Non-streaming response returned when stream is false
 */
export interface ResponseRetrieveResponse {
  id: string;

  created_at: number;

  model: string;

  /**
   * Object type in API responses
   */
  object: 'response';

  output: Array<OutputItem>;

  /**
   * Status of a response or output item
   */
  status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action';

  /**
   * Whether the response was created in background mode.
   */
  background?: boolean;

  error?: ErrorInfo;

  usage?: ResponsesUsage;

  /**
   * Convenience property that aggregates all `output_text` items from the `output` list.
   * If no `output_text` content blocks exist, then an empty string is returned.
   */
  output_text?: string;
}

export type ResponseCreateParams = ResponseCreateParamsNonStreaming | ResponseCreateParamsStreaming;

export interface ResponseCreateParamsBase {
  /**
   * Input content - either a string or array of input items
   */
  input: string | Array<InputItem>;

  /**
   * Run the response asynchronously. When true, the request is queued and the
   * response object's `status` will be `queued` or `in_progress`. Poll GET
   * /v1/responses/{response_id} to retrieve the final result.
   */
  background?: boolean | null;

  /**
   * System instructions for the model
   */
  instructions?: string;

  /**
   * ISO 639-1 language code for response language
   */
  language_preference?: string;

  /**
   * Maximum tokens to generate
   */
  max_output_tokens?: number;

  /**
   * Maximum number of research loop steps. If provided, overrides the preset's
   * max_steps value. Must be >= 1 if specified. Maximum allowed is 10.
   */
  max_steps?: number;

  /**
   * Model ID in provider/model format (e.g., "xai/grok-4-1", "openai/gpt-4o"). If
   * models is also provided, models takes precedence. Required if neither models nor
   * preset is provided.
   */
  model?: string;

  /**
   * Model fallback chain. Each model is in provider/model format. Models are tried
   * in order until one succeeds. Max 5 models allowed. If set, takes precedence over
   * single model field. The response.model will reflect the model that actually
   * succeeded.
   */
  models?: Array<string>;

  /**
   * Preset configuration name (e.g., "sonar-pro", "sonar-reasoning"). Pre-configured
   * model with system prompt and search parameters. Required if model is not
   * provided.
   */
  preset?: string;

  reasoning?: ResponseCreateParams.Reasoning;

  /**
   * Specifies the desired output format for the model response
   */
  response_format?: Shared.ResponseFormat;

  /**
   * If true, returns SSE stream instead of JSON
   */
  stream?: boolean;

  /**
   * Tools available to the model
   */
  tools?: Array<
    | ResponseCreateParams.WebSearchTool
    | ResponseCreateParams.FetchURLTool
    | ResponseCreateParams.PeopleSearchTool
    | FunctionTool
    | ResponseCreateParams.FinanceSearchTool
    | ResponseCreateParams.SandboxTool
    | ResponseCreateParams.McpTool
  >;
}

export namespace ResponseCreateParams {
  export interface Reasoning {
    /**
     * How much effort the model should spend on reasoning
     */
    effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
  }

  export interface WebSearchTool {
    type: 'web_search';

    filters?: WebSearchTool.Filters;

    max_tokens?: number;

    max_tokens_per_page?: number;

    /**
     * Search context size (low, medium, high). Omit when supplying explicit max_tokens
     * / max_tokens_per_page.
     */
    search_context_size?: 'low' | 'medium' | 'high';

    /**
     * User's geographic location for search personalization
     */
    user_location?: WebSearchTool.UserLocation;
  }

  export namespace WebSearchTool {
    export interface Filters {
      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      last_updated_after_filter?: string;

      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      last_updated_before_filter?: string;

      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      search_after_date_filter?: string;

      /**
       * Input: MM/DD/YYYY, Output: YYYY-MM-DD
       */
      search_before_date_filter?: string;

      search_domain_filter?: Array<string>;

      search_recency_filter?: 'hour' | 'day' | 'week' | 'month' | 'year';
    }

    /**
     * User's geographic location for search personalization
     */
    export interface UserLocation {
      city?: string;

      /**
       * ISO 3166-1 alpha-2 country code
       */
      country?: string;

      latitude?: number;

      longitude?: number;

      region?: string;
    }
  }

  export interface FetchURLTool {
    type: 'fetch_url';

    /**
     * Maximum number of URLs to fetch per tool call
     */
    max_urls?: number;
  }

  export interface PeopleSearchTool {
    /**
     * Enables the `people_search` tool.
     */
    type: 'people_search';
  }

  export interface FinanceSearchTool {
    /**
     * Enables the `finance_search` tool. The model can request structured financial
     * data (quotes, financials, segments, earnings transcripts, etc.) via
     * category-based fan-out to FMP, Finchat, and Quartr.
     */
    type: 'finance_search';
  }

  export interface SandboxTool {
    /**
     * Enables the `sandbox` tool. The model can execute code in an isolated container
     * during the request and use the result in its final answer.
     */
    type: 'sandbox';
  }

  /**
   * Connects a user-supplied remote MCP server. The worker discovers the server's
   * tools at boot and calls them like native tools. Matches OpenAI's mcp tool.
   * `require_approval`, `connector_id`, and `defer_loading` are not supported in v1
   * and are ignored if sent: every call auto-runs, and only bring-your-own
   * `server_url` is honored.
   */
  export interface McpTool {
    /**
     * Unique per request, ^[a-zA-Z0-9_-]{1,64}$. Namespaces the server's tools.
     */
    server_label: string;

    /**
     * HTTPS URL of the remote MCP server.
     */
    server_url: string;

    type: 'mcp';

    /**
     * Optional allowlist of tool names. Empty exposes all discovered tools.
     */
    allowed_tools?: Array<string>;

    /**
     * An OAuth access token that can be used with a remote MCP server, with a custom
     * MCP server URL. Never logged or echoed.
     */
    authorization?: string;

    /**
     * Extra request headers. Never logged or echoed.
     */
    headers?: { [key: string]: string };
  }

  export type ResponseCreateParamsNonStreaming = ResponsesAPI.ResponseCreateParamsNonStreaming;
  export type ResponseCreateParamsStreaming = ResponsesAPI.ResponseCreateParamsStreaming;
}

export interface ResponseCreateParamsNonStreaming extends ResponseCreateParamsBase {
  /**
   * If true, returns SSE stream instead of JSON
   */
  stream?: false;
}

export interface ResponseCreateParamsStreaming extends ResponseCreateParamsBase {
  /**
   * If true, returns SSE stream instead of JSON
   */
  stream: true;
}

Responses.Files = Files;

export declare namespace Responses {
  export {
    type Annotation as Annotation,
    type ContentPart as ContentPart,
    type ErrorInfo as ErrorInfo,
    type FunctionCallOutputItem as FunctionCallOutputItem,
    type FunctionTool as FunctionTool,
    type InputItem as InputItem,
    type OutputItem as OutputItem,
    type ResponseFile as ResponseFile,
    type ResponseFileList as ResponseFileList,
    type ResponseStreamChunk as ResponseStreamChunk,
    type ResponsesCreateParams as ResponsesCreateParams,
    type ResponsesUsage as ResponsesUsage,
    type ResponseCreateResponse as ResponseCreateResponse,
    type ResponseRetrieveResponse as ResponseRetrieveResponse,
    type ResponseCreateParams as ResponseCreateParams,
    type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming,
    type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming,
  };

  export { Files as Files, type FileContentParams as FileContentParams };
}