From 89150a4b2e50b2709b6e2489a74776b7e95c1f04 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 18:02:25 +0000 Subject: [PATCH 1/2] feat(responses): add files subresource for sandbox file retrieval --- .stats.yml | 8 +- api.md | 37 +- src/client.ts | 14 +- src/resources/index.ts | 4 +- src/resources/responses.ts | 1260 +--------------- src/resources/responses/files.ts | 42 + src/resources/responses/index.ts | 23 + src/resources/responses/responses.ts | 1316 +++++++++++++++++ tests/api-resources/responses/files.test.ts | 27 + .../{ => responses}/responses.test.ts | 0 10 files changed, 1448 insertions(+), 1283 deletions(-) create mode 100644 src/resources/responses/files.ts create mode 100644 src/resources/responses/index.ts create mode 100644 src/resources/responses/responses.ts create mode 100644 tests/api-resources/responses/files.test.ts rename tests/api-resources/{ => responses}/responses.test.ts (100%) diff --git a/.stats.yml b/.stats.yml index 485fba7..abe6bc3 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -configured_endpoints: 11 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-bf28ac7f1a24d27aa2ba57b65aaf7fc99f492d28ab969f570d86abc339c842e9.yml -openapi_spec_hash: 2f086349fe584965e24e58bddbb91672 -config_hash: 059988c88f0dc18e9e393daed94b5eb6 +configured_endpoints: 13 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-6a9e741f72f36fa6c1f8ece842ba1616376107badbfdeaf6e88c5db7b9412437.yml +openapi_spec_hash: 76d7c6e6e7f84a1de30b869a7579e6b6 +config_hash: 3f1487a29a16f85810ba4d77134da232 diff --git a/api.md b/api.md index 2231022..a246159 100644 --- a/api.md +++ b/api.md @@ -43,23 +43,32 @@ Methods: Types: -- Annotation -- ContentPart -- ErrorInfo -- FunctionCallOutputItem -- FunctionTool -- InputItem -- OutputItem -- ResponseStreamChunk -- ResponsesCreateParams -- ResponsesUsage -- ResponseCreateResponse -- ResponseRetrieveResponse +- Annotation +- ContentPart +- ErrorInfo +- FunctionCallOutputItem +- FunctionTool +- InputItem +- OutputItem +- ResponseFile +- ResponseFileList +- ResponseStreamChunk +- ResponsesCreateParams +- ResponsesUsage +- ResponseCreateResponse +- ResponseRetrieveResponse Methods: -- client.responses.create({ ...params }) -> ResponseCreateResponse -- client.responses.retrieve(responseID) -> ResponseRetrieveResponse +- client.responses.create({ ...params }) -> ResponseCreateResponse +- client.responses.retrieve(responseID) -> ResponseRetrieveResponse + +## Files + +Methods: + +- client.responses.files.list(responseID) -> ResponseFileList +- client.responses.files.content(fileID, { ...params }) -> Response # Embeddings diff --git a/src/client.ts b/src/client.ts index 5ff98d5..6349fad 100644 --- a/src/client.ts +++ b/src/client.ts @@ -23,6 +23,10 @@ import { ContextualizedEmbeddings, } from './resources/contextualized-embeddings'; import { EmbeddingCreateParams, EmbeddingCreateResponse, Embeddings } from './resources/embeddings'; +import { Search, SearchCreateParams, SearchCreateResponse } from './resources/search'; +import { Async } from './resources/async/async'; +import { Browser } from './resources/browser/browser'; +import { Chat, StreamChunk } from './resources/chat/chat'; import { Annotation, ContentPart, @@ -35,16 +39,14 @@ import { ResponseCreateParamsNonStreaming, ResponseCreateParamsStreaming, ResponseCreateResponse, + ResponseFile, + ResponseFileList, ResponseRetrieveResponse, ResponseStreamChunk, Responses, ResponsesCreateParams, ResponsesUsage, -} from './resources/responses'; -import { Search, SearchCreateParams, SearchCreateResponse } from './resources/search'; -import { Async } from './resources/async/async'; -import { Browser } from './resources/browser/browser'; -import { Chat, StreamChunk } from './resources/chat/chat'; +} from './resources/responses/responses'; import { type Fetch } from './internal/builtin-types'; import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers'; import { FinalRequestOptions, RequestOptions } from './internal/request-options'; @@ -796,6 +798,8 @@ export declare namespace Perplexity { 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, diff --git a/src/resources/index.ts b/src/resources/index.ts index 15f32b6..71fdeb5 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -19,6 +19,8 @@ export { type FunctionTool, type InputItem, type OutputItem, + type ResponseFile, + type ResponseFileList, type ResponseStreamChunk, type ResponsesCreateParams, type ResponsesUsage, @@ -27,5 +29,5 @@ export { type ResponseCreateParams, type ResponseCreateParamsNonStreaming, type ResponseCreateParamsStreaming, -} from './responses'; +} from './responses/responses'; export { Search, type SearchCreateResponse, type SearchCreateParams } from './search'; diff --git a/src/resources/responses.ts b/src/resources/responses.ts index 21c4e1d..9d26aac 100644 --- a/src/resources/responses.ts +++ b/src/resources/responses.ts @@ -1,1261 +1,3 @@ // 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 { 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 { - /** - * Generate a response for the provided input with optional web search and - * reasoning. - */ - create( - body: ResponseCreateParamsNonStreaming, - options?: RequestOptions, - ): APIPromise; - create( - body: ResponseCreateParamsStreaming, - options?: RequestOptions, - ): APIPromise>; - create( - body: ResponseCreateParamsBase, - options?: RequestOptions, - ): APIPromise | ResponseCreateResponse>; - create( - body: ResponseCreateParams, - options?: RequestOptions, - ): APIPromise | APIPromise> { - 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)._thenUnwrap((rsp) => { - if ('object' in rsp && rsp.object === 'response') { - addOutputText(rsp as ResponseCreateResponse); - } - return rsp; - }) as APIPromise; - } - - return promise as APIPromise>; - } - - /** - * Retrieve a response by its ID. Use this to poll the status of background tasks. - */ - retrieve(responseID: string, options?: RequestOptions): APIPromise { - 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; -} - -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; - - 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; - } -} - -export type OutputItem = - | OutputItem.MessageOutputItem - | OutputItem.SearchResultsOutputItem - | OutputItem.FetchURLResultsOutputItem - | FunctionCallOutputItem; - -export namespace OutputItem { - export interface MessageOutputItem { - id: string; - - content: Array; - - /** - * 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; - - type: 'search_results'; - - queries?: Array; - } - - export interface FetchURLResultsOutputItem { - contents: Array; - - 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; - } - } -} - -/** - * 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; - - /** - * 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; - - /** - * 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; - - /** - * 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 { - 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 { - 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; - - /** - * 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; - - /** - * 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; - - thought?: string; - } - - /** - * URL fetch results event (type: "response.reasoning.fetch_url_results"). Contains - * fetched URL contents. - */ - export interface FetchURLResultsEvent { - contents: Array; - - /** - * 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; - - /** - * 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; - - /** - * 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 - >; -} - -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; - - 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'; - } -} - -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; - - /** - * 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; -} - -/** - * 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; - - /** - * 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; - - /** - * 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; - - /** - * 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 - >; -} - -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; - - 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'; - } - - 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; -} - -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 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 * from './responses/index'; diff --git a/src/resources/responses/files.ts b/src/resources/responses/files.ts new file mode 100644 index 0000000..085e1f5 --- /dev/null +++ b/src/resources/responses/files.ts @@ -0,0 +1,42 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import { APIResource } from '../../core/resource'; +import * as ResponsesAPI from './responses'; +import { APIPromise } from '../../core/api-promise'; +import { buildHeaders } from '../../internal/headers'; +import { RequestOptions } from '../../internal/request-options'; +import { path } from '../../internal/utils/path'; + +export class Files extends APIResource { + /** + * Lists the files the model delivered via the share_file tool during this + * response. + */ + list(responseID: string, options?: RequestOptions): APIPromise { + return this._client.get(path`/v1/responses/${responseID}/files`, options); + } + + /** + * Streams the raw bytes of one shared file. Content-Disposition carries the + * original filename. + */ + content(fileID: string, params: FileContentParams, options?: RequestOptions): APIPromise { + const { response_id } = params; + return this._client.get(path`/v1/responses/${response_id}/files/${fileID}/content`, { + ...options, + headers: buildHeaders([{ Accept: 'application/octet-stream' }, options?.headers]), + __binaryResponse: true, + }); + } +} + +export interface FileContentParams { + /** + * ID of the response (e.g., resp\_...). + */ + response_id: string; +} + +export declare namespace Files { + export { type FileContentParams as FileContentParams }; +} diff --git a/src/resources/responses/index.ts b/src/resources/responses/index.ts new file mode 100644 index 0000000..33fd829 --- /dev/null +++ b/src/resources/responses/index.ts @@ -0,0 +1,23 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +export { Files, type FileContentParams } from './files'; +export { + Responses, + type Annotation, + type ContentPart, + type ErrorInfo, + type FunctionCallOutputItem, + type FunctionTool, + type InputItem, + type OutputItem, + type ResponseFile, + type ResponseFileList, + type ResponseStreamChunk, + type ResponsesCreateParams, + type ResponsesUsage, + type ResponseCreateResponse, + type ResponseRetrieveResponse, + type ResponseCreateParams, + type ResponseCreateParamsNonStreaming, + type ResponseCreateParamsStreaming, +} from './responses'; diff --git a/src/resources/responses/responses.ts b/src/resources/responses/responses.ts new file mode 100644 index 0000000..495d832 --- /dev/null +++ b/src/resources/responses/responses.ts @@ -0,0 +1,1316 @@ +// 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; + create( + body: ResponseCreateParamsStreaming, + options?: RequestOptions, + ): APIPromise>; + create( + body: ResponseCreateParamsBase, + options?: RequestOptions, + ): APIPromise | ResponseCreateResponse>; + create( + body: ResponseCreateParams, + options?: RequestOptions, + ): APIPromise | APIPromise> { + 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)._thenUnwrap((rsp) => { + if ('object' in rsp && rsp.object === 'response') { + addOutputText(rsp as ResponseCreateResponse); + } + return rsp; + }) as APIPromise; + } + + return promise as APIPromise>; + } + + /** + * Retrieve a response by its ID. Use this to poll the status of background tasks. + */ + retrieve(responseID: string, options?: RequestOptions): APIPromise { + 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; +} + +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; + + 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; + } +} + +export type OutputItem = + | OutputItem.MessageOutputItem + | OutputItem.SearchResultsOutputItem + | OutputItem.FetchURLResultsOutputItem + | FunctionCallOutputItem; + +export namespace OutputItem { + export interface MessageOutputItem { + id: string; + + content: Array; + + /** + * 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; + + type: 'search_results'; + + queries?: Array; + } + + export interface FetchURLResultsOutputItem { + contents: Array; + + 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; + } + } +} + +/** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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 { + 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 { + 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; + + /** + * 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; + + /** + * 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; + + thought?: string; + } + + /** + * URL fetch results event (type: "response.reasoning.fetch_url_results"). Contains + * fetched URL contents. + */ + export interface FetchURLResultsEvent { + contents: Array; + + /** + * 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; + + /** + * 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; + + /** + * 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 + >; +} + +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; + + 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'; + } +} + +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; + + /** + * 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; + + /** + * 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; + + /** + * 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; + + /** + * 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 + >; +} + +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; + + 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'; + } + + 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 }; +} diff --git a/tests/api-resources/responses/files.test.ts b/tests/api-resources/responses/files.test.ts new file mode 100644 index 0000000..1909f89 --- /dev/null +++ b/tests/api-resources/responses/files.test.ts @@ -0,0 +1,27 @@ +// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import Perplexity from '@perplexity-ai/perplexity_ai'; + +const client = new Perplexity({ + apiKey: 'My API Key', + baseURL: process.env['TEST_API_BASE_URL'] ?? 'http://127.0.0.1:4010', +}); + +describe('resource files', () => { + // Mock server tests are disabled + test.skip('list', async () => { + const responsePromise = client.responses.files.list('response_id'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); + + // Mock server tests are disabled + test.skip('content: required and optional params', async () => { + const response = await client.responses.files.content('file_id', { response_id: 'response_id' }); + }); +}); diff --git a/tests/api-resources/responses.test.ts b/tests/api-resources/responses/responses.test.ts similarity index 100% rename from tests/api-resources/responses.test.ts rename to tests/api-resources/responses/responses.test.ts From 60af15ea1def1c5db19acddeb732e3ca3e18ac08 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Mon, 8 Jun 2026 18:02:46 +0000 Subject: [PATCH 2/2] release: 0.33.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4758222..53ecb86 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.32.0" + ".": "0.33.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index fffaacc..17fa235 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.33.0 (2026-06-08) + +Full Changelog: [v0.32.0...v0.33.0](https://github.com/perplexityai/perplexity-node/compare/v0.32.0...v0.33.0) + +### Features + +* **responses:** add files subresource for sandbox file retrieval ([89150a4](https://github.com/perplexityai/perplexity-node/commit/89150a4b2e50b2709b6e2489a74776b7e95c1f04)) + ## 0.32.0 (2026-06-02) Full Changelog: [v0.31.0...v0.32.0](https://github.com/perplexityai/perplexity-node/compare/v0.31.0...v0.32.0) diff --git a/package.json b/package.json index f9c65fc..9c3a905 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@perplexity-ai/perplexity_ai", - "version": "0.32.0", + "version": "0.33.0", "description": "The official TypeScript library for the Perplexity API", "author": "Perplexity ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index b413d15..dc173dd 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.32.0'; // x-release-please-version +export const VERSION = '0.33.0'; // x-release-please-version