@pipedog/core 0.0.0 → 0.2.0

package/dist/services/ultravox/index.d.ts

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

package/dist/services/ultravox/index.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/ultravox/__init__.py
+// Upstream's __init__.py is empty: it only marks the package. The provider
+// modules themselves live in their own packages (see porting/manifest.json).
+export {};
+//# sourceMappingURL=index.js.map

package/dist/services/vision_service.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Vision service implementation.
+ *
+ * Provides base classes and implementations for computer vision services that
+ * can analyze images and generate textual descriptions or answers to questions
+ * about visual content.
+ */
+import { type Frame, UserImageRawFrame } from "../frames/frames.ts";
+import type { FrameDirection } from "../processors/frame_processor.ts";
+import { AIService, type AIServiceOptions } from "./ai_service.ts";
+import { VisionSettings } from "./settings.ts";
+export interface VisionServiceOptions extends AIServiceOptions {
+    /** The runtime-updatable settings for the vision service. */
+    settings?: VisionSettings | null;
+}
+/**
+ * Base class for vision services.
+ *
+ * Provides common functionality for vision services that process images and
+ * generate textual responses. Handles image frame processing and integrates
+ * with the AI service infrastructure for metrics and lifecycle management.
+ */
+export declare abstract class VisionService extends AIService {
+    protected _settings: VisionSettings;
+    protected _describeText: string | null;
+    /**
+     * Initialize the vision service.
+     *
+     * @param options.settings The runtime-updatable settings for the vision
+     *   service. Other options are passed to the parent AIService.
+     */
+    constructor(options?: VisionServiceOptions);
+    /**
+     * Process the given vision image and generate results.
+     *
+     * This method must be implemented by subclasses to provide actual computer
+     * vision functionality such as image description, object detection, or
+     * visual question answering.
+     *
+     * @param frame The image frame to process.
+     * @returns Frames containing the vision analysis results, typically
+     *   TextFrame objects with descriptions or answers.
+     */
+    abstract runVision(frame: UserImageRawFrame): AsyncGenerator<Frame | null, void>;
+    /**
+     * Process frames, handling vision image frames for analysis.
+     *
+     * Automatically processes UserImageRawFrame objects by calling runVision and
+     * handles metrics tracking. Other frames are passed through unchanged.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+}
+//# sourceMappingURL=vision_service.d.ts.map

package/dist/services/vision_service.js

@@ -0,0 +1,62 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/services/vision_service.py
+/**
+ * Vision service implementation.
+ *
+ * Provides base classes and implementations for computer vision services that
+ * can analyze images and generate textual descriptions or answers to questions
+ * about visual content.
+ */
+import { UserImageRawFrame } from "../frames/frames.js";
+import { AIService } from "./ai_service.js";
+import { VisionSettings } from "./settings.js";
+/**
+ * Base class for vision services.
+ *
+ * Provides common functionality for vision services that process images and
+ * generate textual responses. Handles image frame processing and integrates
+ * with the AI service infrastructure for metrics and lifecycle management.
+ */
+export class VisionService extends AIService {
+    _describeText;
+    /**
+     * Initialize the vision service.
+     *
+     * @param options.settings The runtime-updatable settings for the vision
+     *   service. Other options are passed to the parent AIService.
+     */
+    constructor(options = {}) {
+        super({
+            ...options,
+            settings: options.settings ??
+                // Here in case subclass doesn't implement more specific settings
+                // (which hopefully should be rare)
+                new VisionSettings(),
+        });
+        this._describeText = null;
+    }
+    /**
+     * Process frames, handling vision image frames for analysis.
+     *
+     * Automatically processes UserImageRawFrame objects by calling runVision and
+     * handles metrics tracking. Other frames are passed through unchanged.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame processing.
+     */
+    async processFrame(frame, direction) {
+        await super.processFrame(frame, direction);
+        if (frame instanceof UserImageRawFrame && frame.text) {
+            await this.startProcessingMetrics();
+            await this.processGenerator(this.runVision(frame));
+            await this.stopProcessingMetrics();
+        }
+        else {
+            await this.pushFrame(frame, direction);
+        }
+    }
+}
+//# sourceMappingURL=vision_service.js.map

package/dist/services/websocket_service.d.ts

@@ -0,0 +1,213 @@
+import { ErrorFrame } from "../frames/frames.ts";
+import { type Ctor } from "../utils/mixin.ts";
+import { QuickFailureTracker } from "../utils/network.ts";
+/**
+ * Reports an error a websocket service ran into.
+ *
+ * Implemented by the owning service, which usually pairs pushing the error
+ * frame with a connection-error event of its own.
+ *
+ * - `error`: the error frame to report.
+ * - `forceTreatAsPermanent`: whether to treat the error as one that will keep
+ *   recurring, leaving the service unable to do any more work. Leaving it
+ *   false doesn't keep the service usable, since the error's own category may
+ *   cost it its usability.
+ */
+export type ReportErrorCallback = (error: ErrorFrame, options?: {
+    forceTreatAsPermanent?: boolean;
+}) => Promise<void>;
+/**
+ * Default ceiling, in seconds, on the websocket closing handshake. Disconnect
+ * runs while a service handles the EndFrame, before the frame continues
+ * downstream, so an unacknowledged close delays pipeline shutdown by this
+ * much. The `websockets` default of 10s is long enough to be noticeable once
+ * several websocket services tear down in sequence.
+ */
+export declare const WS_CLOSE_TIMEOUT = 2;
+/** Default time, in seconds, to wait for the opening handshake (as `websockets`). */
+export declare const WS_OPEN_TIMEOUT = 10;
+/** Connection state, with the values of `websockets.protocol.State`. */
+export declare const State: {
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+export type State = (typeof State)[keyof typeof State];
+/** Raised when reading from or writing to a closed connection. */
+export declare class ConnectionClosed extends Error {
+    name: string;
+    /** The close code, or null if no close frame was received. */
+    readonly code: number | null;
+    /** The close reason. */
+    readonly reason: string;
+    constructor(code: number | null, reason: string, message?: string);
+}
+/** The connection was closed normally (close code 1000 or 1001). */
+export declare class ConnectionClosedOK extends ConnectionClosed {
+    name: string;
+}
+/** The connection was closed with an error (abnormal close code, or none). */
+export declare class ConnectionClosedError extends ConnectionClosed {
+    name: string;
+}
+/** A message received from a websocket: text, or bytes for a binary frame. */
+export type WebsocketData = string | Uint8Array;
+export interface WebsocketConnectOptions {
+    /**
+     * Maximum time, in seconds, to wait for the peer to acknowledge the closing
+     * handshake before dropping the connection. Defaults to `WS_CLOSE_TIMEOUT`.
+     */
+    closeTimeout?: number | null;
+    /** Maximum time, in seconds, to wait for the opening handshake. */
+    openTimeout?: number | null;
+    /**
+     * Extra HTTP headers for the opening handshake (`additional_headers` in
+     * `websockets`). Supported by the Bun, Node (undici) and Deno `WebSocket`;
+     * on other runtimes pass a `webSocketFactory` that can send them.
+     */
+    additionalHeaders?: Record<string, string> | null;
+    /** Subprotocols to request. */
+    subprotocols?: string[] | null;
+    /**
+     * Creates the underlying `WebSocket`. Defaults to the global `WebSocket`.
+     * Use it on runtimes that open websockets differently (e.g. Cloudflare
+     * Workers, through `fetch` with an `Upgrade` header).
+     */
+    webSocketFactory?: ((uri: string, options: {
+        headers?: Record<string, string>;
+        protocols?: string[];
+    }) => WebSocket | Promise<WebSocket>) | null;
+}
+/**
+ * A websocket client connection with the asyncio-style API of the
+ * `websockets` library, over a standard `WebSocket`.
+ *
+ * Received messages are buffered until read with `recv()` or `for await`.
+ * Binary messages are returned as `Uint8Array`.
+ */
+export declare class WebsocketClientConnection {
+    #private;
+    /** Maximum time, in seconds, to wait for the peer to acknowledge a close. */
+    closeTimeout: number | null;
+    constructor(ws: WebSocket, options?: {
+        closeTimeout?: number | null;
+    });
+    /** The underlying `WebSocket`. */
+    get webSocket(): WebSocket;
+    /** The connection state. */
+    get state(): State;
+    /** The close code, once the connection is closed. */
+    get closeCode(): number | null;
+    /** The close reason, once the connection is closed. */
+    get closeReason(): string | null;
+    /**
+     * Send a text (string) or binary (bytes) message.
+     *
+     * @throws ConnectionClosed if the connection is closing or closed.
+     */
+    send(message: WebsocketData | ArrayBuffer): Promise<void>;
+    /**
+     * Receive the next message. A cancellation point.
+     *
+     * @throws ConnectionClosedOK / ConnectionClosedError once the connection
+     *   is closed and every buffered message has been read.
+     */
+    recv(): Promise<WebsocketData>;
+    /**
+     * Iterate over incoming messages. Ends when the connection closes normally;
+     * throws `ConnectionClosedError` when it closes with an error.
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<WebsocketData, void, unknown>;
+    /**
+     * Check the connection is alive.
+     *
+     * The standard `WebSocket` API cannot send ping frames (runtimes answer the
+     * peer's pings themselves), so this only checks the connection is open.
+     *
+     * @throws ConnectionClosed if the connection is closing or closed.
+     */
+    ping(): Promise<void>;
+    /**
+     * Perform the closing handshake, waiting at most `closeTimeout` seconds for
+     * the peer to acknowledge it. Logs if the peer never acknowledged it, which
+     * keeps a teardown that silently cost `closeTimeout` from going unnoticed.
+     *
+     * @param code WebSocket close code.
+     * @param reason WebSocket close reason.
+     */
+    close(code?: number, reason?: string): Promise<void>;
+}
+/**
+ * Open a websocket connection (`websockets.asyncio.client.connect`).
+ * Waiting for the opening handshake is a cancellation point; a cancelled or
+ * timed-out attempt closes the socket.
+ *
+ * @param uri The websocket URI to connect to.
+ * @returns The connected websocket.
+ */
+export declare function websocketConnect(uri: string, options?: WebsocketConnectOptions): Promise<WebsocketClientConnection>;
+export interface WebsocketServiceOptions {
+    /** Minimum time, in seconds, to wait between reconnection attempts. */
+    reconnectBackoffMinWait?: number;
+    /** Maximum time, in seconds, to wait between reconnection attempts. */
+    reconnectBackoffMaxWait?: number;
+    /** Whether to automatically reconnect on connection errors. */
+    reconnectOnError?: boolean;
+    /**
+     * Maximum time, in seconds, to wait for the peer to acknowledge the
+     * websocket closing handshake before dropping the connection. Applied to
+     * connections opened through `_websocketConnect()`. Increase it for peers
+     * that need longer to complete a graceful close.
+     */
+    wsCloseTimeout?: number;
+}
+/** Members a class gets from the `WebsocketService` mixin. */
+export interface WebsocketService {
+    _websocket: WebsocketClientConnection | null;
+    _reconnectBackoffMinWait: number;
+    _reconnectBackoffMaxWait: number;
+    _reconnectOnError: boolean;
+    _wsCloseTimeout: number;
+    _reconnectInProgress: boolean;
+    _disconnecting: boolean;
+    _quickFailureTracker: QuickFailureTracker;
+    _lastConnectTime: number;
+    readonly _isServiceUsable: boolean;
+    _websocketConnect(uri: string, options?: WebsocketConnectOptions): Promise<WebsocketClientConnection>;
+    _verifyConnection(): Promise<boolean>;
+    _reconnectWebsocket(attemptNumber: number): Promise<boolean>;
+    _tryReconnect(options?: {
+        maxRetries?: number;
+        reportError?: ReportErrorCallback | null;
+    }): Promise<boolean>;
+    sendWithRetry(message: WebsocketData, reportError: ReportErrorCallback): Promise<void>;
+    _maybeTryReconnect(errorMessage: string, reportError: ReportErrorCallback, error?: unknown): Promise<boolean>;
+    _receiveTaskHandler(reportError: ReportErrorCallback): Promise<void>;
+    _connect(): Promise<void>;
+    _disconnect(): Promise<void>;
+    _connectWebsocket(): Promise<void>;
+    _disconnectWebsocket(): Promise<void>;
+    _receiveMessages(): Promise<void>;
+}
+/**
+ * Base class for websocket-based services with automatic reconnection.
+ *
+ * Provides websocket connection management, automatic reconnection with
+ * exponential backoff, connection verification, and error handling.
+ * Subclasses implement service-specific connection and message handling
+ * logic (`_connectWebsocket()`, `_disconnectWebsocket()`, `_receiveMessages()`).
+ *
+ * Reconnection gives up in two ways, both leaving the service unusable: the
+ * provider rejects the configuration, which no amount of retrying will fix,
+ * or the attempts are exhausted. Errors are reported through a `reportError`
+ * callback, which takes the same optional `forceTreatAsPermanent` flag as
+ * `FrameProcessor.pushErrorFrame()`, so that giving up and saying so are the
+ * same act.
+ *
+ * A mixin: `class MyService(TTSService, WebsocketService)` upstream is
+ * `class MyService extends WebsocketService(TTSService)` here. Its options
+ * (`WebsocketServiceOptions`) are read from the constructor's options object.
+ */
+export declare const WebsocketService: import("../utils/mixin.ts").Mixin<<B extends Ctor>(base: B) => B & (abstract new (...args: any[]) => WebsocketService), WebsocketService>;
+//# sourceMappingURL=websocket_service.d.ts.map