@pipedog/openai 0.0.0 → 0.3.0

package/dist/responses/index.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/responses/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/services/openai/responses/__init__.py
+// Upstream's package __init__ is empty: import the submodules directly.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/responses/llm.d.ts

@@ -0,0 +1,448 @@
+import type { BaseLLMAdapter } from "@pipedog/core/adapters/base_llm_adapter";
+import { type OpenAINotGiven } from "@pipedog/core/adapters/services/open_ai_adapter";
+import { type Frame, FunctionCallFromLLM } from "@pipedog/core/frames/frames";
+import type { LLMContext } from "@pipedog/core/processors/aggregators/llm_context";
+import type { FrameDirection } from "@pipedog/core/processors/frame_processor";
+import { LLMService, type LLMServiceOptions, WebsocketLLMService, type WebsocketLLMServiceOptions } from "@pipedog/core/services/llm_service";
+import { LLMSettings, type LLMSettingsOptions } from "@pipedog/core/services/settings";
+import { type Ctor } from "@pipedog/core/utils/mixin";
+import { type NotGiven } from "@pipedog/core/utils/types";
+import OpenAI from "openai";
+import { OpenAIResponsesLLMAdapter, type OpenAIResponsesLLMInvocationParams } from "../open_ai_responses_adapter.ts";
+type Dict = Record<string, any>;
+type ResponsesAdapter = OpenAIResponsesLLMAdapter & BaseLLMAdapter;
+/** Base for errors that should trigger a retry in `_processContext`. */
+export declare class _RetryableError extends Error {
+    name: string;
+}
+/** Server could not find the previous response (connection-local cache miss). */
+export declare class _PreviousResponseNotFoundError extends _RetryableError {
+    name: string;
+}
+/** WebSocket connection hit the 60-minute server-side limit. */
+export declare class _ConnectionLimitReachedError extends _RetryableError {
+    name: string;
+}
+/** Response did not begin producing output within the retry timeout. */
+export declare class _ResponseTimeoutError extends _RetryableError {
+    name: string;
+}
+export interface OpenAIResponsesReasoningConfigOptions {
+    /** How much reasoning effort the model applies. */
+    effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | string | null;
+    /** Verbosity of the reasoning summary to return. */
+    summary?: "auto" | "concise" | "detailed" | string | null;
+    /** Reasoning mode for models that offer one: "standard" or "pro". */
+    mode?: "standard" | "pro" | string | null;
+}
+/**
+ * Reasoning configuration for reasoning-capable OpenAI Responses models.
+ *
+ * Only reasoning-capable models use this — the mainline gpt series from gpt-5
+ * onward and the o-series. The service's default model, `gpt-4.1`, does not
+ * reason, so this config has no effect there; select a reasoning-capable model
+ * to use it. See OpenAI's reasoning guide
+ * (https://platform.openai.com/docs/guides/reasoning) and model list
+ * (https://platform.openai.com/docs/models) to choose one and to check which
+ * effort levels it accepts.
+ *
+ * Reasoning models use internal reasoning tokens before producing a response.
+ * This controls how much reasoning they do and whether a human-readable
+ * summary of it is returned.
+ *
+ * - `effort`: how much reasoning effort the model applies. `null` (the
+ *   default) leaves the field unset, so the model's own default applies;
+ *   `"none"` disables reasoning for latency-sensitive use and `"max"` applies
+ *   the model's deepest reasoning. At lower efforts (e.g. `"low"`) the model
+ *   reasons only when a turn calls for it, so simple prompts may produce no
+ *   summary at all.
+ * - `summary`: verbosity of the reasoning summary to return. `null` (the
+ *   default) requests no summary. Any summary is surfaced via thought frames
+ *   (the `on_assistant_thought` event); the encrypted reasoning itself is
+ *   preserved across turns regardless of this setting.
+ * - `mode`: reasoning mode for models that offer one, such as the gpt-5.6
+ *   series: `"standard"` or the slower, more thorough `"pro"`. `null` (the
+ *   default) leaves the field unset, so the model's own default applies.
+ *   `effort` selects the reasoning intensity within the chosen mode.
+ */
+export declare class OpenAIResponsesReasoningConfig {
+    effort: string | null;
+    summary: string | null;
+    mode: string | null;
+    constructor(options?: OpenAIResponsesReasoningConfigOptions);
+    /**
+     * The config as a dict of its wire fields (pydantic's `model_dump`).
+     *
+     * @param options.excludeNone Leave out fields whose value is `null`.
+     */
+    modelDump(options?: {
+        excludeNone?: boolean;
+    }): Record<string, string | null>;
+}
+export interface OpenAIResponsesLLMSettingsOptions extends LLMSettingsOptions {
+    /** Maximum completion tokens to generate. */
+    maxCompletionTokens?: number | NotGiven | OpenAINotGiven;
+    /** Reasoning configuration for reasoning-capable models. */
+    reasoning?: OpenAIResponsesReasoningConfig | null | NotGiven;
+}
+/**
+ * Settings for OpenAI Responses API LLM services.
+ *
+ * - `maxCompletionTokens`: maximum completion tokens to generate.
+ * - `reasoning`: reasoning configuration for reasoning-capable models. `null`
+ *   (the default) leaves reasoning unconfigured: the service then sends the
+ *   lowest effort OpenAI documents for the model, for the fastest responses,
+ *   and logs what it sent. Models Pipecat doesn't list, and any model when
+ *   `useProviderThinkingDefault` is set, run at OpenAI's default. The default
+ *   model, `gpt-4.1`, does not reason.
+ *
+ * The inherited `temperature` and `topP` fields also hold the OpenAI SDK's
+ * sentinel (`OPENAI_NOT_GIVEN`), which the service stores so these fields
+ * can be passed through unchanged to the client.
+ */
+export declare class OpenAIResponsesLLMSettings extends LLMSettings {
+    maxCompletionTokens: number | NotGiven | OpenAINotGiven;
+    reasoning: OpenAIResponsesReasoningConfig | null | NotGiven;
+    constructor(options?: OpenAIResponsesLLMSettingsOptions);
+}
+/** Whether the model is an o-series reasoning model (o1, o3, o4-mini, ...). */
+export declare function _isOSeries(model: string): boolean;
+export declare const _THINKING_DEFAULTS: Readonly<Record<string, string>>;
+/**
+ * The name a model id refers to, the key it's looked up by in
+ * `_THINKING_DEFAULTS`.
+ *
+ * A dated snapshot (`gpt-5-2025-08-07`) gets its model's entry.
+ */
+export declare function _modelName(model: string): string;
+/**
+ * Classify whether an OpenAI model supports reasoning.
+ *
+ * Assumes that future (beyond gpt-5.x) mainline gpt series models will also
+ * support reasoning. This can be revisited if OpenAI changes their model
+ * lineup or reasoning support in the future.
+ *
+ * @param model The model name (e.g. `"gpt-5.4"`, `"o3"`, `"gpt-4.1"`).
+ * @returns `true` for reasoning-capable models — the o-series and the
+ *   mainline gpt series from gpt-5 onward. `false` for models known *not* to
+ *   reason: gpt-4.x and earlier, and the `gpt-5-chat` non-reasoning variant.
+ *   `null` when the model is unrecognized and we can't tell either way.
+ */
+export declare function _modelSupportsReasoning(model: string): boolean | null;
+/** Options for creating the AsyncOpenAI client. */
+export interface OpenAIResponsesClientOptions {
+    /** OpenAI API key. */
+    apiKey?: string | null;
+    /** Custom base URL for the API. */
+    baseUrl?: string | null;
+    /** OpenAI organization ID. */
+    organization?: string | null;
+    /** OpenAI project ID. */
+    project?: string | null;
+    /** Additional HTTP headers. */
+    defaultHeaders?: Record<string, string> | null;
+}
+export interface BaseOpenAIResponsesLLMServiceOptions extends LLMServiceOptions, OpenAIResponsesClientOptions {
+    /**
+     * Service tier to use: "auto", "default", "flex", "scale", "fast",
+     * "priority" or "ultrafast". "fast" is OpenAI's low-latency tier, the name
+     * that replaced "priority"; both values are accepted. "ultrafast" is the
+     * access-controlled Ultrafast Processing tier, which shortens the time
+     * between output tokens on the models that offer it.
+     */
+    serviceTier?: string | null;
+    /** Runtime-updatable settings. */
+    settings?: OpenAIResponsesLLMSettings | null;
+    /**
+     * How long an inference may go without producing output before it is
+     * abandoned and re-issued, when `retryOnTimeout` is set. Defaults to 5.0
+     * seconds.
+     */
+    retryTimeoutSecs?: number | null;
+    /**
+     * Whether to re-issue the request once if the first attempt produces no
+     * output within `retryTimeoutSecs`. The retry is unbounded.
+     */
+    retryOnTimeout?: boolean | null;
+}
+/** Accumulated data for one function call: name, call_id and arguments. */
+export interface ResponsesFunctionCallData {
+    name: string;
+    call_id: string;
+    arguments: string;
+}
+/** Members a class gets from `BaseOpenAIResponsesLLMServiceMixin`. */
+export interface BaseOpenAIResponsesLLMServiceMembers {
+    _apiKey: string | null;
+    _serviceTier: string | null;
+    _retryTimeoutSecs: number | null;
+    _retryOnTimeout: boolean | null;
+    _reasoningUnsupportedWarnedFor: string | null;
+    _client: OpenAI;
+    _fullModelName: string | null;
+    _createClient(options?: OpenAIResponsesClientOptions): OpenAI;
+    canGenerateMetrics(): boolean;
+    _buildResponseParams(invocationParams: OpenAIResponsesLLMInvocationParams): Dict;
+    runInference(context: LLMContext, options?: {
+        maxTokens?: number | null;
+        systemInstruction?: string | null;
+        responseSchema?: Record<string, unknown> | null;
+    }): Promise<string | null>;
+    _processFunctionCalls(context: LLMContext, functionCalls: Map<string, ResponsesFunctionCallData>): FunctionCallFromLLM[];
+    _maybeApplyThinkingDefault(params: Dict): void;
+    _warnIfReasoningUnsupported(): void;
+    _appendReasoningMessage(itemId: string | null, summary: Dict[], encryptedContent: string | null): Promise<void>;
+}
+/** Static members a class gets from `BaseOpenAIResponsesLLMServiceMixin`. */
+export interface BaseOpenAIResponsesLLMServiceStatics {
+    Settings: typeof OpenAIResponsesLLMSettings;
+    ReasoningConfig: typeof OpenAIResponsesReasoningConfig;
+    supportsResponseSchema: boolean;
+    modelSupportsResponseSchema(model: string): boolean;
+}
+/**
+ * Shared base for HTTP and WebSocket OpenAI Responses API services.
+ *
+ * Contains settings, adapter reference, HTTP client creation, parameter
+ * building, `runInference`, and metrics support. Subclasses implement
+ * `processFrame` and `_processContext` for their transport.
+ *
+ * A mixin over an `LLMService` base: upstream's
+ * `class OpenAIResponsesLLMService(_BaseOpenAIResponsesLLMService, WebsocketLLMService)`
+ * is `class OpenAIResponsesLLMService extends BaseOpenAIResponsesLLMServiceMixin(WebsocketLLMService)`.
+ */
+export declare const BaseOpenAIResponsesLLMServiceMixin: import("@pipedog/core/utils/mixin").Mixin<<B extends Ctor>(base: B) => B & Ctor<BaseOpenAIResponsesLLMServiceMembers> & BaseOpenAIResponsesLLMServiceStatics, BaseOpenAIResponsesLLMServiceMembers>;
+declare const _BaseOpenAIResponsesLLMService_base: typeof LLMService & Ctor<BaseOpenAIResponsesLLMServiceMembers> & BaseOpenAIResponsesLLMServiceStatics;
+/**
+ * Shared base for HTTP and WebSocket OpenAI Responses API services, as a
+ * plain class over `LLMService` (see `BaseOpenAIResponsesLLMServiceMixin`).
+ */
+export declare class _BaseOpenAIResponsesLLMService extends _BaseOpenAIResponsesLLMService_base<ResponsesAdapter> {
+    protected _settings: OpenAIResponsesLLMSettings;
+    constructor(options?: BaseOpenAIResponsesLLMServiceOptions);
+}
+export interface OpenAIResponsesLLMServiceOptions extends BaseOpenAIResponsesLLMServiceOptions, WebsocketLLMServiceOptions {
+    /** Runtime-updatable settings. */
+    settings?: OpenAIResponsesLLMSettings | null;
+    /** WebSocket endpoint URL. Defaults to `wss://api.openai.com/v1/responses`. */
+    wsUrl?: string;
+}
+declare const OpenAIResponsesLLMService_base: typeof WebsocketLLMService & Ctor<BaseOpenAIResponsesLLMServiceMembers> & BaseOpenAIResponsesLLMServiceStatics;
+/**
+ * OpenAI Responses API LLM service using WebSocket transport.
+ *
+ * Maintains a persistent WebSocket connection to
+ * `wss://api.openai.com/v1/responses` for lower-latency inference, especially
+ * beneficial for tool-call-heavy workflows. Automatically uses
+ * `previous_response_id` to send only incremental context when possible, and
+ * falls back to full context on reconnection or cache miss.
+ *
+ * The `previous_response_id` optimization works with `store=false` (the
+ * default) because WebSocket mode uses a connection-local in-memory cache —
+ * no conversations are stored on OpenAI's servers. This is why the HTTP
+ * variant (`OpenAIResponsesHttpLLMService`) does not offer this optimization
+ * by default (or at all, yet): over HTTP, `previous_response_id` requires
+ * `store=true`, which enables OpenAI-side 30-day conversation storage.
+ *
+ * This is the recommended variant for real-time / conversational use.
+ *
+ * @example
+ * const llm = new OpenAIResponsesLLMService({
+ *   apiKey: getEnv("OPENAI_API_KEY"),
+ *   settings: new OpenAIResponsesLLMService.Settings({
+ *     systemInstruction: "You are a helpful assistant.",
+ *   }),
+ * });
+ */
+export declare class OpenAIResponsesLLMService extends OpenAIResponsesLLMService_base<ResponsesAdapter> {
+    protected _settings: OpenAIResponsesLLMSettings;
+    protected _wsUrl: string;
+    protected _previousResponseId: string | null;
+    protected _previousInputHash: string | null;
+    protected _previousInputLength: number | null;
+    protected _previousResponseOutput: Dict[] | null;
+    protected _currentResponseId: string | null;
+    protected _cancelPendingResponse: boolean;
+    protected _needsDrain: boolean;
+    /**
+     * Initialize the WebSocket-based OpenAI Responses API LLM service.
+     *
+     * @param options.wsUrl WebSocket endpoint URL. Defaults to
+     *   `wss://api.openai.com/v1/responses`.
+     *   Other options are passed to the base class (apiKey, baseUrl,
+     *   organization, project, defaultHeaders, serviceTier, settings, etc.).
+     */
+    constructor(options?: OpenAIResponsesLLMServiceOptions);
+    /** Establish the WebSocket connection. */
+    _connectWebsocket(): Promise<void>;
+    /** Close the WebSocket connection and clear state. */
+    _disconnectWebsocket(): Promise<void>;
+    /** Release resources at teardown. */
+    cleanup(): Promise<void>;
+    /**
+     * Compute a deterministic hash of input items for comparison.
+     *
+     * @param items List of Responses API input items.
+     * @returns Hex digest of the SHA-256 hash.
+     */
+    static _hashInputItems(items: unknown[]): Promise<string>;
+    /**
+     * Try to use previous_response_id to send only new input items.
+     *
+     * If the prefix of `fullInput` matches the stored hash from the previous
+     * inference call, only new items are sent along with
+     * `previous_response_id`. Otherwise the full input is sent.
+     *
+     * @param params The response params dict (modified in place).
+     * @param fullInput The complete input items list from the adapter.
+     * @returns The (possibly modified) params dict.
+     */
+    protected _applyPreviousResponseOptimization(params: Dict, fullInput: Dict[]): Promise<Dict>;
+    /**
+     * Check whether `items` begins with entries that match `responseOutput`.
+     *
+     * When using `previous_response_id`, the server already knows its own
+     * output. After confirming that the input prefix matches what we
+     * previously sent, this method checks whether the items immediately
+     * following that prefix correspond to the server's response output. If
+     * they do, those items can be skipped so we send only the truly new items
+     * (user messages, tool results, etc.).
+     *
+     * For messages, the comparison checks role and text content (extracting
+     * text from the output's `output_text` content parts and comparing against
+     * the input's content). For function calls, it matches by `call_id`. This
+     * avoids requiring exact format equality while still confirming the items
+     * represent the same data. If the match fails for any reason, the caller
+     * falls back to sending the full context.
+     *
+     * @param items The input items following the matched prefix.
+     * @param responseOutput Raw `output` array from the previous
+     *   `response.completed` event.
+     * @returns True if the leading items correspond to the response output.
+     */
+    static _startsWithResponseOutput(items: Dict[], responseOutput: Dict[]): boolean;
+    /**
+     * Store state for the next call's previous_response_id optimization.
+     *
+     * @param responseId The response ID returned by the server.
+     * @param fullInput The complete input items list that was sent.
+     * @param responseOutput Raw `output` array from the `response.completed`
+     *   event, stored for loose comparison on the next call.
+     */
+    protected _storePreviousResponseState(responseId: string, fullInput: Dict[], responseOutput: Dict[]): Promise<void>;
+    /** Clear stored previous_response_id state. */
+    protected _clearPreviousResponseState(): void;
+    /** Clear response cancellation tracking state. */
+    protected _clearCancellationState(): void;
+    /**
+     * Drain events from a cancelled response before starting a new one.
+     *
+     * After a cancellation, the WebSocket may still have in-flight events from
+     * the cancelled response. We must drain them before sending a new
+     * `response.create` — we can't simply filter them inline because the API
+     * doesn't provide a reliable way to correlate events to a specific
+     * response (e.g. delta events carry neither a `response_id` nor any
+     * intermediary identifier that could be traced back to one).
+     *
+     * This method reads and discards events until a terminal event
+     * (`response.completed`, `response.failed`, or `response.incomplete`)
+     * arrives, ensuring the connection is clean. If draining times out or the
+     * connection drops, clears cancellation state and returns —
+     * `_ensureConnected` will handle reconnection before the next inference.
+     */
+    protected _drainCancelledResponse(): Promise<void>;
+    /**
+     * Process frames for LLM completion requests.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /**
+     * Run inference over WebSocket with retry and previous_response_id.
+     *
+     * Tries once with the `previous_response_id` optimization. On a retriable
+     * error (cache miss, connection limit, connection drop, or — when
+     * `retryOnTimeout` is set — a response that produces no output in time),
+     * clears state and retries once with the full context and no timeout.
+     * Transport-level `ConnectionClosed` errors are handled transparently by
+     * `_wsSend`/`_wsRecv` (auto-reconnect → `WebsocketReconnectedError`).
+     *
+     * Traced with `tracedLlm` (see the static block).
+     *
+     * @param context The LLM context containing conversation history.
+     */
+    protected _processContext(context: LLMContext): Promise<void>;
+    /** Report the token usage of a response received over the WebSocket. */
+    protected _reportEventUsage(usage: Dict | null | undefined): Promise<void>;
+    /**
+     * Receive and process WebSocket events until the response completes.
+     *
+     * @param context The LLM context for the current inference.
+     * @param fullInput The complete input items list (for storing state on
+     *   success).
+     * @param outputTimeoutSecs How long to wait for the response to start
+     *   producing output before raising `_ResponseTimeoutError`. Once the first
+     *   output event arrives the wait becomes unbounded, since by then content
+     *   is already on its way downstream and re-issuing would duplicate it.
+     *   null waits indefinitely throughout.
+     * @throws _PreviousResponseNotFoundError Server couldn't find previous response.
+     * @throws _ConnectionLimitReachedError 60-minute connection limit reached.
+     * @throws _ResponseTimeoutError Response produced no output in time.
+     * @throws WebsocketReconnectedError Connection was lost and auto-recovered.
+     * @throws ConnectionClosed Connection was lost and could not be recovered.
+     */
+    protected _receiveResponseEvents(context: LLMContext, fullInput: Dict[], outputTimeoutSecs?: number | null): Promise<void>;
+}
+/** A streamed Responses API event (`openai.types.responses.ResponseStreamEvent`). */
+export type ResponseStreamEvent = OpenAI.Responses.ResponseStreamEvent;
+/** A Responses API usage (`openai.types.responses.ResponseUsage`). */
+export type ResponseUsage = OpenAI.Responses.ResponseUsage;
+/** The async stream of events returned by a streaming Responses API call. */
+export type ResponseStream = AsyncIterable<ResponseStreamEvent> & {
+    controller?: AbortController;
+};
+/**
+ * OpenAI Responses API LLM service using HTTP streaming transport.
+ *
+ * Uses server-sent events (SSE) via the OpenAI SDK for streaming inference.
+ * Each `_processContext` call opens a new HTTP connection.
+ *
+ * Unlike the WebSocket variant, this service does not use
+ * `previous_response_id` for incremental context delivery by default (or at
+ * all, yet). Over HTTP, `previous_response_id` requires `store=true`, which
+ * enables OpenAI-side 30-day conversation storage — a privacy/compliance
+ * tradeoff that many users won't want. The WebSocket variant avoids this
+ * because its `previous_response_id` uses a connection-local in-memory cache
+ * that works with `store=false` (nothing is stored long-term).
+ *
+ * @example
+ * const llm = new OpenAIResponsesHttpLLMService({
+ *   apiKey: getEnv("OPENAI_API_KEY"),
+ *   settings: new OpenAIResponsesHttpLLMService.Settings({
+ *     systemInstruction: "You are a helpful assistant.",
+ *   }),
+ * });
+ */
+export declare class OpenAIResponsesHttpLLMService extends _BaseOpenAIResponsesLLMService {
+    /**
+     * Process frames for LLM completion requests.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /** Report a response's token usage, if it carries any. */
+    protected _reportUsage(usage: ResponseUsage | null | undefined): Promise<void>;
+    /**
+     * Open a streaming Responses API request, retrying once on timeout.
+     *
+     * @param params Parameters for the Responses API call.
+     * @returns Async stream of response events.
+     */
+    protected _createStream(params: Dict): Promise<ResponseStream>;
+    /** Traced with `tracedLlm` (see the static block). */
+    protected _processContext(context: LLMContext): Promise<void>;
+}
+export {};
+//# sourceMappingURL=llm.d.ts.map