@pipedog/openai 0.0.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2024–2026, Daily
+Copyright (c) 2026, pipedog contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/NOTICE

@@ -0,0 +1,9 @@
+pipedog is an unofficial TypeScript port of Pipecat (https://github.com/pipecat-ai/pipecat),
+a framework for voice and multimodal conversational AI created by Daily.
+
+It is not affiliated with or endorsed by Daily. Pipecat is distributed under
+the BSD 2-Clause License, Copyright (c) 2024–2026, Daily; that copyright notice
+and license are retained in LICENSE, and every ported source file carries a
+header naming the upstream file it was derived from.
+
+The upstream commit each file was ported from is recorded in porting/manifest.json.

package/dist/_constants.d.ts

@@ -0,0 +1,4 @@
+/** Internal constants for OpenAI service integrations. */
+export declare const OPENAI_SAMPLE_RATE = 24000;
+export declare const OPENAI_REALTIME_WHISPER_MODEL = "gpt-realtime-whisper";
+//# sourceMappingURL=_constants.d.ts.map

package/dist/_constants.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/services/openai/_constants.py
+/** Internal constants for OpenAI service integrations. */
+export const OPENAI_SAMPLE_RATE = 24000;
+export const OPENAI_REALTIME_WHISPER_MODEL = "gpt-realtime-whisper";
+//# sourceMappingURL=_constants.js.map

package/dist/base_llm.d.ts

@@ -0,0 +1,272 @@
+import { type BaseLLMAdapter } from "@pipedog/core/adapters/base_llm_adapter";
+import { type OpenAILLMAdapter, type OpenAILLMInvocationParams, type OpenAINotGiven } from "@pipedog/core/adapters/services/open_ai_adapter";
+import { type Frame } from "@pipedog/core/frames/frames";
+import { LLMTokenUsage } from "@pipedog/core/metrics/metrics";
+import type { LLMContext } from "@pipedog/core/processors/aggregators/llm_context";
+import type { FrameDirection } from "@pipedog/core/processors/frame_processor";
+import { LLMService, type LLMServiceOptions } from "@pipedog/core/services/llm_service";
+import { LLMSettings, type LLMSettingsOptions } from "@pipedog/core/services/settings";
+import { type NotGiven } from "@pipedog/core/utils/types";
+import OpenAI from "openai";
+/** A streamed chat completion chunk (`openai.types.chat.ChatCompletionChunk`). */
+export type ChatCompletionChunk = OpenAI.Chat.Completions.ChatCompletionChunk;
+/** A chat completion's usage (`openai.types.CompletionUsage`). */
+export type CompletionUsage = OpenAI.CompletionUsage;
+/** The async stream of chunks returned by a streaming chat completion. */
+export type ChatCompletionStream = AsyncIterable<ChatCompletionChunk> & {
+    controller?: AbortController;
+};
+export interface OpenAILLMSettingsOptions extends LLMSettingsOptions {
+    /** Maximum completion tokens to generate. */
+    maxCompletionTokens?: number | null | NotGiven | OpenAINotGiven;
+}
+/**
+ * Settings for BaseOpenAILLMService.
+ *
+ * - `maxCompletionTokens`: maximum completion tokens to generate.
+ *
+ * Upstream overrides the inherited sampling fields (`frequencyPenalty`,
+ * `presencePenalty`, `seed`, `temperature`, `topP`, `maxTokens`) to also
+ * accept the OpenAI SDK's sentinel, which the service stores there so those
+ * fields can be passed through unchanged to the client. The SDK's sentinel is
+ * `undefined` here, which TypeScript can't add to an inherited field's type;
+ * the service writes it with `setOpenAINotGiven()`.
+ */
+export declare class OpenAILLMSettings extends LLMSettings {
+    maxCompletionTokens: number | null | NotGiven | OpenAINotGiven;
+    constructor(options?: OpenAILLMSettingsOptions);
+}
+/** The settings fields that hold the OpenAI SDK's sentinel when unset. */
+declare const OPENAI_SENTINEL_FIELDS: readonly ["frequencyPenalty", "presencePenalty", "seed", "temperature", "topP", "maxTokens", "maxCompletionTokens"];
+/**
+ * Store the OpenAI SDK's "not given" sentinel (`OPENAI_NOT_GIVEN`) in the
+ * given settings fields, so they are left out of requests.
+ *
+ * Options objects can't carry it (an `undefined` option means "not given" to
+ * Pipecat), so services set it after building their default settings.
+ *
+ * @param settings Store-mode settings to update in place.
+ * @param fields The fields to set. Defaults to every OpenAI sampling field.
+ */
+export declare function setOpenAINotGiven(settings: OpenAILLMSettings, fields?: readonly (typeof OPENAI_SENTINEL_FIELDS)[number][]): void;
+/**
+ * OpenAI models that predate strict JSON schema replies: gpt-3.5, gpt-4 and
+ * gpt-4-turbo, the first gpt-4o snapshot, chatgpt-4o and the o1 previews.
+ */
+export declare const OPENAI_MODEL_WITHOUT_RESPONSE_SCHEMA: RegExp;
+/** Options for `BaseOpenAILLMService.createClient()`. */
+export interface OpenAIClientOptions {
+    /** OpenAI API key. If null, the SDK reads `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 BaseOpenAILLMServiceOptions extends LLMServiceOptions, OpenAIClientOptions {
+    /** Service tier to use (e.g., "auto", "flex", "priority"). */
+    serviceTier?: string | null;
+    /**
+     * Runtime-updatable settings. When provided, its given fields override the
+     * service's defaults.
+     */
+    settings?: OpenAILLMSettings | 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;
+}
+/**
+ * Base class for all services that use the AsyncOpenAI client.
+ *
+ * This service consumes LLMContextFrame frames, which contain a reference to
+ * an LLMContext object. The context defines what is sent to the LLM for
+ * completion, including user, assistant, and system messages, as well as tool
+ * choices and function call configurations.
+ */
+type OpenAIAdapter = OpenAILLMAdapter & BaseLLMAdapter;
+export declare class BaseOpenAILLMService extends LLMService<OpenAIAdapter> {
+    static Settings: typeof OpenAILLMSettings;
+    protected _settings: OpenAILLMSettings;
+    /**
+     * Set by services for providers other than OpenAI. Without a key the OpenAI
+     * client falls back to OPENAI_API_KEY and would send it to that provider.
+     */
+    static _requiresApiKey: boolean;
+    /**
+     * Whether this service's API supports the "developer" message role.
+     *
+     * OpenAI's native API supports it, but some OpenAI-compatible services
+     * (e.g. Cerebras) do not. Subclasses that don't support it should set this
+     * to `false`, which causes the adapter to convert "developer" messages to
+     * "user" messages before sending them to the API.
+     */
+    static supportsDeveloperRole: boolean;
+    /**
+     * Whether the API can enforce a response schema. OpenAI-compatible services
+     * whose API cannot should set this to `false`.
+     */
+    static supportsResponseSchema: boolean;
+    protected _serviceTier: string | null;
+    protected _retryTimeoutSecs: number | null;
+    protected _retryOnTimeout: boolean | null;
+    protected _fullModelName: string;
+    protected _client: OpenAI;
+    /**
+     * Initialize the BaseOpenAILLMService.
+     *
+     * @param options.apiKey OpenAI API key. If null, uses environment variable.
+     * @param options.baseUrl Custom base URL for OpenAI API. If null, uses default.
+     * @param options.organization OpenAI organization ID.
+     * @param options.project OpenAI project ID.
+     * @param options.defaultHeaders Additional HTTP headers to include in requests.
+     * @param options.serviceTier Service tier to use (e.g., "auto", "flex", "priority").
+     * @param options.settings Runtime-updatable settings.
+     * @param options.retryTimeoutSecs 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.
+     * @param options.retryOnTimeout Whether to re-issue the request once if the
+     *   first attempt produces no output within `retryTimeoutSecs`. The retry
+     *   is unbounded.
+     *   Other options are passed to the parent LLMService.
+     * @throws Error If the service is for a provider other than OpenAI and
+     *   `apiKey` is empty (upstream: ValueError).
+     */
+    constructor(options?: BaseOpenAILLMServiceOptions);
+    /**
+     * Create an AsyncOpenAI client instance.
+     *
+     * @param options.apiKey OpenAI API key.
+     * @param options.baseUrl Custom base URL for the API.
+     * @param options.organization OpenAI organization ID.
+     * @param options.project OpenAI project ID.
+     * @param options.defaultHeaders Additional HTTP headers.
+     *   Other options are the service's constructor options, which subclasses
+     *   may read.
+     * @returns Configured AsyncOpenAI client instance.
+     */
+    createClient(options?: OpenAIClientOptions): OpenAI;
+    /**
+     * Check if this service can generate processing metrics.
+     *
+     * @returns True, as OpenAI service supports metrics generation.
+     */
+    canGenerateMetrics(): boolean;
+    /**
+     * Set the full AI model name.
+     *
+     * @param fullModelName The full name of the AI model to use.
+     */
+    setFullModelName(fullModelName: string): void;
+    /**
+     * Get the current full model name.
+     *
+     * @returns The full name of the AI model being used.
+     */
+    getFullModelName(): string;
+    /** Whether this service's API supports the "developer" message role. */
+    get supportsDeveloperRole(): boolean;
+    /**
+     * Turn request parameters into the JSON body to send: `extra_body` is
+     * merged in over the other fields, as the Python client does.
+     */
+    protected _requestBody(params: Record<string, any>): Record<string, any>;
+    /**
+     * Get streaming chat completions from OpenAI API with optional timeout and retry.
+     *
+     * @param context Context to use for the chat completion. Contains messages,
+     *   tools, and tool choice.
+     * @returns Async stream of chat completion chunks.
+     */
+    getChatCompletions(context: LLMContext): Promise<ChatCompletionStream>;
+    /**
+     * Build parameters for chat completion request.
+     *
+     * Subclasses can override this to customize parameters for different
+     * providers.
+     *
+     * @param paramsFromContext Parameters, derived from the LLM context, to use
+     *   for the chat completion. Contains messages, tools, and tool choice.
+     * @returns Dictionary of parameters for the chat completion request.
+     */
+    buildChatCompletionParams(paramsFromContext: OpenAILLMInvocationParams): Record<string, any>;
+    /**
+     * Add provider-specific fields to a request's `extra_body`.
+     *
+     * The OpenAI client rejects keyword arguments it doesn't know, so fields
+     * specific to an OpenAI-compatible provider travel in `extra_body`, which
+     * the client merges into the request JSON as-is.
+     *
+     * @param params Request parameters, updated in place. An `extra_body`
+     *   already there, supplied through `Settings.extra`, wins key by key,
+     *   matching how `extra` overrides every other request parameter. It is
+     *   copied rather than modified.
+     * @param fields Fields to add. Unset and null values are omitted.
+     */
+    static _mergeExtraBody(params: Record<string, any>, fields: Record<string, unknown>): void;
+    /**
+     * Whether a model can enforce a response schema.
+     *
+     * OpenAI models before gpt-4o-mini and gpt-4o-2024-08-06 cannot.
+     *
+     * @param model The model name.
+     */
+    static modelSupportsResponseSchema(model: string): boolean;
+    /**
+     * Run a one-shot, out-of-band (i.e. out-of-pipeline) inference with the
+     * given LLM context.
+     *
+     * @param context The LLM context containing conversation history.
+     * @param options.maxTokens Optional maximum number of tokens to generate. If
+     *   provided, overrides the service's default max_tokens /
+     *   max_completion_tokens setting.
+     * @param options.systemInstruction Optional system instruction to use for
+     *   this inference. If provided, overrides any system instruction in the
+     *   context.
+     * @param options.responseSchema Optional JSON schema the reply must follow.
+     *   The service asks the provider to enforce it, so the reply is JSON text
+     *   matching the schema.
+     * @returns The LLM's response as a string, or null if no response is
+     *   generated.
+     */
+    runInference(context: LLMContext, options?: {
+        maxTokens?: number | null;
+        systemInstruction?: string | null;
+        responseSchema?: Record<string, unknown> | null;
+    }): Promise<string | null>;
+    /**
+     * Convert a chat completion's usage into Pipecat's token usage.
+     *
+     * Follows OpenAI's convention, where `completion_tokens` includes the
+     * reasoning tokens reported in `completion_tokens_details`. Providers that
+     * report reasoning elsewhere, or apart from `completion_tokens`, override
+     * this.
+     *
+     * @param usage The usage reported with the completion.
+     * @returns The token usage to report.
+     */
+    protected _tokenUsage(usage: CompletionUsage): LLMTokenUsage;
+    protected _processContext(context: LLMContext): Promise<void>;
+    /**
+     * Process frames for LLM completion requests.
+     *
+     * Handles LLMContextFrame to trigger LLM completions.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+}
+export {};
+//# sourceMappingURL=base_llm.d.ts.map