@pipedog/core 0.0.0 → 0.2.0

package/dist/processors/frameworks/rtvi/processor.d.ts

@@ -0,0 +1,182 @@
+/**
+ * RTVIProcessor: main RTVI protocol processor.
+ *
+ * Porting notes:
+ * - Deprecated upstream APIs are not ported: the `transport` constructor
+ *   option (ignored upstream) and `handleFunctionCall()` (superseded by
+ *   `RTVIObserver`'s `llm-function-call-in-progress` events).
+ * - Pydantic models from `models.ts` are dumped to their wire form with
+ *   `modelDump({ excludeNone })` and parsed with `Model.modelValidate(obj)`.
+ * - `ErrorFrame.fatal` is deprecated upstream and not ported, so RTVI `error`
+ *   messages always carry `fatal: false`.
+ */
+import { Queue, type Task } from "@pipedog/asyncio";
+import { CancelFrame, EndFrame, ErrorFrame, type Frame, InputTransportMessageFrame, StartFrame } from "../../../frames/frames.ts";
+import { type FrameDirection, FrameProcessor, type FrameProcessorOptions } from "../../frame_processor.ts";
+import * as RTVI from "./models.ts";
+import { RTVIObserver, type RTVIObserverOptions } from "./observer.ts";
+/**
+ * Any RTVI model (a pydantic `BaseModel` upstream) that can be dumped to its
+ * wire form.
+ */
+export interface RTVIModelLike {
+    modelDump(options?: {
+        excludeNone?: boolean;
+    }): Record<string, unknown>;
+}
+/**
+ * Whether `e` is a model validation error (pydantic's `ValidationError`
+ * upstream; a `ValidationError` or `ZodError` here).
+ */
+export declare function isValidationError(e: unknown): boolean;
+/** Options for `RTVIProcessor`. */
+export interface RTVIProcessorOptions extends FrameProcessorOptions {
+}
+/**
+ * Main processor for handling RTVI protocol messages and actions.
+ *
+ * This processor manages the RTVI protocol communication including
+ * client-server handshaking, configuration management, action execution, and
+ * message routing. It serves as the central hub for RTVI protocol operations.
+ *
+ * Event handlers available:
+ *
+ * - on_bot_started
+ * - on_client_ready
+ * - on_client_message: called with an `RTVI.ClientMessage`
+ * - on_ui_message: called with an `RTVI.UIEventMessage`,
+ *   `RTVI.UISnapshotMessage` or `RTVI.UICancelJobGroupMessage`
+ */
+export declare class RTVIProcessor extends FrameProcessor {
+    protected _botReady: boolean;
+    protected _clientReady: boolean;
+    protected _clientReadyId: string;
+    protected _clientVersion: number[];
+    protected _llmSkipTts: boolean;
+    protected _messageTask: Task<unknown> | null;
+    protected _messageQueue: Queue<[RTVI.Message, string | null]>;
+    /**
+     * Initialize the RTVI processor.
+     *
+     * @param options Options passed to the parent class.
+     */
+    constructor(options?: RTVIProcessorOptions);
+    /**
+     * The negotiated client protocol version as [major, minor, patch].
+     *
+     * Defaults to [0, 0, 0] until the client sends a `client-ready` message.
+     */
+    get clientVersion(): number[];
+    /**
+     * Creates a new RTVI Observer.
+     *
+     * @param options.params Settings to enable/disable specific messages.
+     *   Other options are passed to the observer.
+     * @returns A new RTVI observer.
+     */
+    createRtviObserver(options?: RTVIObserverOptions): RTVIObserver;
+    /** Mark the client as ready and trigger the ready event. */
+    setClientReady(): Promise<void>;
+    /**
+     * Mark the bot as ready and send the bot-ready message.
+     *
+     * @param about Optional information about the bot to include in the ready
+     *   message. If left as null, the Pipecat library and version will be used.
+     */
+    setBotReady(about?: Record<string, unknown> | null): Promise<void>;
+    /** Send a bot interruption frame upstream. */
+    interruptBot(): Promise<void>;
+    /** Send a server message to the client. */
+    sendServerMessage(data: unknown): Promise<void>;
+    /** Send a server response for a given client message. */
+    sendServerResponse(clientMsg: RTVI.ClientMessage, data: unknown): Promise<void>;
+    /** Send an error response for a given client message. */
+    sendErrorResponse(clientMsg: RTVI.ClientMessage, error: string): Promise<void>;
+    /**
+     * Send an error message to the client.
+     *
+     * @param error The error message to send.
+     */
+    sendError(error: string): Promise<void>;
+    /** Push a transport message frame. */
+    pushTransportMessage(model: RTVIModelLike, excludeNone?: boolean): Promise<void>;
+    /**
+     * Handle an incoming RTVI message.
+     *
+     * @param message The RTVI message to handle.
+     * @param userId Identifier for the user who sent it, if known.
+     */
+    handleMessage(message: RTVI.Message, userId?: string | null): Promise<void>;
+    /**
+     * Process incoming frames through the RTVI processor.
+     *
+     * @param frame The frame to process.
+     * @param direction The direction of frame flow.
+     */
+    processFrame(frame: Frame, direction: FrameDirection): Promise<void>;
+    /** Release resources held by the processor. */
+    cleanup(): Promise<void>;
+    /** Start the RTVI processor tasks. */
+    protected _start(_frame: StartFrame): Promise<void>;
+    /** Stop the RTVI processor tasks. */
+    protected _stop(_frame: EndFrame): Promise<void>;
+    /** Cancel the RTVI processor tasks. */
+    protected _cancel(_frame: CancelFrame): Promise<void>;
+    /** Cancel all running tasks. */
+    protected _cancelTasks(): Promise<void>;
+    /** Handle incoming transport messages. */
+    protected _messageTaskHandler(): Promise<void>;
+    /** Handle an incoming transport message frame. */
+    protected _handleTransportMessage(frame: InputTransportMessageFrame): Promise<void>;
+    /** Handle a parsed RTVI message. */
+    protected _handleMessage(message: RTVI.Message, userId?: string | null): Promise<void>;
+    /** Handle the client-ready message from the client. */
+    protected _handleClientReady(requestId: string, data: RTVI.ClientReadyData | null): Promise<void>;
+    /**
+     * Handle incoming audio buffer data.
+     *
+     * The RTVIProcessor is prepended to the very top of the pipeline, so
+     * pushing `InputAudioRawFrame` downstream reaches the input transport,
+     * which feeds it through its VAD/processing path. Frame-based so we don't
+     * hold a transport reference.
+     */
+    protected _handleAudioBuffer(data: unknown): Promise<void>;
+    /**
+     * Handle DTMF keypresses from the client.
+     *
+     * Like `_handleAudioBuffer`, the RTVIProcessor sits at the top of the
+     * pipeline, so pushing `InputDTMFFrame` downstream reaches the input
+     * transport and the bot's DTMF handling exactly as a telephony transport's
+     * keypresses would. A multi-key sequence is pushed as one frame per key,
+     * in order.
+     */
+    protected _handleDtmf(data: RTVI.DTMFInputData): Promise<void>;
+    /** Handle a send-text message from the client. */
+    protected _handleSendText(data: RTVI.SendTextData, messageId: string, userId?: string | null): Promise<void>;
+    /**
+     * Handle a send-file message from the client.
+     *
+     * Validation and framing only: a URL source is passed through unresolved,
+     * and whether the LLM provider fetches it itself or the LLM service's
+     * `FileResolver` downloads it is decided at completion time.
+     */
+    protected _handleSendFile(data: RTVI.SendFileData, messageId: string): Promise<void>;
+    /** Handle a client message frame. */
+    protected _handleClientMessage(msgId: string, data: RTVI.RawClientMessageData): Promise<void>;
+    /** Handle a function call result from the client. */
+    protected _handleFunctionCallResult(data: RTVI.LLMFunctionCallResultData): Promise<void>;
+    /**
+     * Send the bot-ready message to the client.
+     *
+     * @param about Optional information about the bot to include in the ready
+     *   message. If left as null, the pipecat library and version will be used.
+     */
+    protected _sendBotReady(about?: Record<string, unknown> | null): Promise<void>;
+    /** Send a message or response to the client. */
+    protected _sendServerMessage(message: RTVI.ServerMessage | RTVI.ServerResponse): Promise<void>;
+    /** Send an error frame as an RTVI error message. */
+    protected _sendErrorFrame(frame: ErrorFrame): Promise<void>;
+    /** Send an error response message. */
+    protected _sendErrorResponse(id: string, error: string): Promise<void>;
+}
+//# sourceMappingURL=processor.d.ts.map